[Design Discussion] RFC 8707 Resource Indicators Support

[sahandilshan]

Related Feature Issue

#2197

Problem Summary

Thunder cannot audience-restrict access tokens to specific Resource Servers. RFC 8707 introduces a resource parameter that lets clients indicate the target service, enabling the authorization server to mint tokens with appropriate aud claims. The key design question is whether this parameter maps to Thunder's "Resource Server" or its sub-level "Resource" entity.

High-Level Approach

• Add resource parameter support to the authorization and token endpoints.
• Map resource → Thunder's Resource Server entity (rationale below in Alternatives).
• Add a URI identifier field to the Resource Server model for administrators to set (e.g., https://api.example.com/booking/).
• Set aud in issued JWTs to the Resource Server URI; downscope permissions to only those relevant to the target Resource Server.
• Return invalid_target error for unknown or malformed resource values.
• For refresh_token grants, allow narrowing to a subset of originally authorized resources; refresh token stays bound to the full grant.

Architecture Overview

Authorization Endpoint: Accepts resource parameter (one or more absolute URIs), resolves against registered Resource Server identifiers, binds resource context to the authorization code grant.

Token Endpoint: Accepts resource for all grant types. Issues access tokens with aud set to resolved Resource Server URI(s). Downscopes token permissions to the target Resource Server.

Resource Server Entity: New identifier field (absolute URI) added to the model. This is what clients pass as resource and what appears as aud in JWTs.

Relationship to Existing Permission Model: resource answers where (audience); scopes/permissions answer what (access rights). These remain orthogonal. The permission hierarchy (Resource Server → Resources → Actions) is unchanged.

Security Considerations

• Token redirect prevention: Audience-restricted tokens cannot be replayed at unintended Resource Servers.
• Multi-audience tokens: Bearer tokens with multiple audiences can be used by any audience to access any other. Default to single-resource; document trust implications. Consider making multi-resource configurable.
• URI validation: Must be absolute URI, no fragments. Reject malformed values with invalid_target.
• Scope downscoping: Tokens for a specific Resource Server should only carry permissions relevant to it, preventing cross-service permission leakage.
• Refresh token binding: Refresh tokens remain bound to the full original grant per the RFC.

Impacted Areas

• OAuth2 Authorization Endpoint
• OAuth2 Token Endpoint
• Resource Server entity model and management APIs
• JWT token issuance (aud claim)
• Token introspection response

Alternatives Considered

Alternative 1: Map resource to Thunder's sub-level Resource

• Creates an orphan problem: actions assigned directly to a Resource Server (e.g., create, list in the Booking API example) have no Resource entity to map to. Forces awkward workarounds synthetic root resources, disallowing direct Resource Server actions, or dual authorization paths.
• Conflates "where" (audience) with "what" (access rights), which both the RFC and Thunder's model intentionally separate.
• RFC examples consistently use service-level base URIs (https://cal.example.com/, https://apps.example.com/scim/), not sub-resource paths.

Alternative 2: Encode resource identity in scope values

• RFC 8707 explicitly discourages scope overloading for conveying resource identity.

Questions for Community Input

1. Should the Resource Server URI identifier be required or optional? Behavior when a client sends resource but the target has no URI?
2. Naming preference for the field 'identifier, resource_uri, audience_uri`?
3. Support multi-resource token requests from day one, or single-resource first?

[sahandilshan]

Current Blockers

1. Single-value aud claim in issued tokens
Thunder currently sets the aud claim to the OAuth application's client ID as a single string value. RFC 8707 requires the authorization server to audience-restrict tokens to the indicated Resource Server(s), and the spec allows multiple resource parameters in a single request which means aud needs to support an array of values.

2. Permission string collisions across Resource Servers
Permissions (scopes) in Thunder are scoped to individual Resource Servers, meaning different Resource Servers within the same organization can produce identical permission strings. Per [RFC 8707 Section 2.1](https://www.rfc-editor.org/rfc/rfc8707.html#name-authorization-request), multiple resource parameters can be included in an authorization request. If two Resource Servers define the same permission, there is no way to determine which Resource Server a given permission belongs to.

Example:

Resource Server A (delimiter :) → resource: users → action: read → permission: users:read
Resource Server B (delimiter :) → resource: users → action: read → permission: users:read

Both produce users:read, the permission string alone cannot disambiguate the target Resource Server.

3. Resource Server identifier is not a URI
RFC 8707 requires the resource parameter value to be an absolute URI. Thunder currently allows any arbitrary string as a Resource Server identifier, which does not satisfy this requirement.

[sahandilshan]

Analysis of Suggested Solutions

Solution 1: Multi-audience aud support

Suggestion: Issue JWT access tokens with aud as an array when multiple resource parameters are present.

Assessment: This is a direct requirement of RFC 8707 the spec allows multiple resource parameters, and RFC 7519 already supports aud as either a string or an array. There is no blocker here, just implementation work. Tracked as a sub-issue under #2197.

---

Solution 2: Embed Resource Server identity in permission strings

Suggestion: Prefix the permission string with the Resource Server identifier to eliminate collisions.

resource-server-a:users:read
resource-server-b:users:read

Blocker: This works only while the Resource Server identifier is a simple string. However, Blocker 3 requires the identifier to be an absolute URI per RFC 8707. Once it's a URI, : can no longer serve as the delimiter because : appears in every URI scheme (https:). There's no way to parse where the URI ends and the permission begins:

https://api.example.com/booking/:users:read  ← ambiguous

---

Solution 3: Introduce a default Thunder URI for Resource Servers

Suggestion: Generate a standard URI for each Resource Server using a Thunder-owned domain:

https://www.thunder-resources.com/auth/<resource-identifier>

Blocker: RFC 8707 Section 3 recommends that the resource URI correspond to the network-addressable location of the protected resource, so clients can validate that the resource controls the corresponding endpoint. A synthetic Thunder-generated URI at a domain unrelated to the actual API does not satisfy this. It also creates a dependency on an external domain that doesn't work for self-hosted or on-premise Thunder deployments.

---

Optimal Solution

Combine the strengths of Solutions 2 and 3 by introducing two distinct fields on the Resource Server entity:

identifier:A short, unique string (e.g., booking-api). This is embedded in permission strings to resolve collisions. It must not contain the delimiter character.

uri: An absolute URI with no fragment component (e.g., https://api.example.com/booking/). This is what clients pass as the resource parameter and what Thunder sets as the aud claim in issued JWTs. Administrators configure this to the actual network-addressable location of their API, satisfying RFC 8707's security recommendation.

How this resolves all three blockers

Blocker 1 (single-value aud): The uri field provides the value for the aud claim. Multi-audience support allows an array of URIs when multiple resource parameters are requested.

Blocker 2 (permission string collisions): The identifier is a simple string with no URI characters, so : remains a safe delimiter. Permissions become globally unique:

Resource Server A (identifier: "booking-api", uri: "https://api.example.com/booking/")
  → permission: booking-api:users:read

Resource Server B (identifier: "crm-api", uri: "https://api.example.com/crm/")
  → permission: crm-api:users:read

No ambiguity, the delimiter problem from Solution 2 disappears because the identifier is never a URI.

Blocker 3 (identifier is not a URI): The uri field is the RFC 8707-compliant absolute URI. The identifier serves a different purpose (permission string namespacing) and is not used as the resource parameter value.

Example end-to-end flow

Resource Server configuration:
  identifier: "booking-api"
  uri: "https://api.example.com/booking/"
  delimiter: ":"
  resources/actions → permissions:
    - booking-api:create
    - booking-api:list
    - booking-api:reservations:create
    - booking-api:reservations:view

Authorization request:
  resource=https://api.example.com/booking/
  scope=booking-api:reservations:create booking-api:reservations:view

Issued JWT:
  {
    "aud": "https://api.example.com/booking/",
    "scope": "booking-api:reservations:create booking-api:reservations:view"
  }

cc: @senthalan

[sahandilshan]

Below will be the final approach. It's refine of the above. Main focus is not to use and URI attribute directly

Refined Approach: handler and identifier

After further consideration, the two-field approach is refined as follows:

handler — A short, unique string (e.g., booking-api). This is what gets embedded in permission strings to resolve collisions. It must not contain the delimiter character. This is purely an internal construct for permission namespacing.

identifier — A unique value that represents the Resource Server externally. This can be an absolute URI (e.g., https://api.example.com/booking/), but it doesn't have to be. If it is a valid absolute URI, it can be used as the RFC 8707 resource parameter value and will be set as the aud claim in issued JWTs. If it is not a URI, the Resource Server simply cannot participate in RFC 8707 resource indicator flows.

How this maps to the blockers

Blocker 1 (single-value aud): When the identifier is a URI, it serves as the aud value. Multi-audience support allows an array when multiple resource parameters are requested.

Blocker 2 (permission string collisions): The handler is embedded in the permission string. Since it's a simple string (never a URI), : remains unambiguous as a delimiter:

Resource Server A (handler: "booking-api", identifier: "https://api.example.com/booking/")
  → permission: booking-api:users:read

Resource Server B (handler: "crm-api", identifier: "https://api.example.com/crm/")
  → permission: crm-api:users:read

Blocker 3 (identifier is not a URI): The identifier field supports URIs but does not require them. RFC 8707 compliance is opt-in — Resource Servers with a URI identifier get full resource indicator support; those without simply don't participate in resource parameter flows.

Example

Resource Server configuration:
  handler: "booking-api"
  identifier: "https://api.example.com/booking/"
  delimiter: ":"

Permissions generated:
  - booking-api:create
  - booking-api:list
  - booking-api:reservations:create

Authorization request:
  resource=https://api.example.com/booking/
  scope=booking-api:reservations:create

Issued JWT:
  {
    "aud": "https://api.example.com/booking/",
    "scope": "booking-api:reservations:create"
  }

For a Resource Server with a non-URI identifier (e.g., identifier: "internal-service-01"), permissions work identically (booking-api:reservations:create), but clients cannot use the resource parameter to request tokens scoped to it.

[sahandilshan]

Open Questions from Implementation

A few decisions that came up during implementation and need to be finalized:

1. aud claim type in issued tokens
Should aud always be a JSON array, or should it be a string when there is a single audience and an array only when there are multiple? RFC 7519 allows both forms, but always using an array simplifies consumer parsing at the cost of deviating from the current single-string format.

2. Default client_id in the aud claim
Thunder currently sets the OAuth application's client_id as the aud value. When a resource parameter is present and the aud is set to the Resource Server URI, should the client_id be removed from aud entirely, or should it be retained alongside the Resource Server URI?

3. Behavior when the resource parameter is omitted
When a client does not include the resource parameter in the authorize/token request, should Thunder treat this as a request for permissions across all Resource Servers, or should it issue a token with no resource-specific permissions? RFC 8707 leaves this to the authorization server's discretion — it MAY process the request with no specific resource or use a predefined default.