Summary

  • draft-ietf-oauth-rar-metadata-remediation-00 lets a resource server answer a valid-but-insufficient OAuth request with actionable Rich Authorization Request objects that a client may use in a new authorization flow.
  • The resource server does not grant authority. It proposes what it considers sufficient; the authorization server and resource owner still validate, consent to, narrow or refuse the request, and the resource server later decides whether the resulting token is acceptable.
  • Daniel Kade proposes an authority-delta record that preserves the failed operation, current authority, proposed details, schema provenance, consent result, granted details and eventual resource effect. This is governance guidance outside the draft.

The denial that contains the next request

Consider a treasury application attempting to create a direct-debit mandate. It presents a valid access token, but the token carries no authorization details for that transaction. Under ordinary error handling, the client might receive a denial, display a vague message and send a person elsewhere to obtain more access. The parties then depend on documentation, product conventions or a private integration agreement to work out what “more” means.

The first OAuth Working Group draft on RAR metadata and error remediation proposes a more interoperable path. A resource server can return HTTP 401 with the new error insufficient_authorization. Its authorization_remediation parameter can contain authorization_details built from the failed request and an optional authorization_reference. The client may look for an existing token or place the supplied details directly into a new OAuth authorization request.

That flow solves a real coordination problem. RFC 9396 gave OAuth a structured language for fine-grained authorization, but it did not tell a client how to discover every detail type or how to recover when a protected resource says the token lacks the required details. Revision 00 adds a metadata endpoint for schemas and examples, a failure signal, and processing rules for remediation.

The draft is active working-group work dated 23 August 2026. It replaces an individual draft after the IETF 126 OAuth session recorded support for the problem space, debate about the solution and a call for adoption. It is not an RFC, has no telechat date, and does not supply deployment results. Proposed registry entries are requests, not completed IANA assignments.

Its importance does not depend on pretending otherwise. A resource server that can express the missing authorization precisely is more useful than one that can only emit a generic denial. The governance question begins because the useful response is not neutral.

A resource server proposes; it does not grant

The draft says the actionable details are built using the failed resource request and that including them in a successful new grant shall satisfy the resource's requirements. That makes the resource server the author of a consequential proposal. It identifies the structured authority it wants to see before it will perform the operation.

But the proposal crosses several control boundaries before it becomes usable authority. The client chooses whether to process the challenge. The authorization server validates the detail type, applies policy and runs the relevant grant flow. RFC 9396 requires the authorization server to present requested permissions for consent; the resource owner may grant only a subset. The token response reports the authorization details actually granted. The resource server then evaluates the token and the operation again.

Those steps prevent a correct description from becoming “the resource server grants itself permission.” It does not. They also prevent the opposite simplification: “nothing changed because consent still exists.” A new request for authority has been generated, and automation may transport it through the decision path with little visible friction.

The distinction is clearest when the failed request and proposed object do not have the same operational meaning. A client may have attempted to read one account, while the remediation object describes a recurring mandate. A device may have tried one action, while contextual risk causes the resource server to require a stronger ceremony or a more specific data set. The proposal may be narrower, broader, equivalent, incomparable or simply unknown under the client's local policy.

Raw JSON size cannot answer that question. RFC 9396 explicitly says there is no standard mechanism for comparing two arbitrary authorization-detail requests because their fields are defined by individual APIs. Fewer properties need not mean less authority; an omitted limit can activate a default, an array can represent a union, and a resource identifier can change the protected subject entirely.

The opaque reference is a lookup key, not a policy verdict

The optional authorization_reference is designed to spare clients from understanding complex objects when selecting a token. A resource server should derive a stable opaque value for the same or semantically equivalent details. A client can compare that value with references stored beside tokens from the same resource-server origin and the same end-user session.

This is deliberately modest. The client must not interpret the reference. It cannot use it across resource servers. The server must not include it when tokens are intended for single use. A matching value does not guarantee that a stored token will work: consent may have been revoked, risk context may have changed, or the authorization server may have issued a subset of what was requested.

Nor does a different reference prove that one authority is greater than another. The draft notes that a token permitting recurring debits up to 100 may satisfy a request for 80 even when the two remediation references differ. Inclusion is a semantic relation, not opaque-string equality. The reference accelerates token-bag lookup; the resource server still decides whether the token authorizes the operation.

This separation is a strong design choice. Trouble begins when product telemetry collapses it. A log line such as reference matched may be displayed as “authorization satisfied,” even though it records only selection of a candidate credential. Conversely, reference changed may trigger another authorization flow without showing whether the requested authority changed materially.

Metadata validates shape, not purpose

Revision 00 also proposes an authorization-details-types metadata endpoint. Each type can publish an informational version, description, documentation URI, examples and either an embedded JSON Schema or a schema URI. The schema must describe one object and restrict its type field to the relevant identifier.

This helps clients construct and validate objects. It does not make the metadata a policy oracle. The draft says descriptions are not inputs to authorization or validation decisions, examples are non-normative, and the version does not imply semantic-version negotiation. A schema can say that an amount is a string in a required object. It cannot, by itself, say that the amount is appropriate for this person, that a recurring mandate matches the original purpose, or that the consent screen explained the consequence adequately.

