[Design Discussion] External AuthZEN PDP Evaluation

[Yathusiga27]

Related Feature Issue

#2209
#5151

Problem Summary

ThunderID currently evaluates authorization using its built-in RBAC. This presents two limitations:

• Fine-grained authorization: Role-based permissions alone cannot express decisions that depend on subject attributes, resource attributes, or request context.
• Policy duplication: Enterprises that already use centralized Policy Decision Points must duplicate and maintain authorization rules inside ThunderID.

This design allows ThunderID to route authorization evaluations to an external AuthZEN-compatible PDP. It supports both token issuance decisions and AuthZEN authorization requests received by ThunderID from external Policy Enforcement Points.

High-Level Approach

• Add generic support for AuthZEN-compatible PDPs.
• Model external AuthZEN PDPs as ThunderID Connections.
• Configure the PDP using single and batch evaluation endpoints.
• Allow each Resource Server to select RBAC or a configured AuthZEN PDP.
• Route authorization requests to the configured external PDP.
• Apply permitted actions to token scopes during token issuance.
• Return external PDP decisions to callers using ThunderID’s AuthZEN endpoint.
• Log external evaluation results.
• Support exporting AuthZEN PDP connections with the existing connection export.

Architecture Overview

Components:

• AuthZEN Request Endpoint: Receives authorization requests from external PEPs.
• Token Issuance Flow: Receives token requests and determines the requested permissions.
• Authorization Router: Selects the authorization engine configured for the Resource Server.
• External AuthZEN Adapter: Converts ThunderID authorization requests into AuthZEN HTTP requests.
• External AuthZEN PDP: Evaluates the request using its own policies and returns permit or deny decisions.
• AuthZEN Connection Configuration: Stores the PDP name, single and batch evaluation endpoints, subject attribute mappings, and authentication method.

External PEP Authorization Flow

sequenceDiagram
    participant PEP as External PEP
    participant ThunderID
    participant PDP as External AuthZEN PDP

    PEP->>ThunderID: AuthZEN evaluation request
    ThunderID->>PDP: AuthZEN evaluation request
    PDP-->>ThunderID: Permit or deny decision
    ThunderID-->>PEP: AuthZEN evaluation response
    PEP->>PEP: Enforce decision

Loading

1. An external PEP sends an AuthZEN evaluation request to ThunderID.
2. ThunderID identifies the target Resource Server from the request.
3. ThunderID checks the authorization engine configured for that Resource Server.
4. If RBAC is selected, ThunderID evaluates the request using the selected built-in engine.
5. If an external AuthZEN PDP is selected, ThunderID routes the request to that PDP.
6. The external PDP evaluates the request using its own policies.
7. The external PDP returns a permit or deny decision.
8. ThunderID returns the decision to the external PEP.

Token Issuance Flow

sequenceDiagram
    participant User
    participant ThunderID as ThunderID (PEP)
    participant PDP as External AuthZEN PDP

    User->>ThunderID: Request token during login
    ThunderID->>PDP: Send AuthZEN evaluations for candidate scopes
    PDP->>PDP: Evaluate each action for the user
    PDP-->>ThunderID: Return authorization decisions
    ThunderID->>ThunderID: Enforce decisions and include allowed scopes
    ThunderID-->>User: Issue token with allowed scopes

Loading

1. A client requests a token from ThunderID.
2. ThunderID identifies the subject, Resource Server, and requested permissions.
3. The Authorization Router selects the engine configured for the Resource Server.
4. If an external AuthZEN PDP is configured, ThunderID creates AuthZEN evaluations.
5. Multiple requested permissions may be sent as one batch evaluation.
6. The external PDP returns a decision for each permission.
7. ThunderID includes only permitted permissions in the issued token scope.

AuthZEN Request Mapping
ThunderID maps its internal authorization model to the AuthZEN request format.
Subject:

• Subject identifier.
• Subject type
• Selected user attributes configured in the AuthZEN PDP connection.

Resource:

• Resource type mapped to Resource Server identifier.

Action:

• Requested permission, such as booking:read or booking:create.

The current token-issuance implementation does not enrich resource-instance data such as booking status, booking owner, departure time, or region from an application database.
Therefore, policies that require resource-instance attributes are outside the current ThunderID token-issuance.

AuthZEN External PDP Connection Configuration

Sample UI for Connection

External PDPs are configured from the Connections page.
Each connection includes:

