Internet-Draft OAuth 2.0 RAR Metadata and Error Remedia July 2026
Zehavi Expires 5 January 2027 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-zehavi-oauth-rar-metadata-05
Published:
Intended Status:
Standards Track
Expires:
Author:
Y. Zehavi
Raiffeisen Bank International

OAuth 2.0 RAR Metadata and Error Remediation

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://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.

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 5 January 2027.

▲

Table of Contents

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:

Providing clients with actionable authorization details objects enables:

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:

                                                +--------------------+
             +----------+ (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

4. Remediation of failures due to insufficient authorization

This document defines:

Notes:

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:

{
    "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"
           }
       }
   ]
}

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.

"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

  • When receiving an insufficient_authorization error, if the authorization_remediation parameter contains an authorization_reference attribute that matches a valid token in the client's possession, the client MAY retry the failing request using the matching token.

  • If the authorization_remediation parameter contains an authorization_details attribute, the client MAY include it in a subsequent OAuth request to obtain a token for retrying the failing endpoint.

  • If the authorization server used so far by the client does not support the required authorization details types, the client MAY use Protected Resource Metadata [RFC9728] to discover additional authorization_servers supported by the resource, and attempt remediation through them.

  • Clients MAY ignore authorization_reference if they do not support token reuse or caching.

7.2. Resource Server Processing Rules

  • Verify access token validity.

  • Verify required authorization details are provided, by JWT token contents or through token introspection [RFC7662].

  • If authorization details are missing or insufficient, return HTTP 401 with WWW-Authenticate: Bearer error="insufficient_authorization" including the authorization_remediation parameter which provides actionable authorization_details objects constructed from the failing request's input.

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

Table 1
Error Code Error Usage Location Change Controller Specification Document
insufficient_authorization Resource access error response IETF RFC XXXX, Section X

9.2. OAuth Authorization Server Metadata Registry

This specification registers the following authorization server metadata parameter in the OAuth Authorization Server Metadata registry:

Table 2
Metadata Name Metadata Description Change Controller Specification Document
authorization_details_types_metadata_endpoint URL of the Authorization Details Types Metadata endpoint IETF RFC XXXX, Section X

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", , <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, , <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, , <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, , <https://www.rfc-editor.org/rfc/rfc6750>.
[RFC7662]
Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, , <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, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8414]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, , <https://www.rfc-editor.org/rfc/rfc8414>.
[RFC9396]
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, , <https://www.rfc-editor.org/rfc/rfc9396>.
[RFC9728]
Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, , <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 

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})?$"
                        }
                    }
                },
                "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": {
                            "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": {
                "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": [
                                "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": {
                                "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"
                    ]
                },
                "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",
                "care_relationship",
                "patients"
            ]
        }
    }
}

Appendix B. Document History

-05

-04

-03

-02

-01

-00

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