Schema provenance still matters. If a client receives remediation under one schema and asks for authority after the type definition changes, identical-looking fields may no longer have identical meaning. An operator needs to know which document or schema digest informed validation and which policy implementation interpreted it. Merely recording the type name loses the decision surface.

The metadata path can also redirect trust. When a client's current authorization server does not support the needed type, the draft permits discovery of alternative authorization servers through Protected Resource Metadata. That is useful interoperability, but it makes the selected issuer part of the evidence. A new issuer is not a transparent retry target. It may have different client registration, authentication, consent, retention and policy arrangements.

An authority-delta record

I propose an authority-delta record. It is not a new OAuth claim, header, registry or protocol requirement. It is an operational record maintained around the remediation flow so that recovery does not erase the fact that a new authority proposal entered the system.

The record begins with the denial. It identifies the end-user session and resource-server origin; commits to the failed request and operation class; and records the effective scopes or authorization details of the token that was presented. Sensitive account, patient or transaction values should be excluded, replaced with narrow opaque references, or protected by short-lived salted commitments.

It then preserves the proposal: a digest of the decoded authorization_remediation, a safe human-readable rendering of the requested effect, the authorization_reference, the authorization-detail type, the schema URI or embedded-schema digest, the informational version and the time at which metadata was fetched. It records whether the client classified the proposed authority as unchanged, narrower, broader, incomparable or unknown, and names the type-specific evaluator and policy version that made that judgment.

Next comes disposition. Did the client reject the challenge, find an existing token, start a new authorization flow, ask for confirmation or route the case to an operator? Which authorization server was selected, and did that choice differ from the client's existing issuer? Which consent-screen version was shown? What did the resource owner approve, narrow or refuse? What authorization details did the token response say were actually granted?

Finally, the record follows the retry. It stores the reference association only within the relevant user session and resource-server origin; counts the cached-token and fresh-authorization attempts; records the final resource decision; and joins that decision to the operation's outcome or rollback reference. It never stores the token, secret or full sensitive RAR object merely to make audit convenient.

This gives each actor a bounded statement. The resource server can prove what it proposed. The client can prove how it handled the proposal. The authorization server can prove what it presented and issued. The resource owner can be associated with the decision actually made. The final resource response can be linked without claiming that a successful OAuth exchange proves the business operation completed correctly.

Privacy is part of the control, not an audit exemption

RAR objects can describe bank accounts, medical records, locations and transaction terms. The remediation draft advises resource servers not to place sensitive data in actionable details and permits opaque handles. It also advises authorization servers to consider privacy and token size before embedding approved details in JWT access tokens, using authenticated introspection where appropriate.

An authority-delta record should follow the same restraint. The audit purpose is to preserve relationships among decisions, not to create a second database of protected-resource contents. Hashing alone is not always anonymity: low-entropy account labels and predictable amounts can be guessed. Commitments need salts, limited retention and access controls. A human-readable rendering should describe the effect at the minimum useful level—“create recurring debit up to policy limit,” for example—without copying an account number into general logs.

The record must also distinguish what came from whom. A resource-server-provided account handle is not user testimony. A schema description is not a consent statement. A token's granted details are not proof that a person read the interface. Provenance labels make the evidence less convenient but more honest.

Error recovery can become policy automation

The draft includes necessary loop controls. A client should try at most one matching cached token and one fresh authorization flow before failing when the same reference returns. A different reference may permit another attempt, subject to an implementation-defined maximum. Token storage must remain separated by end-user session.

These safeguards limit mechanical repetition. They do not determine when another attempt is substantively appropriate. A sequence of different references could reflect legitimate changing context, unstable policy, or a staircase of authority proposals. An implementation that counts only identical references can satisfy the loop rule while repeatedly asking a user for adjacent or expanding grants.

The better operational limit therefore has two dimensions. One counts protocol attempts. The other limits authority change: unexpected issuer, high-impact action, new resource class, wider recurrence, longer duration, changed schema or an incomparable object. Crossing that boundary should stop silent recovery and require a fresh explanation or accountable review.

That is the durable lesson. An actionable denial is valuable because it turns an interoperability gap into a structured decision. It becomes dangerous only when a system labels every structured decision as plumbing. A retry repeats an operation under existing authority. RAR remediation may ask for different authority. The evidence should preserve the difference before the eventual effect makes it impossible to reconstruct.

Sources

  1. OAuth RAR metadata and remediation draft
  2. Draft history
  3. Datatracker API record
  4. Working-group revision 00
  5. Revision 00 text
  6. Predecessor source repository
  7. IETF 126 OAuth minutes
  8. OAuth Working Group charter
  9. RFC 9396: Rich Authorization Requests
  10. RFC 6750: Bearer Token Usage
  11. RFC 8414: Authorization Server Metadata
  12. RFC 9728: Protected Resource Metadata
  13. RFC 9470: Step Up Authentication Challenge
  14. RFC 7662: Token Introspection
  15. RFC 9068: JWT Access Token Profile
  16. RFC 9126: Pushed Authorization Requests
  17. RFC 9101: JWT-Secured Authorization Request
  18. IANA OAuth parameters
  19. Revision 00 XML source
  20. Predecessor repository issues