]> Raiffeisen Bank International

yaron.zehavi@rbinternational.com

Security Web Authorization Protocol RAR Step-up oauth OAuth 2.0 Rich Authorization Requests (RAR), as defined in , enables fine-grained authorization requests, using structured JSON objects. While RAR standardizes the exchange and handling of authorization details, it does not define a mechanism for clients to discover how to construct valid authorization details types. This document defines a machine-readable metadata format for authorization servers to provide authorization details type documentation and JSON Schema definitions, as well as interoperable discovery via OAuth Resource Server Metadata . This document also defines a new WWW-Authenticate normative OAuth error code, insufficient_authorization_details, enabling resource servers to indicate inadequate authorization details as the cause of failure. It also defines an OPTIONAL response body which MAY be returned alongside the insufficient_authorization_details error, providing an informative yet actionable authorization details object, which can be used directly in a subsequent OAuth request. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction OAuth 2.0 Rich Authorization Requests (RAR) allows OAuth clients to request structured, fine-grained authorization, beyond the coarse-grained access offered by simple scopes, which has enabled advanced authorization models across many domains, such as open banking & API marketplaces. However, RAR does not specify how a client learns how to construct syntactically valid authorization details objects. As a result, clients must rely on out-of-band documentation or static ecosystem profiles, limiting interoperability and preventing dynamic client behavior. This document addresses this gap by:

• Defining a new authorization server endpoint: authorization_details_types_metadata_endpoint, providing metadata for authorization details types, including human-readable documentation as well as embedded JSON Schema definitions .
• Adding accepted authorization details types to OAuth 2.0 Protected Resource Metadata response, facilitating RAR metadata discovery.
• Defining a standardized error signaling mechanism using the WWW-Authenticate response header, allowing resource servers to specify insufficient_authorization_details as the cause of error.
• Defining an OPTIONAL response body, included with an insufficient_authorization_details error, providing an informative authorization details object, whose inclusion in a new OAuth request shall result, if approved, in an access token satisfying the endpoint's requirements.

The OPTIONAL providing of actionable authorization details objects by resource servers enables:

• High interoperability and simplification by relieving clients from having to figure out how to construct valid authorization details objects, instead providing them with required authorization_details object, to be included in a subsequent OAuth request.
• Support for including ephemeral, interaction-specific details originating from the resource domain, in the authorization details object, such as for example a risk score, a risk profile or an internal interaction identifier. Resource servers MAY use this to guide authorization servers as to the required authentication strength and consent flow.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Protocol Overview There are two main proposed flows:

• Client learns to construct valid authorization details objects using authorization details types metadata.
• Client obtains an actionable authorization details object from resource server's error response.

Client learns to construct valid authorization details objects using metadata | Resource | (A) User +---| | | Server | Starts| | |<----------------------| | Flow +-->| | (C) 403 Forbidden +---------------------+ | | WWW-Authenticate: Bearer | | error="insufficient_authorization_details", | | resource_metadata="[resource metadata url]" | | : | | Resource +---------------------+ | | (D) Metadata Request | Resource Server | | |---------------------->|+-------------------+| | | || Resource Metadata || | Client |<----------------------|| Endpoint || | | (E) Metadata Response |+-------------------+| | | (Discover also +---------------------+ | | expected RAR types) | | : +---------------------+ | | RAR Types | Authorization | | | (F) Metadata Request | Server | | |---------------------->|+-------------------+| | | || RAR Types || | |<----------------------|| Metadata Endpoint || | | (G) Metadata Response |+-------------------+| | | : | | | | (H) Construct RAR | | | | Using Metadata | | | | : | | | | (I) Authorization | | | | Request + RAR | | | |---------------------->|+-------------------+| | | || Authorization || | |<----------------------|| Endpoint || | | (J) Authorization Code|| || | | : |+-------------------+| | | : | | | | (K) Token Request |+-------------------+| | |---------------------->|| || | | || Token Endpoint || | |<----------------------|| || | | (L) Access Token |+-------------------+| | | : +---------------------+ | | : | | (M) API Call with | | Access Token +---------------------+ | |---------------------->| | | | | Resource Server | | |<----------------------| | | | (N) 200 OK + Resource +---------------------+ | | +----------+ ]]> Figure: Client learns to construct valid authorization details objects from metadata

