Web Authorization Protocol Y. Zehavi Internet-Draft Raiffeisen Bank International Intended status: Standards Track 14 June 2026 Expires: 16 December 2026 OAuth 2.0 RAR Metadata and Error Signaling draft-zehavi-oauth-rar-metadata-04 Abstract OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] standardizes the exchange and processing of authorization details but does not define metadata for describing authorization details types. This document addresses a practical interoperability challenge regarding authorization details type metadata, allowing clients to dynamically discover metadata instead of relying on out-of-band agreements. It also standardizes error signaling for cases where insufficient authorization details are provided, and offers structured remediation mechanisms. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://yaron- zehavi.github.io/oauth-rich-authorization-requests-metadata/draft- zehavi-oauth-rar-metadata.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-zehavi-oauth- rar-metadata/. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/. Source for this draft and an issue tracker can be found at https://github.com/yaron-zehavi/oauth-rich-authorization-requests- metadata. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Zehavi Expires 16 December 2026 [Page 1] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 16 December 2026. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Client remediates using metadata of required authorization details types . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Client remediates using actionable authorization details objects provided by resource server . . . . . . . . . . . 7 4. Authorization Details Types Metadata Endpoint . . . . . . . . 9 4.1. Authorization Details Types Metadata Endpoint Response . 9 5. Resource Server Error Signaling of insufficient authorization_details . . . . . . . . . . . . . . . . . . 10 5.1. RECOMMENDED authorization_details_types_required in response body . . . . . . . . . . . . . . . . . . . . . . 11 5.1.1. Required types expression syntax . . . . . . . . . . 11 5.1.2. Required types expression examples . . . . . . . . . 12 5.2. OPTIONAL actionable authorization_details in response body . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. Handling large RAR objects when issuing access tokens . . . . 14 7. Processing Rules . . . . . . . . . . . . . . . . . . . . . . 14 7.1. Client Processing Rules . . . . . . . . . . . . . . . . . 15 Zehavi Expires 16 December 2026 [Page 2] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 7.2. Resource Server Processing Rules . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 8.1. Cacheability and Intermediaries . . . . . . . . . . . . . 16 8.2. Confidentiality of resource server provided authorization_details . . . . . . . . . . . . . . . . . . 16 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 9.1. OAuth 2.0 WWW-Authenticate Error Code Registry . . . . . 16 9.2. OAuth Authorization Server Metadata Registry . . . . . . 17 10. Normative References . . . . . . . . . . . . . . . . . . . . 17 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 A.1. Authorization Server Metadata Examples . . . . . . . . . 18 A.1.1. Example authorization_details_types_metadata_endpoint response with Payment Initiation . . . . . . . . . . 18 A.1.2. Example authorization_details_types_metadata_endpoint response for the Norwegian Health Sector (HelseID) . 20 A.2. Resource Server authorization_details_types_required Response Examples . . . . . . . . . . . . . . . . . . . . 25 A.2.1. Example Resource server authorization_details_types_required response from payments resource . . . . . . . . . . . . . . . . . . 26 A.2.2. Example Resource server authorization_details_types_required response from the Norwegian Health Sector (HelseID) . . . . . . . . . . 26 A.3. Payment initiation with RAR error signaling . . . . . . . 26 A.3.1. Client initiates API request . . . . . . . . . . . . 26 A.3.2. Resource server signals insufficient_authorization_details with actionable RAR object . . . . . . . . . . . . . . . . . . . . . . . 27 A.3.3. Client initiates OAuth flow using the provided authorization_details object . . . . . . . . . . . . 28 A.3.4. Client re-attempts API request . . . . . . . . . . . 28 A.3.5. Resource server authorizes the request . . . . . . . 29 Appendix B. Document History . . . . . . . . . . . . . . . . . . 29 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 30 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 1. Introduction OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] allows OAuth clients to request detailed and structured authorization, enabling advanced authorization models across domains such as banking and healthcare. However, RAR [RFC9396] does not specify how clients discover metadata describing valid authorization details objects. Such metadata and documentation are obtained out-of-band. This document defines: Zehavi Expires 16 December 2026 [Page 3] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 * A new authorization server endpoint: authorization_details_types_metadata_endpoint, providing authorization details type metadata, including documentation and JSON Schema definitions [JSON.Schema]. * A new normative OAuth 2.0 WWW-Authenticate Error Code, for resource servers to indicate insufficient_authorization_details as the cause of the error, as well as a RECOMMENDED response body specifying required authorization details types to satisfy the resource's requirements. * An OPTIONAL response body attribute that MAY accompany the insufficient_authorization_details error, providing an informative and actionable authorization details object. This object can be used directly in a follow-up OAuth request. * RECOMMENDED handling of large RAR [RFC9396] authorization details objects when issuing JWT access tokens, to avoid failures due to token sizes exceeding header size restrictions. Providing actionable authorization details objects in the resource server's error response enables: * Simplification for clients who can directly remediate without learning to construct valid authorization details objects. * Support for ephemeral, interaction-specific attributes from the resource server, such as a risk profile or an internal interaction identifier, guiding authorization servers on required authentication strength and consent flows. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Protocol Overview There are two main proposed flows: * Client remediates using *metadata of required authorization details types*. * Client remediates using *actionable authorization details objects* provided by resource server. Zehavi Expires 16 December 2026 [Page 4] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 3.1. Client remediates using metadata of required authorization details types Zehavi Expires 16 December 2026 [Page 5] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 +---------------------+ +----------+ (B) API Request | | | |---------------------->| Resource | (A) User +---| | | Server | Starts| | |<----------------------| | Flow +-->| | (C) 403 Forbidden +---------------------+ | | WWW-Authenticate: Bearer | | error="insufficient_authorization_details" | | + | | HTTP body specifies | | required authorization_details | | : | | +---------------------+ | | RAR Types | Authorization | | | (D) Metadata Request | Server | | |---------------------->|+-------------------+| | | || RAR Types || | |<----------------------|| Metadata Endpoint || | | (E) Metadata Response |+-------------------+| | | : | | | | (F) Construct RAR | | | | Using Metadata | | | | : | | | | (G) Authorization | | | | Request + RAR | | | |---------------------->|+-------------------+| | | || Authorization || | |<----------------------|| Endpoint || | | (H) Authorization Code|| || | | : |+-------------------+| | | : | | | | (I) Token Request |+-------------------+| | |---------------------->|| || | | || Token Endpoint || | |<----------------------|| || | | (J) Access Token |+-------------------+| | | : +---------------------+ | | : | | (K) API Call with | | Access Token +---------------------+ | |---------------------->| | | | | Resource Server | | |<----------------------| | | | (L) 200 OK + Resource +---------------------+ | | +----------+ Zehavi Expires 16 December 2026 [Page 6] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 Figure: Client remediates using metadata of required authorization details types * (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 specifies required authorization details types. * (D-E) The client consumes authorization details types metadata from authorization server's authorization_details_types_metadata_endpoint. * (F-G) The client constructs valid authorization details objects and makes an authorization request using RAR [RFC9396]. * (H) Authorization server returns authorization code. * (I-J) The client exchanges authorization code for access token. * (K) The client makes an API request with the (RAR) access token. * (L) Resource server validates access token and returns successful response. 3.2. Client remediates using actionable authorization details objects provided by resource server Zehavi Expires 16 December 2026 [Page 7] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 +--------------------+ +----------+ (B) API Request | | | |---------------------->| Resource | (A) User +---| | | Server | Starts| | |<----------------------| | Flow +-->| Client | (C) 403 Forbidden +--------------------+ | | WWW-Authenticate: Bearer | | error="insufficient_authorization_details" | | + | | HTTP body provides authorization_details | | : | | : +--------------------+ | | : | Authorization | | | (D) Authorization | Server | | | Request + RAR |+------------------+| | |---------------------->|| || | | || Authorization || | |<----------------------|| Endpoint || | | (E) Authorization Code|| || | | : |+------------------+| | | : | | | | (F) Token Request |+------------------+| | |---------------------->|| || | | || Token Endpoint || | |<----------------------|| || | | (G) Access Token |+------------------+| | | : +--------------------+ | | : | | : | | (H) Retry API Call +--------------------+ | | with Token | | | |---------------------->| Resource | | | | Server | | |<----------------------| | | | (I) 200 OK + Resource +--------------------+ | | +----------+ Figure: Client remediates using actionable authorization details objects provided by resource server * (A) The user starts the flow. * (B) The client calls an API with an access token. Zehavi Expires 16 December 2026 [Page 8] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 * (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 *required authorization details objects*. * (D) The client uses the obtained authorization details objects in a new OAuth + RAR [RFC9396] request. * (E) Authorization server returns authorization code. * (F-G) The client exchanges authorization code for access token. * (H) The client makes an API request with the (RAR) access token. * (I) Resource server validates access token and returns successful response. 4. Authorization Details Types Metadata Endpoint The following authorization server metadata [RFC8414] parameter is introduced to indicate the server's support for Authorization Details Types Metadata: "authorization_details_types_metadata_endpoint": OPTIONAL. The URL of the Authorization Details Types Metadata endpoint. 4.1. Authorization Details Types Metadata Endpoint Response The Authorization Details Types Metadata endpoint is called with HTTP GET and responds with Content-Type application/json and a JSON object whose members are authorization details type identifiers. Each member value is an object describing a single authorization details type. { "type": { "version": "...", "description": "...", "documentation_uri": "...", "schema": { }, "schema_uri": "...", "examples": [ ] } } Attribute definition: Zehavi Expires 16 December 2026 [Page 9] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 "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 description of the authorization details type. Clients MUST NOT rely on this value for authorization or validation decisions. "documentation_uri": OPTIONAL. URI referencing external documentation describing the authorization details type. "schema": The schema attribute contains a JSON Schema document [JSON.Schema] that describes a single authorization details object. The schema MUST validate exactly one authorization details object and MUST restrict the type attribute to the corresponding authorization details type identifier. This attribute is REQUIRED unless schema_uri is specified. If present, schema_uri MUST NOT be included. "schema_uri": The schema_uri attribute is an absolute URI, as defined by RFC 3986 [RFC3986], 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 Appendix A.1 for non-normative response example. 5. Resource Server Error Signaling of insufficient authorization_details This document defines the Bearer authentication error code insufficient_authorization_details for use in the WWW-Authenticate header field as defined by [RFC6750]. Resource servers SHOULD return insufficient_authorization_details to signal that access is denied due to missing or insufficient authorization details. The insufficient_authorization_details error is intended in cases where the access token is otherwise valid, but the authorization details associated with the token do not satisfy the resource's requirements. The insufficient_authorization_details error MUST NOT be used when the access token is missing, expired, malformed, or otherwise invalid. Existing Bearer authentication error codes are used for those cases. Example HTTP response: Zehavi Expires 16 December 2026 [Page 10] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" 5.1. RECOMMENDED authorization_details_types_required in response body It is RECOMMENDED that resource servers return, alongside the insufficient_authorization_details error, an HTTP body of Content- Type application/json containing the new attribute: authorization_details_types_required. This attribute specifies the required authorization details *types* satisfying resource's RAR [RFC9396] requirements. "authorization_details_types_required": RECOMMENDED. A JSON object that conforms to the syntax described in Section 5.1.1 for a _required types expression_. Note: It is RECOMMENDED that _authorization_details_types_required_ specifies ALL acceptable authorization details types combinations, from ALL supported authorization servers. Example resource server response with RECOMMENDED authorization_details_types_required: HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" Content-Type: application/json { "authorization_details_types_required": { "oneOf": ["payment_initiation", "payment_approval", "beneficiary_designation"] } } 5.1.1. Required types expression syntax The following JSON syntax defines a *required types expression* that describes permitted combinations of required _authorization_details_ types. This expression allows selection operators (oneOf, allOf) and boolean composition (and, or) to be combined in a predictable manner. A *required types expression* is a JSON object that MUST contain *exactly* one of the following attributes: * and * or Zehavi Expires 16 December 2026 [Page 11] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 * oneOf * allOf Attribute definition: "and": OPTIONAL. A non-empty JSON array of _required types expressions_. When *and* is specified, the expression is satisfied if *all* contained expressions are satisfied. "or": OPTIONAL. A non-empty JSON array of _required types expressions_. When *or* is specified, the expression is satisfied if *at least one* contained expression is satisfied. "oneOf": OPTIONAL. A non-empty JSON array of strings identifying authorization_details types. When *oneOf* is specified, the expression is satisfied if *exactly one* of the listed types is present. "allOf": OPTIONAL. A non-empty JSON array of strings identifying authorization_details types. When *allOf* is specified, the expression is satisfied if *all* of the listed types are present. 5.1.2. Required types expression examples 5.1.2.1. Example expression using "and" operator Specifies that the selection MUST include a and b, *and* one of c *or* d. { "and": [ { "allOf": ["a", "b"] }, { "oneOf": ["c", "d"] } ] } 5.1.2.2. Example expression using "or" operator Specifies that the selection MUST include *either* c *and* d, *or* one of a or b. { "or": [ { "allOf": ["c", "d"] }, { "oneOf": ["a", "b"] } ] } Zehavi Expires 16 December 2026 [Page 12] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 5.2. OPTIONAL actionable authorization_details in response body The resource server MAY include, in addition to or instead of the authorization_details_types_required attribute, actionable authorization details objects capable of satisfying the resource's requirements. Note: * Resource servers SHOULD provide authorization_details objects intended to be submitted to the authorization server that issued the access token used for the current (failing) request. This simplifies client and end-user interaction, by continuing with the same authorization server previously used. HTTP response body definition: "authorization_details": OPTIONAL. Array of authorization details objects, matching the format specified in RAR [RFC9396] for the authorization_details request parameter. "authorization_hint": RECOMMENDED. An opaque string generated by the resource server that enables the client to select an existing access token associated with equivalent authorization details without understanding the semantics of the authorization details object. Clients MUST treat this value as opaque. The value SHOULD be stable only within the context of the same resource server, client, subject, and authorization server. The value MUST NOT reveal sensitive information. The resource server SHALL NOT return this attribute when tokens resulting from the provided authorization_details are single-use only. 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: Zehavi Expires 16 December 2026 [Page 13] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" Content-Type: application/json Cache-Control: no-store { "authorization_details_types_required": { "oneOf": ["payment_initiation"] }, "authorization_details": [{ "type": "payment_initiation", "instructed_amount": { "currency": "EUR", "amount": "100.00" }, "creditor_account": { "iban": "DE02120300000000202051" } }], "authorization_hint": "Yb7q3AC5d" } 6. Handling large RAR objects when issuing access tokens RAR [RFC9396] section 9 instructs that authorization servers MUST provide approved RAR objects to resource servers for enforcement. The authorization server MAY add the authorization_details attribute to access tokens in JSON Web Token (JWT) format or to token introspection responses. Including large RAR objects in JWT access tokens may cause interoperability loss due to token sizes exceeding header size restrictions. Authorization servers SHOULD support a configurable *maximum approved RAR objects size threshold*. The size calculation SHOULD be based on the UTF-8 encoded JSON serialization of the approved authorization_details value before JWT signing or encryption. If the size exceeds this threshold, JWT access tokens SHOULD NOT include the authorization_details attribute; instead, the authorization server MUST ensure that the resource server can obtain the approved authorization details by another means, such as token introspection [RFC7662]. 7. Processing Rules Zehavi Expires 16 December 2026 [Page 14] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 7.1. Client Processing Rules * When receiving an insufficient_authorization_details error, if the response body contains an authorization_hint attribute that matches a valid token in the client's possession, the client SHOULD retry the failing request using the matching token. * If the response body contains an authorization_details attribute, the client MAY include it in a subsequent OAuth request to obtain a token, which it MAY then use to retry the failing endpoint. * Otherwise, the client SHOULD use the authorization_details_types_required attribute, if provided in the response body: - Use the response body to understand which authorization details types satisfy the resource's requirements. - If the authorization server metadata contains authorization_details_types_supported, the client MAY use it to determine whether the authorization server supports one or more types referenced by authorization_details_types_required. - Fetch authorization server's authorization_details_types_metadata_endpoint to obtain authorization details types metadata and schemas. - Use the embedded schema value or retrieve the JSON Schema document from schema_uri. * Construct authorization details conforming to the schema and include them in a subsequent OAuth request to obtain an access token with which the client MAY retry calling the failing endpoint. 7.2. Resource Server Processing Rules * Verify access tokens against required authorization details. * When a resource server receives a JWT access token that does not contain an authorization_details claim, and authorization details are required for the requested resource, the resource server SHOULD attempt to obtain the authorization details using token introspection [RFC7662], if introspection is available. * If authorization details are missing or insufficient, the resource server SHALL return HTTP 403 with WWW-Authenticate: Bearer error="insufficient_authorization_details". Zehavi Expires 16 December 2026 [Page 15] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 * It is RECOMMENDED to also provide an HTTP body with the authorization_details_types_required attribute, specifying the required authorization details types to satisfy the resource's requirement. This attribute applies to ALL supported authorization servers. * Resource server MAY also provide in the HTTP body, OPTIONAL actionable authorization_details objects, intended to be submitted to the authorization server that issued the current access token, which MAY be used directly for remediation in a subsequent OAuth request. 8. Security Considerations 8.1. Cacheability and Intermediaries HTTP 403 responses with response bodies may be cached or replayed in unexpected contexts. Resource servers SHOULD mitigate by including the Cache-Control: no-store response header. 8.2. Confidentiality of resource server provided authorization_details Resource server providing actionable authorization_details SHOULD NOT include sensitive data in those objects. This is consistent with RAR [RFC9396] authorization_details OAuth request parameter, representing *request* semantics. Confidentiality-preserving authorization_details types SHOULD NOT include sensitive data. Instead, the end-user SHOULD provide such information when interacting with the authorization server. Alternatively, authorization_details MAY refer to specific end-user resources using opaque reference handles (e.g., "account_1a" instead of using explicit IBAN). 9. IANA Considerations 9.1. OAuth 2.0 WWW-Authenticate Error Code Registry +==================================+========+==========+=============+ |Error Code |Error |Change |Specification| | |Usage |Controller|Document | | |Location| | | +==================================+========+==========+=============+ |insufficient_authorization_details|Resource|IETF |RFC XXXX, | | |access | |Section X | | |error | | | | |response| | | Zehavi Expires 16 December 2026 [Page 16] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 +----------------------------------+--------+----------+-------------+ Table 1 9.2. OAuth Authorization Server Metadata Registry This specification registers the following authorization server metadata parameter in the OAuth Authorization Server Metadata registry: +=============================================+=============+==========+=============+ |Metadata Name |Metadata |Change |Specification| | |Description |Controller|Document | +=============================================+=============+==========+=============+ |authorization_details_types_metadata_endpoint|URL of the |IETF |RFC XXXX, | | |Authorization| |Section X | | |Details Types| | | | |Metadata | | | | |endpoint | | | +---------------------------------------------+-------------+----------+-------------+ Table 2 10. Normative References [IANA.oauth-parameters] IANA, "OAuth Parameters", . [JSON.Schema] Wright, Ed, A., Andrews, Ed, H., Hutton, Ed, B., and G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", June 2022, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . Zehavi Expires 16 December 2026 [Page 17] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, . [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, . [RFC9728] Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, . Appendix A. Examples This section provides non-normative examples of how this specification may be used to support specific use cases. A.1. Authorization Server Metadata Examples A.1.1. Example authorization_details_types_metadata_endpoint response with Payment Initiation HTTP/1.1 200 OK Content-Type: application/json { "payment_initiation": { "version": "1.0", "description": "Authorization to initiate a single payment from a payer account to a creditor account.", "documentation_uri": "https://example.com/docs/payment-initiation", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", Zehavi Expires 16 December 2026 [Page 18] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 "title": "Payment Initiation Authorization Detail", "type": "object", "required": [ "type", "instructed_amount", "creditor_account" ], "properties": { "type": { "const": "payment_initiation", "description": "Authorization details type identifier." }, "actions": { "type": "array", "description": "Permitted actions for this authorization.", "items": { "type": "string", "enum": ["initiate"] }, "minItems": 1, "uniqueItems": true }, "instructed_amount": { "type": "object", "description": "Amount and currency of the payment to be initiated.", "required": ["currency", "amount"], "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code.", "pattern": "^[A-Z]{3}$" }, "amount": { "type": "string", "description": "Decimal monetary amount represented as a string.", "pattern": "^[0-9]+(\\.[0-9]{1,2})?$" } } }, "creditor_account": { "type": "object", "description": "Account to which the payment will be credited.", "required": ["iban"], "properties": { "iban": { "type": "string", "description": "International Bank Account Number (IBAN).", "pattern": "^[A-Z0-9]{15,34}$" Zehavi Expires 16 December 2026 [Page 19] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 } } }, "remittance_information": { "type": "string", "description": "Unstructured remittance information for the payment.", "maxLength": 140 } } } } } A.1.2. Example authorization_details_types_metadata_endpoint response for the Norwegian Health Sector (HelseID) HTTP/1.1 200 OK Content-Type: application/json { "helseid_authorization": { "version": "1.0", "description": "Allows the OAuth client to pass organization information to HelseID.", "documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tekniske-mekanismer/organisasjonsnumre_enmd", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Organization numbers for a multi-tenant client", "type": "object", "properties": { "type": { "type": "string", "const": "helseid_autorization" }, "practitioner_role": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "identifier": { "type": "object", "properties": { "system": { "type": "string" }, "type": { "type": "string" Zehavi Expires 16 December 2026 [Page 20] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 }, "value": { "type": "string" } }, "required": [ "system", "type", "value" ] } }, "required": [ "identifier" ] } }, "required": [ "organization" ] } }, "required": [ "type", "practitioner_role" ] } }, "helseid_trust_framework": { "version": "1.0", "description": "HelseID Trust Framework Information", "documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tekniske-mekanismer/trust-framework", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "Complete Trust Framework structure", "documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tillitsrammeverk/profil_for_tillitsrammeverkmd", "type": "object", "properties": { "type": { "type": "string", "const": "nhn:tillitsrammeverk:parameters" }, "practitioner": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { Zehavi Expires 16 December 2026 [Page 21] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 "code": { "type": "string" }, "system": { "type": "string" } }, "required": [ "code", "system" ] }, "legal_entity": { "type": "object", "properties": { "id": { "type": "string" }, "system": { "type": "string" } }, "required": [ "id", "system" ] }, "point_of_care": { "type": "object", "properties": { "id": { "type": "string" }, "system": { "type": "string" } }, "required": [ "id", "system" ] }, "department": { "type": "object", "properties": { "id": { "type": "string" }, Zehavi Expires 16 December 2026 [Page 22] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 "system": { "type": "string" } }, "required": [ "id", "system" ] } }, "required": [ "authorization", "legal_entity", "point_of_care", "department" ] }, "care_relationship": { "type": "object", "properties": { "healthcare_service": { "type": "object", "properties": { "code": { "type": "string" }, "system": { "type": "string" } }, "required": [ "code", "system" ] }, "purpose_of_use": { "type": "object", "properties": { "code": { "type": "string" }, "system": { "type": "string" } }, "required": [ "code", "system" Zehavi Expires 16 December 2026 [Page 23] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 ] }, "purpose_of_use_details": { "type": "object", "properties": { "code": { "type": "string" }, "system": { "type": "string" } }, "required": [ "code", "system" ] }, "decision_ref": { "type": "object", "properties": { "id": { "type": "string" }, "user_selected": { "type": "boolean" } }, "required": [ "id", "user_selected" ] } }, "required": [ "healthcare_service", "purpose_of_use", "purpose_of_use_details", "decision_ref" ] }, "patients": { "type": "array", "items": { "type": "object", "properties": { "point_of_care": { "type": "object", "properties": { Zehavi Expires 16 December 2026 [Page 24] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 "id": { "type": "string" }, "system": { "type": "string" } }, "required": [ "id", "system" ] }, "department": { "type": "object", "properties": { "id": { "type": "string" }, "system": { "type": "string" } }, "required": [ "id", "system" ] } }, "required": [ "point_of_care", "department" ] } } }, "required": [ "type", "practitioner", "care_relationship", "patients" ] } } } A.2. Resource Server authorization_details_types_required Response Examples Zehavi Expires 16 December 2026 [Page 25] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 A.2.1. Example Resource server authorization_details_types_required response from payments resource HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" Content-Type: application/json Cache-Control: no-store { "authorization_details_types_required": { "oneOf": ["payment_initiation", "payment_approval", "beneficiary_designation"] } } A.2.2. Example Resource server authorization_details_types_required response from the Norwegian Health Sector (HelseID) HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" Content-Type: application/json Cache-Control: no-store { "authorization_details_types_required": { "allOf": ["helseid_authorization", "nhn:tillitsrammeverk:parameters"] } } A.3. Payment initiation with RAR error signaling A.3.1. Client initiates API request Client uses access token obtained at login to call payment initiation API Zehavi Expires 16 December 2026 [Page 26] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 POST /payments HTTP/1.1 Host: resource.example.com Content-Type: application/json Authorization: Bearer eyj... (access token from login) { "type": "payment_initiation", "locations": [ "https://resource.example.com/payments" ], "instructed_amount": { "currency": "EUR", "amount": "123.50" }, "creditor_name": "Merchant A", "creditor_account": { "bic": "ABCIDEFFXXX", "iban": "DE02100100109307118603" } } A.3.2. Resource server signals insufficient_authorization_details with actionable RAR object Resource server requires payment approval and responds with: Zehavi Expires 16 December 2026 [Page 27] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_authorization_details" Content-Type: application/json Cache-Control: no-store { "authorization_details": [{ "type": "payment_initiation", "locations": [ "https://resource.example.com/payments" ], "instructed_amount": { "currency": "EUR", "amount": "123.50" }, "creditor_name": "Merchant A", "creditor_account": { "bic": "ABCIDEFFXXX", "iban": "DE02100100109307118603" }, "interaction_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "risk_profile": "B-71" } ] } Note: the resource server has added the ephemeral attributes interaction_id and risk_profile. A.3.3. Client initiates OAuth flow using the provided authorization_details object After user approves the request, client obtains an access token representing the approved payment A.3.4. Client re-attempts API request Zehavi Expires 16 December 2026 [Page 28] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 POST /payments HTTP/1.1 Host: resource.example.com Content-Type: application/json Authorization: Bearer eyj... (payment approval access token) { "type": "payment_initiation", "locations": [ "https://resource.example.com/payments" ], "instructed_amount": { "currency": "EUR", "amount": "123.50" }, "creditor_name": "Merchant A", "creditor_account": { "bic": "ABCIDEFFXXX", "iban": "DE02100100109307118603" } } A.3.5. Resource server authorizes the request HTTP/1.1 201 Accepted Content-Type: application/json Cache-Control: no-store { "paymentId": "a81bc81b-dead-4e5d-abff-90865d1e13b1", "status": "accepted" } Appendix B. Document History -04 * Moved required authorization details types from resource metadata to resource server's response. * Adapted resource server processing rules to reflect error signaling and handling of large RAR payloads. -03 * Added authorization_hint to guide client on token selection and updated client processing rules accordingly Zehavi Expires 16 December 2026 [Page 29] Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026 * Added security consideration on confidentiality of RS-provided authorization_details * Added authorization server considerations for handling large RAR objects in JWT access tokens -02 * Defined the required types expression * Added Protected Resource Metadata examples -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 The authors would like to thank the following individuals who contributed ideas, feedback, and wording that helped shape the final specification: Rune Grimstad. Author's Address Yaron Zehavi Raiffeisen Bank International Email: yaron.zehavi@rbinternational.com Zehavi Expires 16 December 2026 [Page 30]