Extending RBAC support for entity model

[thiva-k]

1. Current state

Thunder currently implements RBAC for users and groups. A role is a collection of permissions drawn from one or more registered resource servers. Roles are assigned to users or groups, and when a user authenticates, their roles are resolved, the associated permissions are collected, and those permissions are included in the issued token as scopes. (scopes == permissions)

This model works correctly for human principals but does not extend to non-human entities. As Thunder evolves toward a unified entity model, Applications and Agents will also share the same RBAC foundation.

---

2. Current limitations

• M2M tokens carry no enforced permissions — any application can claim any scope string in a client credentials token with no validation.
• No authorization boundary in delegated flows — a subscribed app can surface any permission the user holds; there is no application-level cap/ceiling on what scopes flow into delegated tokens.
• No audit trail of application authorization — currently which applications are permitted to access a given resource server(or permissions in a RS) cannot be answered.
• RFC 8707 resource parameter is not used — without application authorization, the resource parameter only determines the token's aud claim and has no effect on what the app is permitted to request.

---

3. Entity unification

The long-term direction for Thunder is a unified entity model where Users, Applications, and Agents share a common base with credentials, lifecycle state, and RBAC support. The RBAC system must accept any entity type as a principal — not just users and groups. (#948)

Agent authorization requirements share similar requirements to application authorization — both can use client credentials for autonomous M2M access and authorization code for delegated access on behalf of users. App RBAC is a prerequisite of entity unification; agent RBAC could follow as a direct extension of the same model without additional architectural changes.

---

4. How other vendors handle this

Auth0

Applications are granted an explicit scope list per API through a "Client Grant" object. User RBAC and application authorization are entirely separate systems using the same scope strings in different contexts. For M2M flows, every application must explicitly authorize each API — no Client Grant means no access. Auth code flows are open by default; the same grant mechanism can optionally enforce a per-application scope ceiling on delegated flows when required.

Keycloak

Every OAuth client can enable a service account — a synthetic user entity assigned roles exactly like a human user. Client credentials tokens are issued by resolving this service account's roles. For auth code flows, the token reflects the authenticating user's own roles — the service account's assignments have no effect on delegated tokens.

IS / Asgardeo

Applications authorize API resources via an "Authorized APIs" configuration, selecting a scope allowlist per (app, API) pair. Auth code tokens are the intersection of the user's RBAC permissions and the app's authorized scopes. M2M tokens use the same authorized scope list as the direct grant — no separate RBAC mechanism. Because the same scope list serves both flows, configuring auth code delegation automatically makes those scopes available for autonomous M2M access, requiring to explicitly restrict which grant types are permitted to prevent unintended access.

---

5. Proposed models

Model 1 — Unified RBAC

Applications are assigned roles, similar to users. Auth code tokens are the intersection of user RBAC and app RBAC permissions. M2M tokens use app RBAC directly.

Auth Code:  finalPerms = INTERSECT(user RBAC perms, app RBAC perms)
M2M:        finalPerms = app RBAC perms

Pros: Single RBAC system, consistent mental model for admins.

Cons: The same role assignment serves both delegation and autonomous purposes simultaneously. An app assigned orders:read to participate in auth code flows also holds orders:read for autonomous M2M access. Permission bleed is structural, not the result of misconfiguration.

---

Model 2 — Subscription Gate + RBAC (preferred)

A subscription table, managed by the resource server, gates which apps and agents can access it. The subscription is a pure access gate — it carries no permission strings. It just enforces whether an app/agent can access the specific resource server. Auth code permissions come from user RBAC; M2M permissions come from app RBAC. The two mechanisms are fully independent. Both the subscription lookup and RBAC scoping are keyed to the resource server identified by the RFC 8707 resource parameter in the token request.

Auth Code:  subscription gate → user RBAC → token
M2M:        subscription gate → app RBAC  → token

Pros: Subscription carries no permission strings — zero shared data between auth code and M2M paths; no bleed by design. Resource server owner has full control over who can access it, at whatever granularity the RS requires.

Cons: M2M with role-based access requires both a subscription record in the RS-side and role assignments — two setup steps coordinated between the resource server owner and the role admin.

---

Model 3 — Permission Allowlist per App/Agent

The subscription record at resource server carries authorized permissions(/scopes) per App/Agent. Auth code tokens are the intersection of user RBAC permissions and the app's authorized permissions. M2M tokens use the permission allowlist as the direct grant.

Auth Code:  finalPerms = user RBAC ∩ app's authorized permissions
M2M:        finalPerms = app's authorized permissions

Pros: Resource server level permission ceiling per app in auth code flows.

Cons: The same permission list is the ceiling for auth code AND the direct grant for M2M — structural bleed that can only be prevented by explicitly restricting the grant types permitted for application/agent.
Configuring Permission lists per app/agent pair do not scale well for complex permission hierarchies.

---

6. Preferred model: Model 2

Why Model 2

• Auth code permissions come entirely from user RBAC; M2M permissions come entirely from app RBAC role assignments. There is no shared data between the two paths that could leak. The subscription record is a pure gate/ceiling — it carries no permission strings.
• Resource server as the authority. The subscription is RS-defined — the resource server owner controls which entities can access it across all flow types.
• Scales with complexity. App RBAC assigns roles — one role encapsulates a permission set across resource servers. Does not require a manually curated scope list per app/agent, which does not scale for complex permission hierarchies.
• Direct path to entity unification. The same RBAC engine, query patterns, and subscription mechanism extend to agents without additional architectural changes.

Authorization policy

Model 2 as described above requires RBAC for entities to access resource servers. However, not all resource servers require role assignments. A public catalog API, an MCP server accessible to any dynamically registered client, or any RS where authentication alone is sufficient should not require roles to be configured before access is granted.

An authorization_policy field addresses this without a separate mechanism or additional configuration surface. The policy can live at the resource server level (applying uniformly to all subscribers) or at the subscription level (per app/agent) — the semantics are the same either way:

authorization_policy	Auth code	M2M
rbac (default)	User RBAC determines token scope	App/agent RBAC determines token scope
none	Any authenticated user gets the requested scopes	Any subscribed app or agent gets the requested scopes

In both cases, issued scopes are the intersection of what was requested and what the authorization engine resolves. The authorization_policy field is a policy selector — not an RBAC-specific construct — making it naturally extensible to other authorization models such as attribute-based or relationship-based access control, should Thunder adopt them in the future.

Request arrives
    → Look up RS from resource parameter
    → Subscription check(can the app/agent access the RS): subscribed? → No , stop
    → Yes → Read authorization_policy
        → rbac  → run user/app/agent RBAC → intersect with requested → issue token
        → none  → intersect requested with valid RS scopes → issue token

Note that the subscription check can be also enforced as a ceiling of permissions on that RS for that app/agent, rather than a gate that either allows or denies access. The model is extensible if the requirement comes up to this level-of granularity.

UI/UX

Three admin actors interact with the model across distinct surfaces:

Actor	Surface	What they configure	What it controls
Resource server admin	RS → Subscribers	Add or remove apps/agents; set authorization_policy	Which entities are permitted to access the RS, and whether RBAC or authentication alone is sufficient
App / Agent admin	App → Subscriptions	View the resource servers this app has been granted access to	Read-only visibility into subscription state; request access if self-service is enabled
App / Role admin	App → Roles	Assign roles to the app (same UX as assigning roles to a user)	Which permissions the app holds for autonomous M2M access
Role admin	Role → Members	Add apps or agents as role members alongside users and groups	Bulk or role-centric management of app permission sets

Questions

1. Are they any other basic requirements that are not considered/missed in these models?
2. What level of granularity should the resource server define entities' access on it (binary gate or at permission-level)?
3. Any other policy requirements that may be needed at the resource-server level?
4. Any other model that may align better with our entity unification requirement as well as provides extensibility for future needs?

[sahandilshan]

Suggested approach for #1616 - refined

After working through this with the entity model assumptions from #948 (final comment by @thiva-k, Model 1 or 2, no Model 2.1) in mind, I'd like to propose two options and recommend one.

Option 1 - Subscription at the RS level + RBAC

Where the relationship lives. The (App ↔ RS) relationship is stored at the Resource Server level, not on the Application. The RS owner is the authority over who may access the RS - querying "who can access RS001" should be a lookup against the RS, not a join across every Application's permission list. This also aligns with how RFC 8707 and RFC 9728 frame the RS as the access target, and handles dynamically-registered clients (MCP, etc.) cleanly.

Scope ownership stays with the RS. Each RS defines its own scope namespace. Roles are composed of scopes from one specific RS. When a token is requested, the AS:

1. Verifies the subscription exists for (requesting App, target RS from resource param). If not, reject.
2. Looks up roles based on the Subject:
   • M2M flow: roles the App holds. Subject and Actor are the same Entity.
   • Delegation flow: roles the User holds.
3. Token scopes = requested ∩ RBAC scopes (∩ subscription allowlist, if applicable - see approaches below).

This plugs the #2198 M2M-accepts-anything gap directly: M2M tokens cap at the App's assigned roles for that RS, which start empty.

Option 2 - Permission allowlist on the Application

The list of permissions an App can access is stored on the Application side. Each App declares which RSs/scopes it is authorized to request, and the AS validates against this list.

This is the model used by Microsoft Entra (API permissions on the client app registration) and AWS Cognito (allowed scopes per app client). The accessing App is the entity that carries the access list.

Recommendation

Option 1 is the recommended approach. Storing the relationship at the RS level keeps the resource owner as the authority, matches how RFC 8707/9728 frame the RS as the access target, and makes "who can access RS001" a single-RS lookup rather than a global scan across Applications.

Two approaches under Option 1

Within Option 1, there are two ways to express the subscription:

1a - RS-level subscription (binary gate). A subscription authorizes an App for the RS as a whole. If subscribed, the App may request any scope the RBAC layer permits. Token scopes = requested ∩ RBAC.

1b - Scope-level subscription (allowlist). A subscription authorizes an App for a specific set of scopes at the RS. Token scopes = requested ∩ RBAC ∩ subscription allowlist. The allowlist represents what the RS owner has authorized this App to channel, regardless of who the Subject is.

Issues to consider with scope-level subscription (1b)

1. Two ceilings to reason about. Admins debugging "why is my token missing scope X?" have to check both the subscription allowlist and the role assignments. Cognitive cost compared to the single-source RBAC ceiling in 1a.

2. Drift with RS scope changes. When the RS introduces a new scope, every existing subscription with an explicit allowlist silently does not include it. The RS owner must walk every subscription to opt in. Scope removal needs cleanup of dangling references.

3. Default behaviour question. If admins can omit the allowlist, they will - narrowing scopes is tedious, so unrestricted becomes the de-facto default and the per-App ceiling becomes theatre. To avoid this, unrestricted has to be a deliberate choice (scopes: ["*"]) rather than just an empty field.

4. Redundancy with RBAC in the common case. When the allowlist matches what App roles already grant, the field contributes no decision. It only earns its keep when the allowlist is narrower than RBAC alone - i.e., when the RS owner wants a Subject-agnostic ceiling on the App independent of role assignments.

Open questions

• Should public RSs (e.g., dynamically-registered MCP servers) be able to opt out of the gate entirely? Some RSs are intentionally open and shouldn't require explicit subscription per accessing App.
• How does the gate behave when one Application has multiple OAuth clients (per Agent Identity and Entity Model #948 forward requirement)? Subscription should key off Application ID, not client_id, so that all clients of the same Application share the same gate.
• Role definition ownership - App owner or RS owner? Both produce the same gating outcome but differ in admin model.

cc @thiva-k @senthalan

[senthalan]

With the subject-actor-resource concepts,

In a high level, the resource should have say on,

1. How subject (user, agent, application in M2M) can access is controlled ?
2. How the actor (app, agent) can access is controlled?

The RBAC for entities is to provide one way of controlling how the subject access resource. As this design is to solve the 2nd part, can we create this as a separate discussion ?

[thiva-k]

+1 for Option 1, since it aligns cleanly with our subject-actor-resource story.

Regarding 1a and 1b, I think we can have both representations right? The resource server can dictate whether:

1. All scopes on it are allowed/ binary gate(can be the default considering UX)
2. RS owner can optionally fine-grain it by allowing only certain scopes(ceiling)
3. Which client(actors) can access it? (MCP server can allow any clients to access it e.g. *)

These can be considered as policies of the resource-server too