OAuth 2.0 RAR Metadata and Error Remediation
draft-ietf-oauth-rar-metadata-remediation-00
| Document | Type | Active Internet-Draft (oauth WG) | |
|---|---|---|---|
| Author | Yaron Zehavi | ||
| Last updated | 2026-08-23 | ||
| Replaces | draft-zehavi-oauth-rar-metadata | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-oauth-rar-metadata-remediation-00
Web Authorization Protocol Y. Zehavi
Internet-Draft Raiffeisen Bank International
Intended status: Standards Track 23 August 2026
Expires: 24 February 2027
OAuth 2.0 RAR Metadata and Error Remediation
draft-ietf-oauth-rar-metadata-remediation-00
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.
In addition, no interoperable guidance is offered to clients, to
remediate failures by resource servers due to insufficient
authorization details.
This document addresses this interoperability challenge, allowing
clients to dynamically discover metadata instead of relying on out-
of-band agreements, as well as standardizes failure signaling
including interoperable remediation when insufficient authorization
details are the cause of failure.
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://drafts.oauth.net/draft-ietf-oauth-rar-metadata-remediation/
draft-ietf-oauth-rar-metadata.html. Status information for this
document may be found at https://datatracker.ietf.org/doc/draft-ietf-
oauth-rar-metadata-remediation/.
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/oauth-wg/draft-ietf-oauth-rar-metadata-
remediation.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Zehavi Expires 24 February 2027 [Page 1]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 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 24 February 2027.
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
4. Remediation of failures due to insufficient authorization . . 6
5. Authorization Details Types Metadata Endpoint . . . . . . . . 9
6. RAR objects in JWT access tokens . . . . . . . . . . . . . . 10
7. Processing Rules . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Client Processing Rules . . . . . . . . . . . . . . . . . 10
7.1.1. Step 1 - Parse the remediation response . . . . . . . 11
7.1.2. Step 2 - Attempt token reuse via
authorization_reference (if present) . . . . . . . . 11
7.1.3. Step 3 - Obtain a new token via OAuth + RAR . . . . . 12
7.1.4. Step 4 - Handle continued failure . . . . . . . . . . 12
7.1.5. Additional guidance . . . . . . . . . . . . . . . . . 12
7.2. Resource Server Processing Rules . . . . . . . . . . . . 13
7.2.1. Step 1 - Validate the access token . . . . . . . . . 13
7.2.2. Step 2 - Verify authorization details (if present) . 13
7.2.3. Step 3 - If authorization details are missing or
insufficient . . . . . . . . . . . . . . . . . . . . 13
Zehavi Expires 24 February 2027 [Page 2]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
7.3. Limitations and Considerations for
authorization_reference . . . . . . . . . . . . . . . . . 14
7.3.1. Token reuse is opportunistic, not guaranteed . . . . 14
7.3.2. authorization_reference does not replace
authorization_details . . . . . . . . . . . . . . . . 14
7.3.3. Loop prevention . . . . . . . . . . . . . . . . . . . 14
7.3.4. No cross-resource-server portability . . . . . . . . 15
7.3.5. Analogy to scope-based token selection . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
8.1. 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 . . . . . . 16
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
Appendix B. Document History . . . . . . . . . . . . . . . . . . 26
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 27
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27
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:
* 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 as the
cause of the error.
Zehavi Expires 24 February 2027 [Page 3]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
* A new OAuth 2.0 WWW-Authenticate response parameter,
authorization_remediation, providing actionable authorization
details objects, to be used directly for remediation in a follow-
up OAuth request.
* Authorization server considerations for when RAR authorization
details objects should perhaps be omitted from JWT access tokens
and provided instead through token instrospection.
Providing clients with actionable authorization details objects
enables:
* Interoperability benefit as clients can simply and directly
proceed to remediate, without first learning how to construct
valid authorization details objects.
* Support for ephemeral, interaction-specific attributes included by
the resource server, such as a risk profile or an internal
interaction identifier, guiding authorization servers on the
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
Client remediates using actionable authorization details objects
provided by resource server:
Zehavi Expires 24 February 2027 [Page 4]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
+--------------------+
+----------+ (B) API Request | |
| |---------------------->| Resource |
(A) User +---| | | Server |
Starts| | |<----------------------| |
Flow +-->| Client | (C) 401 Unauthorized +--------------------+
| | WWW-Authenticate: Bearer
| | error="insufficient_authorization",
| | error_description=[human readable message],
| | authorization_remediation=[required
| | 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 24 February 2027 [Page 5]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
* (C) Resource server returns HTTP 401 with a WWW-Authenticate
header with error code insufficient_authorization and in
authorization_remediation the *required authorization details
objects*.
* (D) The client uses the provided 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. Remediation of failures due to insufficient authorization
This document defines:
* The authentication error code insufficient_authorization for the
WWW-Authenticate header. Resource servers SHOULD return
insufficient_authorization when access is denied due to missing or
insufficient authorization details.
* The authorization_remediation error parameter, which contains a
base64url-encoded JSON object guiding the client on remediating
the error. Its attributes are:
- authorization_details: RECOMMENDED. Array of actionable
authorization details objects, matching the format specified in
RAR [RFC9396] for the authorization_details request parameter,
built using the failed resource request. Their inclusion in
successful new OAuth grant SHALL satisfy the resource's
requirements and remediate the failure.
- authorization_reference: RECOMMENDED. An opaque string
generated by the resource server to enable the client to select
an existing access token associated with equivalent
authorization details, without requiring the client to
understand the semantics of the authorization details object:
o Resource server SHOULD generate the authorization_reference
by canonicalizing and hashing the authorization_details
object or an equivalent stable representation, so that the
same or semantically equivalent authorization details
produce the same authorization_reference value.
Zehavi Expires 24 February 2027 [Page 6]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
o The value MUST NOT reveal any sensitive or private
information.
o Clients MUST treat this value as opaque and MUST NOT attempt
to interpret or derive meaning from it.
o Returning stable authorization_reference values enables
clients to reliably match existing tokens to incoming
authorization_remediation responses, to avoid requesting new
tokens when a matching token is already in their possession.
o The resource server SHALL NOT include this attribute when
tokens issued for the provided authorization_details are
intended for single-use only.
Notes:
* The error_description parameter MAY be included to provide a
human-readable description.
* The provided authorization_details are intended to be
interoperable with all OAuth specifications and usable in any
grant flow supporting RAR.
* Deployments where resource servers have out-of-band agreements
with clients to provide other types of payloads for authorization
failure remediation, MAY define and use different attributes of
authorization_remediation as they see fit.
Example HTTP response from a direct debit resource:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_authorization",
error_description="Additional authorization is required",
authorization_remediation=eyJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7InR5cGUiOiJkaX...
The decoded authorization_remediation contents in this example are:
Zehavi Expires 24 February 2027 [Page 7]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
{
"authorization_details": [{
"type": "direct_debit_mandate",
"DebtorAccount": {
"SchemeName": "UK.OBIE.SortCodeAccountNumber",
"Identification": "08080021325698",
"Name": "JohnDoe"
},
"CreditorAgent": {
"SchemeName": "UK.OBIE.BICFI",
"Identification": "NWBKGB22"
},
"CreditorAccount": {
"SchemeName": "UK.OBIE.SortCodeAccountNumber",
"Identification": "08080021325698",
"Name": "ACMECorp"
},
"MandateStatus": "Active",
"CreationDateTime": "2026-06-01T09:00:00+00:00"
}
],
"authorization_reference": "Yb7q3AC5d"
}
Example HTTP response from a payment initiation resource:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_authorization",
error_description="Additional authorization is required",
authorization_remediation=eyJhdXRob3JpemF0aW9uX2RldGFpbHMiOlt7InR5cGUiOiJkaX...
The decoded authorization_remediation contents in this example are:
{
"authorization_details": [{
"type": "payment_initiation",
"instructed_amount": {
"currency": "EUR",
"amount": "100.00"
},
"creditor_account": {
"iban": "DE02120300000000202051"
}
}
]
}
Zehavi Expires 24 February 2027 [Page 8]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
5. 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.
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:
"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.
Zehavi Expires 24 February 2027 [Page 9]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"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.
6. RAR objects in JWT access tokens
Pursuant with RAR [RFC9396] section 9, 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.
There may however be cases, where due to various considerations such
as token size or information privacy, including approved RAR objects
in JWT access tokens would be advised against.
It is RECOMMENDED that when an authorization server issues JWT access
tokens, it should consider the size, sensitivity, and privacy
implications of including the authorization_details attribute. Where
appropriate, the authorization server SHOULD omit this attribute from
JWT tokens and instead provide the approved RAR objects to resource
servers via the token introspection endpoint. This endpoint SHOULD
use appropriate client authentication methods to prevent unauthorized
access, in case of token leakage.
7. Processing Rules
7.1. Client Processing Rules
*General*:
Client MAY attempt calling resource server, either on first attempt
or as a remediation step, using any valid tokens which were obtained
following a remediation challenge from same resource server origin,
which included an authorization_reference, as such tokens are not
limited for single-use.
Existing tokens whose authority is inclusive may permit resource
calls requiring lower authority, despite their
authorization_reference value differs from value obtained in other
Zehavi Expires 24 February 2027 [Page 10]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
remediation challenges. For example, a recurring direct debit token
permitting up to 100$ can authorize a 80$ debit, although the
remediation challenges returned when attempting 80$ or 100$ debits
with insufficient authority, will differ in their
authorization_details and authorization_reference values.
Therefore attempting a 80$ debit with an existing token permitting
100$ debits may succeed.
*Handling an HTTP 401 failure response*:
When a client receives an HTTP 401 response with WWW-Authenticate
error code insufficient_authorization and an
authorization_remediation parameter, it SHOULD process it as follows.
7.1.1. Step 1 - Parse the remediation response
The client decodes the base64url-encoded authorization_remediation
JSON object and extracts:
* authorization_details (RECOMMENDED): the actionable RAR objects.
* authorization_reference (OPTIONAL): an opaque string for token-bag
lookup.
7.1.2. Step 2 - Attempt token reuse via authorization_reference (if
present)
1. If the authorization_remediation contains an
authorization_reference attribute, the client SHOULD search its
*in-session tokens* for a token previously associated with that
reference value *and* the same resource server origin.
2. Matching is a simple string comparison — the client MUST NOT
attempt to compute, parse, or derive meaning from the reference
value.
3. If a matching, non-expired token is found, the client MAY retry
the failing request with that token. If the retry also fails
with insufficient_authorization, the client MUST NOT retry again
with the same token for the same reference and SHOULD proceed to
Step 3.
4. If no matching token is found, the client proceeds to Step 3.
Zehavi Expires 24 February 2027 [Page 11]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
7.1.3. Step 3 - Obtain a new token via OAuth + RAR
The client proceeds to this step if: (a) no authorization_reference
was present, (b) no matching token in client's possession was found,
(c) a matched token was rejected by the resource server (Step 2, item
4), or (d) the client elects to skip an existing token lookup and use
authorization_details directly.
1. The client uses the authorization_details from the
authorization_remediation response in a new OAuth authorization
request per [RFC9396]. The client MAY use any grant type or
extension that supports RAR (such as PAR [RFC9126], JAR
[RFC9101], etc).
2. Upon successful token issuance, if the triggering resource server
response included an authorization_reference, the client SHOULD
persist the newly obtained token associated with that reference
value and the resource server origin in its in-session token
storage. This token-to-reference association enables future
lookups in Step 2 when the same authorization_reference is
encountered again.
3. The client retries the failing request with the newly obtained
token.
7.1.4. Step 4 - Handle continued failure
If after obtaining a new token and retrying, the resource server
still returns insufficient_authorization:
* If the new response contains a *different*
authorization_reference, the client MAY attempt remediation again
(subject to implementation-defined retry limits).
* If the new response contains the *same* authorization_reference,
the client MUST NOT loop — it SHOULD treat the failure as non-
remediable and report an error to the user or calling application.
7.1.5. Additional guidance
* Clients MAY ignore authorization_reference entirely if they do not
implement token caching or reuse. In that case, each
insufficient_authorization response triggers a fresh authorization
request using the provided authorization_details.
Zehavi Expires 24 February 2027 [Page 12]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
* If the client's current authorization server does not support the
required authorization details types (as indicated by its
metadata), the client MAY use Protected Resource Metadata
[RFC9728] to discover alternative authorization servers for the
resource.
* The token storage MUST be scoped per end-user session. Concurrent
users operating through the same client instance MUST maintain
separate token storage instances.
7.2. Resource Server Processing Rules
When a resource server receives a request with an OAuth token:
7.2.1. Step 1 - Validate the access token
Verify token validity following [RFC6750] or [RFC9068] if JWT
profiled. If the token is invalid for reasons other than
insufficient authorization details, return the appropriate existing
error code (e.g., invalid_token).
7.2.2. Step 2 - Verify authorization details (if present)
Determine whether the token carries sufficient authorization details
for the requested operation. Authorization details MAY be obtained
from the JWT access token payload or via token introspection
[RFC7662].
7.2.3. Step 3 - If authorization details are missing or insufficient
The resource server responds with an error per the bearer token error
framework [RFC6750] Section 3. The specific error code depends on
the nature of the failure: - If the token is valid but lacks
sufficient *scope*, the resource server returns insufficient_scope
per [RFC6750] Section 3.1. - If the token is valid but lacks
sufficient *authentication context* (e.g., ACR/AMR level), the
resource server returns insufficient_user_authentication per
[RFC9470]. - If the token is valid but lacks sufficient
*authorization details*, the RS returns insufficient_authorization
per Section 4 of this document, with an authorization_remediation
parameter as defined in Section 4.1. The authorization_remediation
parameter carries the actionable authorization_details and optional
authorization_reference as specified in Section 4. The resource
server constructs these per the rules defined below.
Zehavi Expires 24 February 2027 [Page 13]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
7.3. Limitations and Considerations for authorization_reference
Implementers should be aware of the following limitations:
7.3.1. Token reuse is opportunistic, not guaranteed
A matching authorization_reference with client's existing tokens does
NOT guarantee the token will be accepted by the resource server. The
token may have been issued under conditions that no longer apply:
* The resource owner may have revoked consent since the token was
issued.
* Contextual risk may have changed (e.g., geolocation, device
posture), causing the resource server to require stronger
authorization ceremonies.
* The authorization server may have issued the token with a subset
of the requested authorization details (per [RFC9396] Section 7).
Clients MUST handle the case where a reused token is rejected despite
matching the authorization_reference (see Section 7.1, Step 2, item
4).
7.3.2. authorization_reference does not replace authorization_details
The authorization_reference is an optimization for token selection.
It is NOT a substitute for authorization_details:
* authorization_details is RECOMMENDED in every
authorization_remediation response providing actionable RAR
objects and is what the client uses when initiating a new
authorization request.
* authorization_reference is RECOMMENDED and enables the client to
avoid unnecessary authorization flows when it already possesses a
suitable token.
Clients that do not implement token caching MAY safely ignore
authorization_reference with no loss of interoperability.
7.3.3. Loop prevention
If the resource server consistently returns the same
authorization_reference and rejects tokens obtained via the
associated authorization_details, the client may enter an infinite
loop. To prevent this:
Zehavi Expires 24 February 2027 [Page 14]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
* Clients MUST implement a maximum retry count (RECOMMENDED: 1 retry
with a cached token, then 1 fresh authorization attempt, then
fail).
* If a freshly obtained token (from a new authorization flow using
the resource server provided authorization_details) is immediately
rejected by the same resource server with the same
authorization_reference, the client MUST stop and report the
error.
7.3.4. No cross-resource-server portability
The authorization_reference value is scoped to the producing resource
server. It MUST NOT be used for token selection when interacting
with a different resource server, even if the two servers enforce
similar authorization details types.
7.3.5. Analogy to scope-based token selection
The authorization_reference mechanism is analogous to how clients
select tokens based on OAuth scopes in traditional deployments. Just
as a client maintains a mapping of {scope → token} and selects the
appropriate token for each resource server call, this mechanism
extends that pattern to RAR:
+=========================+================================+
| Traditional (scope- | RAR + authorization_reference |
| based) | |
+=========================+================================+
| Resource server returns | Resource server returns |
| insufficient_scope with | insufficient_authorization |
| required scope value | with authorization_remediation |
+-------------------------+--------------------------------+
| Client checks if it has | Client checks if it has a |
| a token with matching | token with matching |
| scope | authorization_reference |
+-------------------------+--------------------------------+
| Simple string | Simple string comparison on |
| comparison on scope | reference values |
| values | |
+-------------------------+--------------------------------+
| If not found, request | If not found, request new |
| new token with required | token with provided |
| scope | authorization_details |
+-------------------------+--------------------------------+
Table 1
Zehavi Expires 24 February 2027 [Page 15]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
The key advantage: clients do not need to understand, parse, or
compare complex JSON authorization_details objects — the resource
server has already reduced the comparison to an opaque string.
8. Security Considerations
8.1. Confidentiality of resource server provided authorization_details
Resource servers when 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 |Resource| IETF | RFC XXXX, |
| |access | | Section X |
| |error | | |
| |response| | |
+----------------------------+--------+------------+---------------+
Table 2
9.2. OAuth Authorization Server Metadata Registry
This specification registers the following authorization server
metadata parameter in the OAuth Authorization Server Metadata
registry:
Zehavi Expires 24 February 2027 [Page 16]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
+=============================================+=============+==========+=============+
|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 3
10. Normative References
[IANA.oauth-parameters]
IANA, "OAuth Parameters",
<https://www.iana.org/assignments/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,
<https://json-schema.org/draft/2020-12/json-schema-core>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[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,
<https://www.rfc-editor.org/rfc/rfc3986>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/rfc/rfc6750>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/rfc/rfc7662>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
Zehavi Expires 24 February 2027 [Page 17]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/rfc/rfc8414>.
[RFC9068] Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0
Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October
2021, <https://www.rfc-editor.org/rfc/rfc9068>.
[RFC9101] Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0
Authorization Framework: JWT-Secured Authorization Request
(JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021,
<https://www.rfc-editor.org/rfc/rfc9101>.
[RFC9126] Lodderstedt, T., Campbell, B., Sakimura, N., Tonge, D.,
and F. Skokan, "OAuth 2.0 Pushed Authorization Requests",
RFC 9126, DOI 10.17487/RFC9126, September 2021,
<https://www.rfc-editor.org/rfc/rfc9126>.
[RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", RFC 9396,
DOI 10.17487/RFC9396, May 2023,
<https://www.rfc-editor.org/rfc/rfc9396>.
[RFC9470] Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up
Authentication Challenge Protocol", RFC 9470,
DOI 10.17487/RFC9470, September 2023,
<https://www.rfc-editor.org/rfc/rfc9470>.
[RFC9728] Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0
Protected Resource Metadata", RFC 9728,
DOI 10.17487/RFC9728, April 2025,
<https://www.rfc-editor.org/rfc/rfc9728>.
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
Zehavi Expires 24 February 2027 [Page 18]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
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",
"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})?$"
}
}
Zehavi Expires 24 February 2027 [Page 19]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
},
"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}$"
}
}
},
"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": {
Zehavi Expires 24 February 2027 [Page 20]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"type": "object",
"properties": {
"identifier": {
"type": "object",
"properties": {
"system": {
"type": "string"
},
"type": {
"type": "string"
},
"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": {
Zehavi Expires 24 February 2027 [Page 21]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"type": {
"type": "string",
"const": "nhn:tillitsrammeverk:parameters"
},
"practitioner": {
"type": "object",
"properties": {
"authorization": {
"type": "object",
"properties": {
"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": [
Zehavi Expires 24 February 2027 [Page 22]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"id",
"system"
]
},
"department": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"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": {
Zehavi Expires 24 February 2027 [Page 23]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"code": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"code",
"system"
]
},
"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"
Zehavi Expires 24 February 2027 [Page 24]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
]
},
"patients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"point_of_care": {
"type": "object",
"properties": {
"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",
Zehavi Expires 24 February 2027 [Page 25]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 2026
"care_relationship",
"patients"
]
}
}
}
Appendix B. Document History
-06
* Expanded processing rules to be more explicit, using Jeff
Lombardo's feedback.
* Explained how potential reuse of existing tokens is possible
despite authorization_reference mismatches.
-05
* Removed required authorization details types.
* Changed from HTTP 403 to 401.
* Moved resource servers response from body to WWW-Authenticate
header.
* Renamed authorization_hint to authorization_reference and
clarified its usage.
* Clarified authorization server broader considerations on omitting
RAR from JWT access tokens.
* Clarified document's interoperability with any OAuth rfc and any
grant that supports RAR.
-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_reference to guide client on token selection
and updated client processing rules accordingly
Zehavi Expires 24 February 2027 [Page 26]
Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia August 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, Justin Richer, Jeff Lombardo, Judith
Kahrer, Pieter Kasselman.
Author's Address
Yaron Zehavi
Raiffeisen Bank International
Email: yaron.zehavi@rbinternational.com
Zehavi Expires 24 February 2027 [Page 27]