OAuth 2.0 Rich Authorization Requests
Extracted elements (27)
For authorization details types deployed across different servers (open standards), API designers are RECOMMENDED to use a collision-resistant namespace such as a URI under their control as the type value, to prevent type identifier conflicts across deployments.
The combined use of `authorization_details` and `scope` is intentionally supported to allow existing OAuth-based applications to incrementally migrate towards using `authorization_details` exclusively, without requiring a flag-day cutover.
The `scope` parameter is insufficient for fine-grained authorization such as 'transfer 45 EUR to Merchant A' or 'read access to directory A and write access to file X'. The `authorization_details` parameter introduces JSON-structured objects to express these detailed requirements in a way that scope strings cannot convey.
There is no standardized mechanism to compare two arbitrary `authorization_details` requests because field semantics are API-specific. The AS should not rely on simple object comparison; instead, it should apply the same processing used when granting the request to determine whether a new request is subsumed by an existing grant.
For large authorization requests containing `authorization_details`, implementers should consider using Pushed Authorization Requests (RFC 9126) with the `request_uri` parameter (RFC 9101) to avoid URI length limitations and improve security and reliability.
The `authorization_details` parameter can be used in all contexts where `scope` is used: RFC 6749 authorization requests, RFC 8628 device authorization requests, and OpenID Connect CIBA backchannel authentication requests. Parameter encoding follows the rules of the respective context.
The `resource` parameter (RFC 8707) does not have any impact on how the AS processes the `authorization_details` parameter; the two parameters are independent and do not interact.
In the token response, the AS MUST also return `authorization_details` as granted by the resource owner and assigned to the respective access token, in addition to the standard RFC 6749 token response parameters.
The AS MUST refuse to process any unknown authorization details type or any authorization details object that contains unknown fields, fields of the wrong type, fields with invalid values, or missing required fields. It MUST abort and respond with the error `invalid_authorization_details`.
The `type` field within each authorization details object is REQUIRED. Its value is unique for the described API in the context of the AS and controls which other fields are permitted in that object.
To enable RSs to enforce authorization details, the AS MUST make the `authorization_details` data available to the RS, either by adding it to JWT-format access tokens or to token introspection responses.
When `authorization_details` and `scope` appear in the same authorization request, the AS MUST process both sets of requirements in combination. When gathering user consent, the AS MUST present the merged set of requirements.
When the AS includes `authorization_details` in a token introspection response, the information MUST be conveyed as a top-level `authorization_details` member of the introspection response JSON object, containing the same structure defined in Section 2, potentially filtered and extended for the requesting RS.
Even with encryption, an attacker could inject an encrypted authorization request on their own device and use the AS consent screen to reveal decrypted user data. Implementations must consider this attack vector and apply countermeasures such as showing only portions of data or verifying that the user context is unchanged.
Sensitive personal data included in `authorization_details` must be prevented from leaking through referrer headers or other side channels. Mitigations include encrypted request objects (RFC 9101) or end-to-end encrypted transmission via PAR (RFC 9126) with `request_uri`.
The AS should share `authorization_details` with clients and RSs on a 'need to know' basis as determined by local policy, minimizing the exposure of potentially sensitive authorization details beyond what each party requires.
Common data fields defined for reuse across API types are: `locations` (array of URI strings identifying the RS), `actions` (array of action strings), `datatypes` (array of data-type strings), `identifier` (single resource identifier string), and `privileges` (array of privilege-level strings). When combined in one object, the resulting permissions are the product of all values.
Enriched authorization details: the AS MAY add information to authorization details objects in the token response beyond what the client originally requested (e.g., specific account identifiers or record locations selected by the user during consent). Whether enrichment is allowed is part of the definition of each authorization details type.
For JWT-based access tokens, the AS is RECOMMENDED to add the `authorization_details` object as a top-level JWT claim, filtered to the specific audience (RS). This enables the RS to enforce the authorized details without introspection.
The `authorization_details` parameter is a JSON array of objects; each object MUST contain a `type` field whose value is a string identifier for the authorization details type and determines the allowable contents of the object. Multiple entries of the same type are permitted within one array.
The `authorization_details_types_supported` AS metadata parameter is a JSON array advertising the authorization details types the AS supports. The `authorization_details_types` client registration metadata parameter is a JSON array indicating which types the client uses.
The `invalid_authorization_details` error code is registered for use at both the token endpoint and the authorization endpoint, returned when authorization details fail validation (unknown type, wrong field types, missing required fields, or invalid values).
IANA registered `authorization_details` in the OAuth Parameters registry (authorization request, token request, token response), the JSON Web Token Claims registry, and the OAuth Token Introspection Response registry. Also registered `authorization_details_types_supported` in OAuth Authorization Server Metadata and `authorization_details_types` in OAuth Dynamic Client Registration Metadata.
IANA registered the `invalid_authorization_details` error code in the OAuth Extensions Error Registry for use at both the token endpoint and the authorization endpoint, as defined by RFC 9396.
The AS MUST properly sanitize and handle data passed in `authorization_details` to prevent injection attacks. All string comparisons are done per RFC 8259 with no additional normalization.
The `authorization_details` parameter is sent through the user agent in an OAuth authorization request, making it vulnerable to modification by the user. If integrity is a concern, clients MUST protect `authorization_details` against tampering by signing the request using JAR (RFC 9101) or using PAR (RFC 9126) with `request_uri`.
The `locations` common data field enables unambiguous audience restriction by binding authorization to specific RSs, preventing a token scoped for one RS (e.g., email) from being misused at another RS (e.g., cloud storage) when both share a common scope value.