• (A) The user starts the flow.
• (B) The client calls an API with an access token.
• (C) Resource server returns HTTP 403 forbidden including a WWW-Authenticate header with error code insufficient_authorization_details and the resource metadata url (OAuth 2.0 Protected Resource Metadata ).
• (D-E) The client discovers expected authorization details types from resource metadata endpoint's response.
• (F-G) The client consumes authorization details type metadata from authorization server's authorization_details_types_metadata_endpoint.
• (H-I) The client constructs a valid authorization details object and makes an OAuth + RAR request.
• (J) Authorization server returns authorization code.
• (K-L) The client exchanges authorization code for access token.
• (M) The client makes an API request with the (RAR) access token.
• (N) Resource server validates access token and returns successful response.

Client obtains authorization details object from resource server's error response | Resource | (A) User +---| | | Server | Starts| | |<----------------------| | Flow +-->| Client | (C) 403 Forbidden +--------------------+ | | WWW-Authenticate: Bearer | | error="insufficient_authorization_details", | | resource_metadata="[resource metadata url]" | | + | | HTTP body provides authorization_details | | : | | : +--------------------+ | | : | Authorization | | | (D) Authorization | Server | | | Request + RAR |+------------------+| | |---------------------->|| || | | || Authorization || | |<----------------------|| Endpoint || | | (E) Authorization Code|| || | | : |+------------------+| | | : | | | | (G) Token Request |+------------------+| | |---------------------->|| || | | || Token Endpoint || | |<----------------------|| || | | (H) Access Token |+------------------+| | | : +--------------------+ | | : | | : | | (I) Retry API Call +--------------------+ | | with Token | | | |---------------------->| Resource | | | | Server | | |<----------------------| | | | (J) 200 OK + Resource +--------------------+ | | +----------+ ]]> Figure: Client obtains authorization details object from resource server's error response

• (A) The user starts the flow.
• (B) The client calls an API with an access token.
• (C) Resource server returns HTTP 403 forbidden including a WWW-Authenticate header with error code insufficient_authorization_details and in the response body includes the authorization details object requiring approval.
• (D) The client uses the obtained authorization details object in a new OAuth + RAR request.
• (E) Authorization server returns authorization code.
• (G-H) The client exchanges authorization code for access token.
• (I) The client makes an API request with the (RAR) access token.
• (J) Resource server validates access token and returns successful response.

OAuth 2.0 Protected Resource Metadata This document specifies that the metadata attribute: authorization_details_types_supported, defined by RAR , shall be included as an OPTIONAL response attributes in Protected Resource Metadata . Note: When resource servers accept access tokens from several authorization servers, interoperability is maintained as client can discover each authorization server' supported authorization details types. The following is a non-normative example response with the added authorization_details_types_supported attribute:

Authorization Details Types Metadata Endpoint The following authorization server metadata parameter is introduced to signal the server's support for Authorization Details Types Metadata:

"authorization_details_types_metadata_endpoint":

OPTIONAL. The URL of the Authorization Details Types Metadata endpoint.

Authorization Details Types Metadata Endpoint Response The Authorization Details Types Metadata endpoint's response is a JSON document with the key authorization_details_types_metadata whose attributes are authorization details type identifiers. Each identifier is an object describing a single authorization details type. Attributes definition:

"version":

OPTIONAL. String identifying the version of the authorization details type definition. The value is informational and does not imply semantic version negotiation.

"description":

OPTIONAL. String containing a human-readable description of the authorization details type. Clients MUST NOT rely on this value for authorization or validation decisions.

"documentation_uri":

OPTIONAL. URI referencing external human-readable documentation describing the authorization details type.

"schema":

The schema attribute is a JSON Schema document describing a single authorization detail object. The schema MUST validate a single authorization detail object and MUST constrain the type attribute to the authorization detail type identifier. This attribute is REQUIRED unless schema_uri is specified. If this attribute is present, schema_uri MUST NOT be present.

