[Design Discussion] Adding AuthZEN-Compatible Access Evaluation APIs to ThunderID

[Yathusiga27]

Related Feature Issue

#2575

Problem Summary

ThunderID currently supports a coarse-grained authorization model that is used mainly for internal evaluation flows, such as login flow authorization and OAuth client credentials scope filtering. In this model, internal callers provide a list of requested permissions or scopes and receive the subset that the subject is authorized to use.

This creates two limitations. First, ThunderID does not currently expose its authorization decision capability through a standard API for external parties or trusted applications. Second, the current model is not a fine-grained access control model, because it focuses on filtering permissions rather than evaluating a specific subject-resource-action request.

The proposed AuthZEN-based design introduces a fine-grained access evaluation model. Instead of only asking “which permissions from this list are allowed?”, a caller can ask “can this subject perform this action on this resource?” using subject, resource, action, and optional context, and receive an allow/deny decision.

High-Level Approach

The proposed approach is to add a new authzen package that exposes AuthZEN-style HTTP endpoints and translates those requests into ThunderID’s internal authorization model.
Instead of keeping the core authorization service centered around GetAuthorizedPermissions, the design moves toward explicit access evaluation:

                       subject + resource server + permission + context  → decision

The external AuthZEN API still uses the standard subject, resource, action, and context shape. Internally, ThunderID maps that model to its existing resource server and permission model.

The existing RBAC remains the decision engine, but the interface is extendable for future decision engines too(e.g. ABAC, external PDPs). For compatibility with ThunderID’s current resource server model, the AuthZEN action.name field is treated as the full registered permission string from ThunderID’s resource server model. No permission transformation is required.

                               action.name = "booking:read"

The RBAC engine evaluates this permission directly against the subject’s assigned roles as done currently.

Architecture Overview

The AuthZEN adapter maps:

AuthZEN subject       -> authz.Subject
AuthZEN resource.type -> authz.ResourceServer.Handle
AuthZEN action.name   -> authz.Permission.Name
AuthZEN context       -> authz.Context

AuthZEN to ThunderID Model Mapping:

The AuthZEN request keeps the standard subject/resource/action/context structure, but the fields are interpreted according to ThunderID’s existing authorization model.

• subject.id
  Identifies the entity whose access is being evaluated. ThunderID uses this ID to resolve group memberships and role assignments.

• resource.type
  Represents the ThunderID resource server handle, for example booking. ThunderID resolves this handle to the internal resource server ID and uses it to validate that action.name is a registered permission under that resource server.

• action.name
  Carries the full registered ThunderID permission string, for example booking:read. This value is mapped internally to Permission.Name, passed to the RBAC engine, and checked against the subject’s assigned roles.

• context
  Carries optional request context for future policy engines or additional validation. The initial RBAC implementation does not rely on context for the final decision.

• subject.type
  Accepted as part of the AuthZEN subject model and preserved in the internal authorization request. It can be used to distinguish entity categories such as user, application, or agent. The current RBAC decision is still based on the subject ID, resolved groups, and assigned roles.

• subject.properties
  Preserved for future policy engines such as ABAC. The current RBAC implementation does not use subject properties for the decision.

• resource.id
  Accepted as part of the AuthZEN resource model and reserved for future instance-based authorization. The current RBAC implementation does not use it for the authorization decision.

• resource.properties
  Preserved for future policy engines. The current RBAC implementation does not use resource properties for the decision.

• action.properties
  Preserved for future policy engines. The current RBAC implementation does not use action properties for the decision.

Authz Service Interface Before vs Proposed:

Before:

The previous authorization service interface was permission-list based:

type AuthorizationServiceInterface interface {
	GetAuthorizedPermissions(
		ctx context.Context,
		request GetAuthorizedPermissionsRequest,
	) (*GetAuthorizedPermissionsResponse, *serviceerror.ServiceError)
}

The request model was:

type GetAuthorizedPermissionsRequest struct {
	EntityID             string
	GroupIDs             []string
	RequestedPermissions []string
}

The response model was:

type GetAuthorizedPermissionsResponse struct {
	AuthorizedPermissions []string
}

Proposed:

The proposed authorization service interface is access-evaluation based:

type AuthorizationServiceInterface interface {
	EvaluateAccess(
		ctx context.Context,
		request AccessEvaluationRequest,
	) (*AccessEvaluationResponse, *serviceerror.ServiceError)

	EvaluateAccessBatch(
		ctx context.Context,
		request AccessEvaluationsRequest,
	) (*AccessEvaluationsResponse, *serviceerror.ServiceError)
}