• Connection name.
• AuthZEN single and batch evaluation endpoints.
• Subject attribute selection.
• PDP attribute-name mapping.

Sample UI for Resource Server Configuration

Each Resource Server can select its authorization engine from the Advanced tab.
Available options include:

• RBAC, the default engine.
• Configured AuthZEN PDP connections.

The dropdown displays the names of configured PDP connections.
The selected engine is used for:

• AuthZEN requests received by ThunderID.
• Authorization checks during token issuance.

Response Handling
When the PDP permits an action: ThunderID includes that permission in the issued token scope.
When the PDP denies an action: ThunderID excludes that permission from the issued token scope.
If the PDP denies all requested permissions, the token may be issued without those permissions according to the current token flow behavior.
If the PDP cannot be reached or returns an error:

• The evaluation error is propagated to token issuance.
• The current behavior is fail-closed.

Security Considerations

• Use HTTPS, mTLS, or equivalent service authentication for production PDPs.
• Store PDP credentials securely when runtime authentication is implemented.
• Validate PDP evaluation endpoints and responses before applying decisions.
• Send only the configured subject attributes to the PDP.
• Review and control policies through the external PDP’s policy-management process.

Impacted Areas

• Authorization engine and routing.
• OAuth token issuance.
• Authorization Code flow.
• Client Credentials flow.
• Resource Server configuration.
• AuthZEN PDP connection management.
• Subject attribute mapping.
• Connection import and export.
• Error handling.
• Integration and unit tests.

Alternatives Considered

Provider-Specific Adapters
Create a separate ThunderID adapter for each external PDP provider, such as Cerbos, OPA, or another authorization service.
Pros:

• Supports provider-specific features.
• Can integrate with PDPs that do not support AuthZEN.
• Allows direct use of native provider APIs.

Cons:

• Requires a separate adapter for each provider.
• Increases maintenance and testing effort.
• Creates vendor-specific coupling.
• Makes switching PDP providers more difficult.

Questions for Community Input

1. Should external PDP routing continue to be based on Resource Server, or should future versions also support client, user type, or organization-based routing?
2. Should fail-open behavior ever be supported?
3. What authentication methods should we support for external PDP connections, such as bearer tokens, API keys, basic authentication?

[Thumimku]

Hi,

we need to have samples and try outs of integrating popular authZEN compliant PDP vendor. can we consider enriching the tokens with claims also?

[Yathusiga27]

We’ll include a reference integration and try-out sample for a popular AuthZEN compatible PDP (Eg:- Cerbos, OpenFGA), as part of the implementation documentation.
Regarding claims, the AuthZEN response provides an authorization decision, not arbitrary token claims. We can consider adding explicitly configured ThunderID claims about the evaluation, such as the authorized scopes or decision source. We’ll define the claim format separately in a follow-up.

[thiva-k]

For federated subjects, the identifier ThunderID holds may not be the one the PDP knows. A locally provisioned user has a ThunderID UUID, while PDP policies are usually written against the provider's sub or email etc. With no local record, as in token exchange, there is no ThunderID identifier at all.

Can we make the Authzen subject id in the constructed request be optionally configurable from the attributes, at the connection-level?

[Yathusiga27]

We’ll make subject.id configurable per connection, pointing to a chosen trusted attribute, such as the provider’s sub or email, instead of always using ThunderID’s internal UUID.

[Yathusiga27]

Summary of Discussion (14/09/2026)

Participants: @darshanasbg @Thumimku @thiva-k @Yathusiga27

Notes:

• The proposed External AuthZEN PDP design was reviewed and agreed upon.
• It was decided to discuss the proposed Console experience with @jeradrutnam and obtain a UI/UX review.
• The UI will be updated based on the feedback from the UI/UX review.

[Yathusiga27]

Summary of Discussion (17/09/2026)

Participants: @jeradrutnam @NipuniBhagya @Thumimku @thiva-k @Yathusiga27

Notes:

• Rename the connection name from AuthZEN to Policy Decision Point (PDP).
• Under Policy Decision Point, display protocol cards.
• Add AuthZEN as a protocol card.
• Use the navigation flow:
  Connections → Policy Decision Point → AuthZEN → Connection Configuration
• Rename the resource-server authorization engine option from RBAC to Local.
• Rename the Connection Details section to Connection Configuration.
• Move authentication settings into a separate card or tab.