"schema_uri":

The schema_uri attribute is an absolute URI, as defined by RFC 3986 , referencing a JSON Schema document describing a single authorization details object. The referenced schema MUST satisfy the same requirements as the schema attribute. This attribute is REQUIRED unless schema is specified. If this attribute is present, schema MUST NOT be present.

"examples":

OPTIONAL. An array of example authorization details objects. Examples are non-normative.

See Examples for non-normative response example.

Resource Server Error Signaling of Inadequate authorization_details This document defines a new normative OAuth error code, insufficient_authorization_details, which resource servers SHALL return using the WWW-Authenticate header, to signal access is denied due to missing or insufficient authorization details. Example HTTP response:

OPTIONAL authorization_details in response body Resource server MAY provide alongside the insufficient_authorization_details error, an HTTP response body of content type application/json, containing the required authorization details to satisfy the currently failing request. Note:

• Authorization details objects provided by a resource server in an error response are intended for its trusted authorization servers, as advertised by the Resource Server’s metadata endpoint.
• Resource servers SHALL provide authorization_details objects only if all trusted authorization servers accept the authorization details type used.

HTTP response body definition:

"authorization_details":

OPTIONAL. Array of authorization details objects, matching the format specified in RAR for the authorization_details request parameter.

Clients MAY use the provided authorization_details in a subsequent OAuth request to obtain an access token satisfying the resource's requirements. Example resource server response with OPTIONAL authorization_details:

Processing Rules

Client Processing Rules

• If encountering error insufficient_authorization_details, check if body.authorization_details exists and if provided MAY include in subsequent OAuth request.
• Otherwise consult metadata:
  • Fetch resource metadata to discover accepted authorization servers and supported authorization_details types.
  • Fetch authorization server metadata to discover authorization_details_types_supported.
  • Fetch authorization server's authorization_details_types_metadata_endpoint to obtain metadata and schema
  • Locate schema or retrieve schema_uri.
• Construct authorization details conforming to the schema and include in subsequent OAuth request.

Resource Server Processing Rules

• Advertise in resource metadata authorization_details_types_supported, where relevant.
• Verify access tokens against required authorization details.
• If insufficient, return HTTP 403 with WWW-Authenticate: Bearer error="insufficient_authorization_details".
• OPTIONALLY provide also an HTTP body with an informative actionable authorization_details object.

Security Considerations

Cacheability and Intermediaries HTTP 403 responses with response bodies may be cached or replayed in unexpected contexts. Recommended mitigation is resource servers SHALL use Cache-Control: no-store response header.

IANA Considerations

OAuth 2.0 Bearer Token Error Registry

Error Code	Description
insufficient_authorization_details	The request is missing required authorization details or the provided authorization details are insufficient.

OAuth Metadata Attribute Registration The metadata attribute authorization_details_types_metadata_endpoint is defined for OAuth authorization server metadata as a URL.

Normative References A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. This document specifies a new parameter authorization_details that is used to carry fine-grained authorization data in OAuth messages. This specification defines a metadata format that an OAuth 2.0 client or authorization server can use to obtain the information needed to interact with an OAuth 2.0 protected resource. IANA In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Examples This section provides non-normative examples of how this specification may be used to support specific use cases.

Metadata Examples

Example authorization_details_types_metadata_endpoint response with Payment Initiation

Payment initiation with RAR error signaling

Client initiates API request Client uses access token obtained at login to call payment initiation API

Resource server signals insufficient_authorization_details with actionable RAR object Resource server requires payment approval and responds with: Note: the resource server has added the ephemeral attributes interactionId and riskProfile.

Client initiates OAuth flow using the provided authorization_details object After user approves the request, client obtains single-use access token representing the approved payment

Client re-attempts API request

Resource server authorizes the request

Document History -01

• Authorization details moved to HTTP body and made OPTIONAL
• Metadata pointer from resource metadata url, full authorization details types metadata on authorization server new endpoint

-00

• Document creation

Acknowledgments