The request model is:

type AccessEvaluationRequest struct {
	Subject  Subject
	ResourceServer ResourceServer
	Permission     Permission
	Context  map[string]interface{}
}

The response model is:

type AccessEvaluationResponse struct {
	Decision bool
}

Batch evaluation uses:

type AccessEvaluationsRequest struct {
	Evaluations []AccessEvaluationRequest
}

type AccessEvaluationsResponse struct {
	Evaluations []AccessEvaluationResponse
}

The proposed interface changes the authorization service from returning an authorized list of permissions to evaluating explicit access requests. This aligns the internal service contract with AuthZEN’s subject/resource/action/context model while keeping batch evaluation support for existing OAuth and flow authorization use cases.

Impacted Areas

• Authorization service and engine interfaces
• RBAC engine implementation
• OAuth client credentials scope filtering
• Flow authorization executor
• AuthZEN API adapter, routes, models, validation, and error responses

Alternatives Considered

Option 1:
Keep existing GetAuthorizedPermissions and add AuthZEN as a thin wrapper
This would minimize internal changes, but the core authorization model would remain permission-list based. The AuthZEN layer would need to convert every access evaluation into permission filtering, which makes the design less natural for future policy engines.

Option 2:
Implement AuthZEN directly on top of the role service
This is simpler for the current RBAC implementation, but it bypasses the authorization service and engine abstraction. That would make future authorization models harder to support.

Questions for Community Input

The initial implementation doesn’t consider the following in the evaluation decision since ThunderID doesn’t support these as of now:

1. Client subscription/ceiling on resource-server
2. Native resource type support
3. Instance-based authorization

The interface is designed to be extended when this needs to be supported. Please let know if there are any other requirements that need to be considered if we are to add this support in the future?

[Yathusiga27]

Implementation Update

Most of the original design remains the same. During implementation, we made one model alignment to better fit ThunderID’s current resource server and permission model.

The external AuthZEN API still follows the standard shape:

subject + resource + action + context -> decision

Internally, ThunderID maps the request as follows:

AuthZEN subject       -> authz.Subject
AuthZEN resource.type -> authz.ResourceServer.Handle
AuthZEN action.name   -> authz.Permission.Name
AuthZEN context       -> authz.Context

The main implementation detail is that resource.type is treated as the ThunderID resource server handle. The adapter resolves this handle to the internal resource server ID and validates that action.name is a registered permission under that resource server.

action.name is treated as the full registered ThunderID permission string and is passed directly to the RBAC engine through authz.Permission.Name. The RBAC engine does not derive or transform permissions from the resource fields.

resource.id is currently accepted but reserved for future instance-based authorization. subject.type is optional; when provided, it can identify the subject entity category, such as user, application, or agent. The subject, resource, and action properties are preserved for future policy engines such as ABAC, but they are not used by the current RBAC decision.

Difference from the AuthZEN Access Request and Approval Profile

The AuthZEN Access Request and Approval Profile defines approval workflow capabilities on top of access evaluation, such as requestable denials, access request endpoints, task handles, callbacks or polling, approval result binding, and re-evaluation after approval.

The current ThunderID implementation does not implement that approval workflow profile yet. It currently supports access evaluation and action search only.

Out of scope for the current implementation:

• access_request_endpoint
• context.access_request
• requestable denial responses
• task status endpoint
• approval task handles
• approval callbacks or polling
• approval result binding
• jwks_uri for signed binding tokens
• re-evaluation after approval
• search_subject_endpoint
• search_resource_endpoint

The current metadata therefore advertises only the implemented evaluation/search endpoints, not the access request approval profile metadata. The approval/requestable-denial workflow can be considered separately as a future extension.

[Yathusiga27]

Implementation Update

We changed AuthZEN endpoint protection to use Direct Auth Secret instead of requiring a system-scope access token.

The external AuthZEN API still follows the standard shape:

subject + resource + action + context -> decision

Internally, ThunderID maps the request as follows:

AuthZEN subject       -> authz.Subject
AuthZEN resource.type -> resource server identifier
AuthZEN action.name   -> authz.Permission.Name
AuthZEN context       -> authz.Context

The main implementation detail is that resource.type represents the ThunderID resource server identifier. The AuthZEN adapter resolves this identifier to the internal resource server ID and validates that action.name is a registered permission under that resource server.

AuthZEN evaluation endpoints are protected using the Direct Auth Secret mechanism. Callers such as the Wayfinder backend send the configured secret in the Direct-Auth-Secret header when calling /access/v1/evaluation.