OAuth 2.0 Insufficient Claims Challenge
draft-mcguinness-oauth-insufficient-claims-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Karl McGuinness | ||
| Last updated | 2026-05-27 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-mcguinness-oauth-insufficient-claims-00
Web Authorization Protocol K. McGuinness
Internet-Draft Independent
Intended status: Standards Track 27 May 2026
Expires: 28 November 2026
OAuth 2.0 Insufficient Claims Challenge
draft-mcguinness-oauth-insufficient-claims-00
Abstract
This specification defines an OAuth 2.0 challenge mechanism by which
an Authorization Server or Protected Resource signals that a
credential presented by a Client is otherwise acceptable but lacks
claims required to fulfill the request. A new error code,
insufficient_claims, together with a required_claims parameter that
enumerates the missing claims, lets the recipient signal what is
needed. The same challenge is used in Token Endpoint error
responses, in Bearer authentication challenges at Protected
Resources, and (optionally) in OAuth 2.0 Protected Resource Metadata.
The challenge is intentionally decoupled from how the Client
responds. For back-channel re-issuance grants (OAuth 2.0 Token
Exchange and Refresh Token), a Client uses the requested_claims Token
Endpoint request parameter defined here. For grants that may require
end-user interaction (authorization_code, device_code, CIBA), a
Client uses an applicable front-channel claims request mechanism,
such as the OpenID Connect claims request parameter.
A motivating use case is just-in-time account provisioning by a
Resource Authorization Server receiving an identity assertion under
the Identity Assertion Authorization Grant.
About This Document
This note is to be removed before publishing as an RFC.
Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-mcguinness-oauth-insufficient-
claims/.
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/.
McGuinness Expires 28 November 2026 [Page 1]
Internet-Draft OAuth Claims Challenge May 2026
Source for this draft and an issue tracker can be found at
https://github.com/mcguinness/draft-mcguinness-oauth-insufficient-
claims.
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 28 November 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 . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Why a New Error Code . . . . . . . . . . . . . . . . . . 6
1.2. Motivating Use Cases . . . . . . . . . . . . . . . . . . 6
1.2.1. Just-in-Time Account Provisioning at a Resource
Authorization Server . . . . . . . . . . . . . . . . 6
1.2.2. Resource-Side Claim Requirements . . . . . . . . . . 6
1.2.3. Multi-Resource Refresh Tokens . . . . . . . . . . . . 7
1.2.4. Other Assertion-Based Grants . . . . . . . . . . . . 7
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 7
3. The Insufficient Claims Challenge . . . . . . . . . . . . . . 8
3.1. Error Code . . . . . . . . . . . . . . . . . . . . . . . 8
McGuinness Expires 28 November 2026 [Page 2]
Internet-Draft OAuth Claims Challenge May 2026
3.2. Response Parameter . . . . . . . . . . . . . . . . . . . 8
3.3. Returned at the Token Endpoint . . . . . . . . . . . . . 10
3.4. Returned at the Protected Resource . . . . . . . . . . . 11
4. Client Remediation . . . . . . . . . . . . . . . . . . . . . 12
4.1. Back-Channel Token Endpoint Request Parameter . . . . . . 13
4.1.1. Use with Token Exchange . . . . . . . . . . . . . . . 14
4.1.2. Use with Refresh Token . . . . . . . . . . . . . . . 15
4.2. Interactive Grants . . . . . . . . . . . . . . . . . . . 15
4.3. Authorization Server Behavior . . . . . . . . . . . . . . 16
4.4. No Loop Guarantee . . . . . . . . . . . . . . . . . . . . 16
5. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1. Protected Resource Metadata . . . . . . . . . . . . . . . 17
5.2. Authorization Server Metadata . . . . . . . . . . . . . . 18
6. End-to-End Examples . . . . . . . . . . . . . . . . . . . . . 18
6.1. Token Exchange Retry . . . . . . . . . . . . . . . . . . 19
6.2. Protected Resource Challenge . . . . . . . . . . . . . . 19
7. Relationship to Other Specifications . . . . . . . . . . . . 20
7.1. Identity Assertion Authorization Grant . . . . . . . . . 20
7.2. Assertion-Based Grants . . . . . . . . . . . . . . . . . 21
7.3. OAuth 2.0 scope Parameter . . . . . . . . . . . . . . . . 21
7.4. OAuth 2.0 Resource Indicators . . . . . . . . . . . . . . 22
7.5. OpenID Connect claims Request Parameter . . . . . . . . . 22
7.6. OAuth 2.0 Bearer Token Usage and Step-Up
Authentication . . . . . . . . . . . . . . . . . . . . . 23
7.7. OAuth 2.0 Rich Authorization Requests . . . . . . . . . . 24
8. Security Considerations . . . . . . . . . . . . . . . . . . . 24
8.1. Disclosure of Claim Requirements . . . . . . . . . . . . 24
8.2. Disclosure of Issued Claims . . . . . . . . . . . . . . . 24
8.3. Untrusted Input . . . . . . . . . . . . . . . . . . . . . 25
8.4. Replay and Caching . . . . . . . . . . . . . . . . . . . 25
8.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 25
8.6. Trust Between Recipient and Issuing Authorization
Server . . . . . . . . . . . . . . . . . . . . . . . . . 25
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
10.1. OAuth Extensions Error Registry . . . . . . . . . . . . 26
10.2. OAuth Parameters Registry . . . . . . . . . . . . . . . 27
10.2.1. required_claims . . . . . . . . . . . . . . . . . . 27
10.2.2. requested_claims . . . . . . . . . . . . . . . . . . 27
10.3. OAuth Protected Resource Metadata Registry . . . . . . . 27
10.4. OAuth Authorization Server Metadata Registry . . . . . . 28
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
11.1. Normative References . . . . . . . . . . . . . . . . . . 28
11.2. Informative References . . . . . . . . . . . . . . . . . 29
Appendix A. Worked End-to-End Example . . . . . . . . . . . . . 30
A.1. Actors . . . . . . . . . . . . . . . . . . . . . . . . . 30
A.2. Step 1: Client obtains an ID-JAG from the IdP AS . . . . 31
A.3. Step 2: Client presents the ID-JAG to the RAS . . . . . . 32
McGuinness Expires 28 November 2026 [Page 3]
Internet-Draft OAuth Claims Challenge May 2026
A.4. Step 3: RAS returns insufficient_claims . . . . . . . . . 32
A.5. Step 4: Client retries the Token Exchange with
requested_claims . . . . . . . . . . . . . . . . . . . . 32
A.6. Step 5: IdP AS issues an enriched ID-JAG . . . . . . . . 33
A.7. Step 6: Client re-presents the enriched ID-JAG to the
RAS . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.8. Step 7: RAS provisions Alice's account and issues an Access
Token . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.9. Step 8: Client calls the downstream API . . . . . . . . . 34
A.10. Avoiding the Round Trip with Protected Resource
Metadata . . . . . . . . . . . . . . . . . . . . . . . . 34
A.11. Authorization Server Metadata Discovery . . . . . . . . . 35
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 35
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 35
1. Introduction
OAuth 2.0 Clients present credentials at two natural recipients: a
Token Endpoint (an assertion or subject token used to obtain an
Access Token) and a Protected Resource (an Access Token used to
invoke an operation). Either recipient may require specific claims
about the subject (an identifier, a directory attribute, a policy
attribute) that the credential does not carry, even though the
credential is cryptographically valid and structurally acceptable.
There is currently no interoperable way for either recipient to
signal which claims are missing, nor for the Client to convey that
requirement to whoever issued the credential. Coordination happens
out of band per deployment pair, limiting composability across
Authorization Servers, Clients, and resources.
This specification separates the challenge (universal across
recipients and grants) from the Client's response (grant-specific).
It defines:
1. An OAuth 2.0 error code, insufficient_claims, that a recipient
returns when a presented credential is otherwise acceptable but
lacks claims required to fulfill the request. Used in Token
Endpoint error responses (Section 5.2 of [RFC6749]) and Bearer
authentication challenges at Protected Resources (Section 3 of
[RFC6750]).
2. A required_claims parameter (a JSON array of claim entries)
carried in Token Endpoint error response bodies, in JSON response
bodies accompanying Protected Resource Bearer challenges, and
(optionally) in OAuth 2.0 Protected Resource Metadata
([RFC9728]).
McGuinness Expires 28 November 2026 [Page 4]
Internet-Draft OAuth Claims Challenge May 2026
3. A requested_claims Token Endpoint request parameter that a Client
includes on a back-channel re-issuance request to obtain a
credential carrying the indicated claims. Defined for use with
the OAuth 2.0 Token Exchange ([RFC8693]) and Refresh Token
(Section 6 of [RFC6749]) grants only.
4. A required_claims Protected Resource Metadata parameter
([RFC9728]) by which a Protected Resource advertises the claims
it may require, letting Clients request them at Access Token
issuance and reduce runtime challenges.
5. A requested_claims_parameter_supported Authorization Server
Metadata parameter ([RFC8414]) by which an Authorization Server
advertises that it recognizes the requested_claims request
parameter at its Token Endpoint.
The challenge applies to credentials presented at the Token Endpoint
under any grant (see Section 3.3) and to Access Tokens presented at
Protected Resources (see Section 3.4). The Client's response is
grant-specific:
* For OAuth 2.0 Token Exchange and Refresh Token grants, the Client
sends a back-channel Token Endpoint request including the
requested_claims parameter (see Section 4.1).
* For grants that may require end-user interaction
(authorization_code, device authorization, CIBA, and similar), the
Client initiates a new authorization request and conveys its claim
requirements via an applicable front-channel claims request
mechanism, such as the OpenID Connect claims request parameter
(Section 5.5 of [OpenID.Core]; see Section 7.5). The
requested_claims parameter defined here is not used with these
grants.
The mechanism is opt-in and degrades gracefully. A recipient opts in
by returning insufficient_claims; a Client that does not recognize
the error treats the response as it would any other failure. An
Authorization Server that does not recognize the requested_claims
request parameter ignores it per Section 3.2 of [RFC6749]; the Client
may then receive a second insufficient_claims, which per Section 4.4
it treats as a terminal failure. The Authorization Server remains
the policy authority for claim release and does not release any claim
it would not otherwise release.
McGuinness Expires 28 November 2026 [Page 5]
Internet-Draft OAuth Claims Challenge May 2026
1.1. Why a New Error Code
OAuth defines distinct error codes for distinct failure modes:
invalid_grant ([RFC6749]) when a token is rejected,
insufficient_scope ([RFC6750]) when a valid token's scope is
insufficient, and insufficient_user_authentication ([RFC9470]) when a
valid token's authentication context is insufficient. The condition
addressed here is parallel to insufficient_scope but applies to claim
content rather than scope, and arises at both the Token Endpoint and
the Protected Resource. A distinct error code lets the Client
distinguish a recoverable claim-negotiation failure from a hard
rejection of the credential.
1.2. Motivating Use Cases
1.2.1. Just-in-Time Account Provisioning at a Resource Authorization
Server
A common deployment pattern, formalized by the Identity Assertion
Authorization Grant [I-D.ietf-oauth-identity-assertion-authz-grant],
conveys an identity assertion (the ID-JAG, a signed JWT) from an
Identity Provider (IdP) Authorization Server to a Resource
Authorization Server (RAS) governing a downstream resource. The
Client obtains the ID-JAG from the IdP AS via OAuth 2.0 Token
Exchange ([RFC8693]) and presents the ID-JAG to the RAS via the JWT
Bearer assertion grant ([RFC7523]).
If the subject has no account at the RAS, the RAS may perform just-
in-time (JIT) provisioning from the claims; if an account exists, the
RAS may update it. Either operation requires a sufficient set of
identity claims, and the required set varies per RAS. The mechanism
defined here lets the RAS enumerate the claims it needs in an
insufficient_claims response, and the Client forward that requirement
to the IdP AS on the follow-up Token Exchange.
1.2.2. Resource-Side Claim Requirements
A Protected Resource may require subject claims at request time that
were not provisioned into the Access Token at issuance: for example,
an authorization service whose policy depends on attributes the
Client did not request via scope, or a downstream resource that needs
claims an upstream Authorization Server did not include. The
mechanism defined here allows the Protected Resource to challenge the
Client to obtain a richer Access Token before retrying.
McGuinness Expires 28 November 2026 [Page 6]
Internet-Draft OAuth Claims Challenge May 2026
1.2.3. Multi-Resource Refresh Tokens
A Client holding a Refresh Token that issues Access Tokens for
multiple audiences (Section 6 of [RFC6749]) may need different claim
sets in the Access Tokens it obtains for each audience. The
requested_claims parameter on the Refresh Token request lets the
Client request the audience-appropriate claim set for the next Access
Token without initiating a new authorization flow.
1.2.4. Other Assertion-Based Grants
Any assertion-based grant defined by [RFC7521], including JWT Bearer
([RFC7523]) and SAML 2.0 Bearer ([RFC7522]), shares the "incoming
credential carrying claims" shape with Token Exchange. This
specification's error code applies uniformly to those grants; how the
Client obtains a richer assertion is governed by the assertion
provider's protocol and is out of scope for this document.
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.
This document uses the following terms from [RFC6749]: Client,
Authorization Server, Access Token, Token Endpoint, Protected
Resource, and error response.
This document uses the following terms from [RFC8693]: Token
Exchange, subject token, and requested token type.
This document uses the term "assertion" as defined in Section 1.2 of
[RFC7521]: a package of information that allows identity and security
information to be shared across security domains.
This document additionally uses the following terms:
Issuing Authorization Server: An OAuth 2.0 Authorization Server that
issued, or can re-issue, the credential the Client uses in an
OAuth 2.0 request. In the back-channel retry path (Section 4.1),
the Issuing Authorization Server is the one the Client targets
with requested_claims. In the Protected Resource case
(Section 3.4), it is the Authorization Server that issued the
Access Token presented at the resource.
Processing Authorization Server: The Authorization Server that
McGuinness Expires 28 November 2026 [Page 7]
Internet-Draft OAuth Claims Challenge May 2026
receives a Token Endpoint request from the Client and originates
the insufficient_claims error response.
Claim: An attribute of the subject or the assertion, as defined in
Section 4 of [RFC7519] for JWT-formatted tokens and generalized
here to any token format that carries named claims.
3. The Insufficient Claims Challenge
The insufficient_claims error code (Section 3.1) and the
required_claims response parameter (Section 3.2) define a common
challenge that applies in two contexts:
* OAuth 2.0 Token Endpoint requests under any grant that presents a
claim-bearing credential, including the Token Exchange grant
([RFC8693]), assertion-based grants ([RFC7521], [RFC7522],
[RFC7523]), and the Refresh Token grant (Section 6 of [RFC6749]);
see Section 3.3.
* Access Tokens presented at OAuth 2.0 Protected Resources; see
Section 3.4.
The HTTP envelope and the carrier of the structured response differ
per context, as described in Section 3.3 and Section 3.4. For Client
behavior on receiving the error, see Section 4.
3.1. Error Code
The error code is:
insufficient_claims: The credential presented by the Client is
acceptable but does not carry claims sufficient for the recipient
to fulfill the request.
3.2. Response Parameter
A recipient SHOULD include a required_claims parameter enumerating
the claims it requires.
In a JSON response body, the value of required_claims is a JSON array
of claim entries. Each entry is either a JSON string or a JSON
object.
A bare-string entry identifies a claim by name and indicates that the
named claim is required; any value is acceptable. For example:
"required_claims": ["email", "given_name", "family_name"]
McGuinness Expires 28 November 2026 [Page 8]
Internet-Draft OAuth Claims Challenge May 2026
An object entry adds an optional value constraint and has the
following members:
* name: REQUIRED. A JSON string identifying the claim name.
* value: OPTIONAL. A JSON value the claim MUST equal.
* values: OPTIONAL. A JSON array of values, one of which the claim
MUST equal.
An entry MUST NOT include both value and values. An entry that
includes neither is equivalent to the bare-string form. For example:
"required_claims": [
"email",
{"name": "email_verified", "value": true},
{"name": "tenant_id", "values": ["t-123", "t-456"]}
]
A claim name identifies a claim as it appears in the credential (for
example, the JSON member name in a JWT). Claim names use the scope-
token syntax of Section 3.3 of [RFC6749]: visible ASCII characters
excluding space (%x20), double-quote (%x22), and backslash (%x5C).
Claim names are case-sensitive. The order of entries in the array is
not significant.
This document does not define essential/voluntary semantics; all
entries are required. Profiles needing richer expressivity SHOULD
define their own parameter rather than overload required_claims (see
Section 7.5).
The same JSON array shape is used wherever this document conveys a
claim list in a JSON document, namely in Token Endpoint error
response bodies (Section 5.2 of [RFC6749]), in Protected Resource
error response bodies (Section 3.4), and in Protected Resource
Metadata documents (Section 5.1). This aligns with the
scopes_supported and claims_supported metadata conventions of
[RFC8414] and [OpenID.Core].
When the same list is carried as the requested_claims parameter on an
application/x-www-form-urlencoded Token Endpoint request (see
Section 4.1), the JSON array value is serialized to a JSON string and
percent-encoded per application/x-www-form-urlencoded rules. This
follows the precedent of authorization_details ([RFC9396]).
Characters that have special meaning in JSON or in form bodies,
including [, ], ", and ,, MUST be percent-encoded.
McGuinness Expires 28 November 2026 [Page 9]
Internet-Draft OAuth Claims Challenge May 2026
The required_claims parameter is OPTIONAL. A recipient that cannot
or does not wish to enumerate the missing claims MAY return the error
code without it. In that case the Client has no machine-readable
basis for retry and SHOULD treat the response as a terminal failure
unless out-of-band information is available.
A recipient MUST NOT include in required_claims any claim name whose
semantics are not defined by a registered claims registry (such as
the JSON Web Token Claims registry), a registered profile (such as
OpenID Connect Core [OpenID.Core]), or prior agreement with the
population of Issuing Authorization Servers it expects to
interoperate with.
Claim names in required_claims are interpreted in the context of the
(issuer, subject, audience, Client) tuple of the request, in the same
way as the scope parameter (Section 3.3 of [RFC6749]); see
Section 7.3. The Authorization Server's claim release policy, the
content and format of issued claims, and the meaning attached to a
given claim name are all scoped to that tuple.
Entries forwarded from a required_claims field into a
requested_claims parameter on a retry Token Endpoint request retain
their meaning only when both of the following hold:
* The audience, subject, and Client are preserved between the
original request and the retry.
* The Issuing and Processing Authorization Servers share an
understanding of the claim names and constraint values involved.
A recipient MUST NOT include the same claim name in more than one
entry of the array. A Client receiving duplicate entries for the
same claim name in required_claims MUST treat the value as malformed
and MUST NOT forward it as requested_claims. An Authorization Server
receiving duplicate entries for the same claim name in
requested_claims MUST treat the parameter as malformed.
3.3. Returned at the Token Endpoint
A Processing Authorization Server receiving a Token Endpoint request
MUST first validate the presented credential per its own acceptance
rules and the rules of the grant profile in use. If the credential
is rejected for cryptographic, audience, issuer, type, or freshness
reasons, the server MUST respond with the applicable error from
Section 5.2 of [RFC6749] (typically invalid_grant) rather than the
error defined here.
McGuinness Expires 28 November 2026 [Page 10]
Internet-Draft OAuth Claims Challenge May 2026
If the credential is acceptable but does not carry claims sufficient
to fulfill the request, the Processing Authorization Server MAY
respond with insufficient_claims. The error code is returned in the
error parameter of the Token Endpoint error response, formatted per
Section 5.2 of [RFC6749] with HTTP status code 400.
Example error response:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "insufficient_claims",
"error_description": "The presented credential is missing required claims.",
"required_claims": ["email", "given_name", "family_name"]
}
3.4. Returned at the Protected Resource
When a Protected Resource receives a request bearing an Access Token
that is otherwise valid but does not carry claims sufficient to
fulfill the request, the Protected Resource MAY return an
authentication challenge containing the insufficient_claims error
code.
The challenge follows Section 3 of [RFC6750]. The Protected Resource
MUST respond with HTTP status 403 Forbidden. The response MUST
include a WWW-Authenticate header field with the error parameter set
to insufficient_claims. The response MAY also include the
resource_metadata auth-param ([RFC9728]) to point the Client at its
Protected Resource Metadata document (see Section 5.1).
Structured details of the challenge, including the claims the
Protected Resource requires, are conveyed in the JSON response body
rather than as additional WWW-Authenticate auth-params. This follows
the body-carrying pattern of the OAuth 2.0 Token Endpoint error
response (Section 5.2 of [RFC6749]) and keeps the Bearer challenge
header simple.
When the Protected Resource emits a response body alongside the
challenge, the body's Content-Type MUST be application/json. The
body SHOULD include a required_claims member (Section 3.2)
enumerating the claims the Protected Resource requires. The response
SHOULD include Cache-Control: no-store.
McGuinness Expires 28 November 2026 [Page 11]
Internet-Draft OAuth Claims Challenge May 2026
The 403 status code is consistent with insufficient_scope
(Section 3.1 of [RFC6750]): the Access Token authenticates the Client
and subject but does not authorize this request because of
insufficient claim content. The 401 Unauthorized status code is not
used because the failure is not authentication of the Client or the
token.
Example challenge (line breaks in the WWW-Authenticate header are
shown for readability):
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_claims",
resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"
Content-Type: application/json
Cache-Control: no-store
{
"error": "insufficient_claims",
"error_description": "The Access Token is missing required claims.",
"required_claims": ["email", "department"]
}
A Protected Resource that cannot emit a JSON body MAY convey only the
WWW-Authenticate header. The Client then has no machine-readable
claim list to echo on retry, and SHOULD treat the response as a
terminal failure unless out-of-band information (such as Protected
Resource Metadata, Section 5.1) is available.
If the resource request was unauthenticated (no Access Token
presented), the Protected Resource MUST use the existing error
semantics of Section 3 of [RFC6750] (no error parameter or
error="invalid_token"), not insufficient_claims. The error defined
here is only applicable when the presented Access Token is otherwise
acceptable.
4. Client Remediation
A Client that receives an insufficient_claims response or challenge,
and that supports the mechanism defined in this document, obtains a
new credential carrying the claims listed in the required_claims
field. The Client then retries the original request with the new
credential. The retry mechanism depends on how the original
credential was obtained:
* When the original credential was obtained via OAuth 2.0 Token
Exchange ([RFC8693]) or from a Refresh Token (Section 6 of
[RFC6749]), the Client sends a back-channel Token Endpoint request
including the requested_claims parameter (Section 4.1).
McGuinness Expires 28 November 2026 [Page 12]
Internet-Draft OAuth Claims Challenge May 2026
* When the original credential was obtained via an interactive
authorization flow (the authorization_code grant, the device
authorization grant, the CIBA grant, or any other grant that may
involve end-user interaction), the Client initiates a new
authorization request and conveys its claim requirements using an
applicable front-channel claims request mechanism, such as the
OpenID Connect claims request parameter (Section 5.5 of
[OpenID.Core]); see Section 4.2.
* When the original credential was a pre-issued assertion presented
under a JWT Bearer ([RFC7523]) or SAML Bearer ([RFC7522]) grant,
the Client obtains a richer assertion from the assertion provider
using whatever mechanism that provider supports, then presents the
new assertion in a fresh assertion-grant request; see Section 7.2.
4.1. Back-Channel Token Endpoint Request Parameter
This document extends the Token Endpoint request (Section 3.2 of
[RFC6749]) with the following parameter:
requested_claims: OPTIONAL. A JSON array of claim entries that the
Client is requesting be included in the issued token. The array
shape, including the bare-string and constraint-object entry
forms, and the claim-name syntax match the required_claims
parameter defined in Section 3.2. When included in a Token
Endpoint request, the JSON array is serialized to a JSON string
and percent-encoded as the value of the requested_claims form
parameter. The requested_claims parameter MUST NOT appear more
than once in a single Token Endpoint request. A Client SHOULD NOT
include the same claim name in more than one entry of the array.
An Authorization Server receiving duplicate entries for the same
claim name MUST treat the parameter as malformed.
The requested_claims parameter is defined for use with the OAuth 2.0
Token Exchange grant ([RFC8693]) and the OAuth 2.0 Refresh Token
grant (Section 6 of [RFC6749]). These grants are back-channel re-
issuance flows in which the Client already holds a credential that
the Authorization Server can use to determine eligibility for the
requested claims, without a fresh end-user interaction. The
parameter MUST NOT be used with grants that may require end-user
interaction, including the authorization_code grant, the
urn:ietf:params:oauth:grant-type:device_code grant, and the
urn:openid:params:grant-type:ciba grant; see Section 4.2.
When sending a request that carries requested_claims, the Client MUST
identify the same audience or resource as the original request that
produced the insufficient_claims response or challenge. For Token
Exchange ([RFC8693]), the Client uses the audience and/or resource
McGuinness Expires 28 November 2026 [Page 13]
Internet-Draft OAuth Claims Challenge May 2026
request parameters defined by that specification. For Refresh Token
requests, the Client uses the resource parameter defined by Resource
Indicators ([RFC8707]).
The Authorization Server's release policy is scoped to the indicated
audience or resource. Changing the audience or resource may cause a
different policy to apply; see Section 7.3 and Section 7.4.
A Client MUST ensure that the requested_claims value it sends is a
well-formed JSON array of claim entries conforming to the syntax
defined in Section 3.2, and MUST NOT forward malformed input received
in a required_claims field from a recipient.
A Client SHOULD forward the value received in required_claims
verbatim as the value of requested_claims, percent-encoded for the
application/x-www-form-urlencoded body. A Client MAY include
additional entries (bare claim names or constraint objects) in the
array based on local knowledge of the target resource.
4.1.1. Use with Token Exchange
Under the OAuth 2.0 Token Exchange grant ([RFC8693]), the Client
sends a new request to the Issuing Authorization Server. The Client
selects the subject_token and subject_token_type based on its
established credential relationship with the Issuing Authorization
Server. This is typically the same subject_token the Client
originally exchanged at that Authorization Server.
The following example uses the ID-JAG token type from the Identity
Assertion Authorization Grant
([I-D.ietf-oauth-identity-assertion-authz-grant]); any
requested_token_type registered with IANA may be used. The audience
value matches the Processing Authorization Server that issued the
original insufficient_claims response.
POST /oauth2/token HTTP/1.1
Host: issuer.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid-jag
&subject_token=eyJhbGciOi...
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
&audience=https%3A%2F%2Fapi.example.com%2F
&requested_claims=%5B%22email%22%2C%22given_name%22%2C%22family_name%22%5D
The requested_claims value above is the URL-encoded form of the JSON
array ["email","given_name","family_name"].
McGuinness Expires 28 November 2026 [Page 14]
Internet-Draft OAuth Claims Challenge May 2026
4.1.2. Use with Refresh Token
A Client holding a Refresh Token (Section 6 of [RFC6749]) MAY include
requested_claims on a Refresh Token request to obtain a re-issued
Access Token (and, where applicable, ID Token) carrying the indicated
claims. This is particularly useful for multi-resource Refresh
Tokens, where a single Refresh Token issues Access Tokens for several
audiences and the claim set required differs per audience.
Example request:
POST /oauth2/token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=8xLOxBtZp8...
&resource=https%3A%2F%2Fapi.example.com%2F
&requested_claims=%5B%22email%22%2C%22department%22%5D
The requested_claims value above is the URL-encoded form of the JSON
array ["email","department"].
The Authorization Server applies its normal Refresh Token policy,
including any policy that would have applied had the Client requested
those claims at the original authorization.
An Authorization Server that would require fresh end-user consent or
re-authentication to release a requested claim has two options. It
MAY decline that claim and issue a token without it. Alternatively,
it MAY respond with an OpenID Connect error such as consent_required
or interaction_required (Section 3.1.2.6 of [OpenID.Core]), prompting
the Client to initiate a new authorization request (see Section 4.2).
4.2. Interactive Grants
For grants that may require end-user interaction (the
authorization_code grant, the device authorization grant, the CIBA
grant, and similar), a Client responding to insufficient_claims
SHOULD initiate a new authorization request and convey its claim
requirements using an applicable front-channel claims request
mechanism, such as the OpenID Connect claims request parameter
(Section 5.5 of [OpenID.Core]); see Section 7.5.
This separation lets the Authorization Server apply consent, user
authentication, or interaction policies appropriate to the new claim
release, rather than requiring those policies to be expressed as a
back-channel side effect.
McGuinness Expires 28 November 2026 [Page 15]
Internet-Draft OAuth Claims Challenge May 2026
4.3. Authorization Server Behavior
An Authorization Server that supports the requested_claims request
parameter on Token Exchange or Refresh Token requests SHOULD include
each requested claim in the issued token, subject to its own policy.
In particular, the Authorization Server:
* MUST NOT release a claim it would not otherwise release under its
configured policy for the subject, the audience, and the
requesting Client. Receipt of requested_claims is not
authorization to bypass consent, privacy, or release controls.
* MUST NOT treat requested_claims as a complete enumeration of the
claims that should be issued. The Authorization Server MAY
include additional claims it would normally include.
* MAY decline to include any specific requested claim. Declining to
include a claim is not, by itself, a reason to fail the request.
* SHOULD NOT fail the request because of an unrecognized claim name
in requested_claims.
* When an entry includes a value or values constraint, the
Authorization Server MUST NOT include the claim in the issued
token with a value that does not satisfy the constraint. The
Authorization Server MAY decline to include the claim entirely if
it cannot satisfy the constraint.
* An Authorization Server that does not support constraint entries
MUST NOT ignore the value or values members and treat the entry as
the bare-string form. It MUST either decline the constrained
claim or reject the request with invalid_request.
Issuance of a token in response to a requested_claims request is not
an assertion by the Authorization Server that all requested claims
were honored. A Client that needs to verify a specific claim is
present in the re-issued token before retrying inspects the issued
token using the mechanisms applicable to its format.
4.4. No Loop Guarantee
This specification does not oblige an Issuing Authorization Server to
satisfy a requested_claims request, nor a recipient (Processing
Authorization Server or Protected Resource) to accept a re-issued
credential whose claims still fall short. For the purposes of this
section, the "logical exchange" is the workflow that produced the
original insufficient_claims response or challenge, whether returned
from a Token Endpoint or a Protected Resource. A Client SHOULD issue
McGuinness Expires 28 November 2026 [Page 16]
Internet-Draft OAuth Claims Challenge May 2026
at most one retry per logical exchange, and MUST treat any subsequent
insufficient_claims for the same logical exchange as a terminal
failure, even if it enumerates a different required_claims value.
5. Discovery
This section defines two static-metadata mechanisms that complement
the runtime challenge. Protected Resources advertise the claims they
may require so that Clients can request them at issuance time.
Authorization Servers advertise support for the requested_claims
request parameter so that Clients can use it proactively. Both
mechanisms are optional and degrade gracefully when absent.
5.1. Protected Resource Metadata
A Protected Resource MAY advertise the set of claims it may require
in its OAuth 2.0 Protected Resource Metadata document ([RFC9728])
using the following metadata parameter:
required_claims: OPTIONAL. A JSON array of claim entries with the
shape defined in Section 3.2, enumerating claims the Protected
Resource may require in Access Tokens. Entries MAY be bare claim
names or constraint objects, though deployments commonly advertise
bare names only.
Example metadata fragment:
{
"resource": "https://api.example.com/",
"authorization_servers": ["https://as.example.com/"],
"scopes_supported": ["read", "write"],
"required_claims": ["email", "given_name", "family_name"]
}
The advertised set is advisory and represents a maximal or typical
set of claims the resource may require across its operations. A
Client that obtains an Access Token carrying these claims will, in
the common case, avoid an insufficient_claims challenge.
The Protected Resource MAY still return insufficient_claims for
operations whose requirements depend on request path, parameters,
subject state, or policy. The Protected Resource is not obliged to
require every advertised claim for every operation.
Clients SHOULD treat the advertised list as a hint for Access Token
acquisition. Clients SHOULD NOT depend on it as a complete or stable
contract.
McGuinness Expires 28 November 2026 [Page 17]
Internet-Draft OAuth Claims Challenge May 2026
As with required_claims in error responses and challenges, and
requested_claims in Token Endpoint requests, claim names in the
metadata are interpreted in the context of the (issuer, subject,
audience, Client) tuple of any Access Token that will be presented at
the resource; see Section 7.3. For Authorization Server-side
advertising of requested_claims support, see Section 5.2.
5.2. Authorization Server Metadata
An Authorization Server that supports the requested_claims request
parameter defined in Section 4.1 SHOULD advertise that support in its
OAuth 2.0 Authorization Server Metadata ([RFC8414]) using the
following metadata parameter:
requested_claims_parameter_supported: OPTIONAL. Boolean value
indicating whether the Authorization Server supports the
requested_claims Token Endpoint request parameter defined in this
document. If omitted, the default value is false.
A Client MAY consult this metadata to determine whether to send
requested_claims on a Token Exchange or Refresh Token request. This
includes proactively including the parameter on a first attempt where
the Client expects specific claims will be needed.
A Client MUST NOT rely on the absence or false value of this metadata
to predict an Authorization Server's behavior on requested_claims.
An Authorization Server that does not advertise support MAY still
honor the parameter, consistent with Section 3.2 of [RFC6749].
This metadata parameter advertises support for the Token Endpoint
request parameter only. It does not advertise support for the
insufficient_claims error code in error responses. Recipients return
that error code per their own policy regardless of metadata.
For Protected Resource-side advertising of required claims, see
Section 5.1.
6. End-to-End Examples
The two diagrams below illustrate the principal flows. For a full
worked example with concrete actors, decoded JWT payloads, and
complete HTTP messages, see Appendix A.
McGuinness Expires 28 November 2026 [Page 18]
Internet-Draft OAuth Claims Challenge May 2026
6.1. Token Exchange Retry
The following non-normative example illustrates the Token Endpoint
flow using the Identity Assertion Authorization Grant profile
([I-D.ietf-oauth-identity-assertion-authz-grant]), where the
Processing Authorization Server is the Resource Authorization Server
(RAS) and the Issuing Authorization Server is the Identity Provider
(IdP) Authorization Server.
Client IdP AS RAS
| | |
| TokenExchange | |
| (subject=ID Token)| |
|------------------->| |
| | |
| ID-JAG (minimal) | |
|<-------------------| |
| | |
| JWT Bearer (assertion=ID-JAG) |
|-------------------------------------->|
| | |
| 400 insufficient_claims |
| required_claims: ["email", |
| "given_name", |
| "family_name"] |
|<--------------------------------------|
| | |
| TokenExchange | |
| +requested_claims | |
|------------------->| |
| | |
| ID-JAG with | |
| requested claims | |
|<-------------------| |
| | |
| JWT Bearer (assertion=ID-JAG) |
|-------------------------------------->|
| | |
| 200 OK { access_token } |
|<--------------------------------------|
6.2. Protected Resource Challenge
The following non-normative example illustrates a Protected Resource
returning insufficient_claims and the Client obtaining a richer
Access Token via Token Exchange before retrying.
McGuinness Expires 28 November 2026 [Page 19]
Internet-Draft OAuth Claims Challenge May 2026
Client AS Resource
| | |
| GET /api/foo |
| Authorization: Bearer AT1 |
|---------------------------------------->|
| | |
| 403 Forbidden |
| WWW-Authenticate: Bearer |
| error="insufficient_claims" |
| Body: {"required_claims": |
| ["email", "department"]} |
|<----------------------------------------|
| | |
| TokenExchange | |
| audience=api.example.com |
| +requested_claims | |
|------------------->| |
| | |
| AT2 (carries | |
| email, department)| |
|<-------------------| |
| | |
| GET /api/foo |
| Authorization: Bearer AT2 |
|---------------------------------------->|
| | |
| 200 OK { result } |
|<----------------------------------------|
7. Relationship to Other Specifications
7.1. Identity Assertion Authorization Grant
[I-D.ietf-oauth-identity-assertion-authz-grant] defines the
urn:ietf:params:oauth:token-type:id-jag token type and the role of
the Resource Authorization Server in a cross-domain identity
assertion flow. The Client mints an ID-JAG via OAuth 2.0 Token
Exchange ([RFC8693]) at the IdP AS and presents the ID-JAG to the RAS
via the JWT Bearer assertion grant ([RFC7523]). With the mechanism
defined here, specific claim requirements at the RAS become a
deployment-time decision negotiated at runtime via the
required_claims/requested_claims pair, with the Issuing Authorization
Server retaining policy authority over release.
McGuinness Expires 28 November 2026 [Page 20]
Internet-Draft OAuth Claims Challenge May 2026
7.2. Assertion-Based Grants
[RFC7521] defines the framework for assertion-based OAuth 2.0 grants.
[RFC7522] and [RFC7523] define specific profiles for SAML 2.0 and JWT
assertions respectively. The insufficient_claims error code defined
here applies uniformly to Token Endpoint requests using any of these
grants.
The requested_claims request parameter (Section 4.1) is defined for
Token Exchange and Refresh Token grants and is not used with JWT
Bearer or SAML Bearer requests directly. The assertion presented in
those grants is obtained out of band, and obtaining a richer
assertion is governed by the assertion provider's protocol.
Where the assertion provider is itself an OAuth 2.0 Authorization
Server, a Client receiving insufficient_claims would typically obtain
a richer assertion via Token Exchange or via an interactive flow
using the OpenID Connect claims request parameter. The Client then
presents the new assertion in a fresh JWT Bearer or SAML Bearer
request.
7.3. OAuth 2.0 scope Parameter
The scope parameter (Section 3.3 of [RFC6749]) is a coarse,
Authorization Server-specific authorization request signal. In some
deployment profiles, including OpenID Connect, specific scope values
(for example, profile, email) imply the issuance of specific claims.
This document does not redefine that mapping.
The mechanism defined here is finer-grained than scope: a recipient
names individual claims directly in required_claims, independent of
any scope-to-claim mapping the issuing Authorization Server may
apply. The Client can forward a precise requirement as
requested_claims without knowing that mapping.
Both required_claims and requested_claims share with scope the
property that values are interpreted in the context of the (issuer,
subject, audience, Client) tuple of the request. A claim name has no
globally registered semantics that override an Authorization Server's
local release policy. The same name may carry different content,
format, or release rules at different Authorization Servers, for
different subjects, audiences, or Clients.
A Client forwarding claim names between a recipient (in
required_claims) and an Issuing Authorization Server (in
requested_claims) is relying on those two parties having a shared
understanding of the listed names, typically through registered
claims or profile alignment.
McGuinness Expires 28 November 2026 [Page 21]
Internet-Draft OAuth Claims Challenge May 2026
requested_claims complements scope rather than replacing it. A
Client retrying at the Token Endpoint MAY include both parameters in
the same request. The Authorization Server applies its scope
semantics as it otherwise would, and additionally takes
requested_claims into account.
7.4. OAuth 2.0 Resource Indicators
[RFC8707] allows a Client to specify the resource (the resource
parameter) at which the requested token will be used. The
Authorization Server may use that signal, together with the audience
parameter, to determine the audience of the issued token and to apply
audience-specific claim release policy. Two consequences follow:
1. Claims releasable to one audience may not be releasable to
another. A retry under Section 4.1 that changes the audience or
resource value from the original request may obtain a token under
different policy. The Authorization Server may include or omit
different claims, and the recipient that returned
insufficient_claims may not accept the re-issued token. For this
reason Section 4.1 requires the Client to preserve the original
audience and, where applicable, resource on retry.
2. A Processing Authorization Server or Protected Resource that
returns insufficient_claims does so for a specific audience. A
required_claims value that is meaningful for one audience may be
meaningless, or trigger different release policy, for another.
7.5. OpenID Connect claims Request Parameter
OpenID Connect Core 1.0 ([OpenID.Core], Section 5.5) defines a claims
request parameter at the OIDC Authorization Endpoint and Token
Endpoint, carrying a JSON object that requests individual claims for
the ID Token and UserInfo responses with optional essential/voluntary
semantics and value constraints.
This document defers to the OIDC claims parameter for any response to
insufficient_claims that requires a new authorization request,
including the authorization_code grant, the device authorization
grant, the CIBA grant, and similar interactive flows. In these
cases:
McGuinness Expires 28 November 2026 [Page 22]
Internet-Draft OAuth Claims Challenge May 2026
* The Client SHOULD initiate a new authorization request to the
Authorization Server and include a claims parameter reflecting the
entries enumerated in the required_claims field of the
insufficient_claims response or challenge. Mapping constraint
entries to OIDC claims syntax is deployment-specific and only
possible where the Authorization Server supports the corresponding
OIDC claim request semantics.
* The Authorization Server applies its normal interactive-flow
policy: it MAY prompt the end user for consent, perform additional
authentication, or otherwise involve the user before releasing
newly requested claims. This is the natural place to handle such
policy, which the back-channel requested_claims parameter
(Section 4.1) cannot accommodate.
* On completion of the new authorization request, the Client obtains
an Access Token (and, where applicable, ID Token) carrying the
requested claims, and retries the original request.
The requested_claims parameter defined in this document is not a
substitute for the OIDC claims parameter for interactive grants; the
two parameters target different stages of the OAuth 2.0 flow and
different deployment patterns:
* OIDC claims is presented at an Authorization or backchannel-
authentication request, where end-user consent and authentication
can be evaluated. It supports essential/voluntary claims and
value constraints.
* requested_claims is presented at the Token Endpoint as part of a
back-channel re-issuance request (Token Exchange or Refresh
Token), where no end-user interaction occurs. It is a hint to the
Authorization Server about which claims should be included in the
issued token, with optional value or values constraints.
An Authorization Server MAY support both claims (on its OIDC
endpoints) and requested_claims (on Token Exchange and Refresh Token
requests at its Token Endpoint). This document does not define an
interaction between them.
7.6. OAuth 2.0 Bearer Token Usage and Step-Up Authentication
[RFC6750] defines the Bearer authentication scheme used at the
Protected Resource and the insufficient_scope error returned when the
Access Token's scope is insufficient. [RFC9470] defines
insufficient_user_authentication returned when the authentication
context behind the Access Token is insufficient. The mechanism in
Section 3.4 of this document follows the same challenge pattern but
McGuinness Expires 28 November 2026 [Page 23]
Internet-Draft OAuth Claims Challenge May 2026
addresses claim content rather than scope or authentication context.
7.7. OAuth 2.0 Rich Authorization Requests
[RFC9396] carries structured request objects (authorization_details)
as JSON. The claim-entry syntax in this document is intentionally
much narrower: it can name claims and, when needed, request equality
against one value or one of a set of values. Profiles needing richer
authorization semantics, schema references, or non-claim constraints
SHOULD define their own parameter rather than overload
required_claims.
8. Security Considerations
8.1. Disclosure of Claim Requirements
The required_claims parameter, whether in an error response body or
in Protected Resource Metadata, discloses to the Client the set of
claims the recipient intends to consume. This is generally low-
sensitivity information, comparable to the OAuth scope parameter, but
operators SHOULD confirm that disclosing the list to any Client
capable of reaching the Token Endpoint or Protected Resource is
acceptable.
When required_claims entries include value or values constraints,
those constraints disclose more deployment-specific policy than bare
claim names: they reveal specific tenant identifiers, role names, or
other policy attributes that the recipient evaluates. Operators
SHOULD consider whether disclosing these values to any Client capable
of reaching the endpoint is acceptable. Where the constraint values
themselves are sensitive, deployments SHOULD use bare claim names and
validate values out of band.
8.2. Disclosure of Issued Claims
When an Authorization Server includes additional claims in a re-
issued token in response to requested_claims, those claims may be
readable by the Client (for example, a JWT-formatted token can be
parsed by anyone holding the token). Authorization Servers SHOULD
apply the same release policy as for any other token issued to the
same subject, audience, and Client.
In deployments where the intended consumer of the issued token is the
recipient only and the Client is treated as a transport, the security
guidance from [I-D.ietf-oauth-identity-assertion-authz-grant] on
audience scoping and (where supported) encryption of the token
applies.
McGuinness Expires 28 November 2026 [Page 24]
Internet-Draft OAuth Claims Challenge May 2026
The Authorization Server is the policy authority for release.
Receipt of a requested_claims parameter from a Client MUST NOT be
treated as user consent, subject release authorization, or any other
form of override of the Authorization Server's configured policy. An
Authorization Server that finds that satisfying requested_claims
would violate policy MUST decline the affected claims and MAY decline
the request.
8.3. Untrusted Input
A recipient constructing a required_claims field, and an
Authorization Server consuming a requested_claims parameter, MUST
treat the value as untrusted input until validated. Implementations
MUST validate that each entry in the array conforms to the syntax
constraints stated in this document, including claim-name syntax,
mutual exclusion of value and values, and the absence of duplicate
claim names. Implementations MUST NOT pass the value into log
formatters, database queries, or claim release rules without proper
escaping or parameterization.
8.4. Replay and Caching
The insufficient_claims error response (at the Token Endpoint or
Protected Resource) and the required_claims parameter it carries have
no authentication state, no nonce, and no expiration, and MUST NOT be
used to make any access decision. They serve only to guide the
Client's next request. Responses carrying required_claims SHOULD be
returned with Cache-Control: no-store.
8.5. Denial of Service
A recipient returning insufficient_claims invites the Client to
perform an additional Token Endpoint request against an Authorization
Server. Implementations on all sides SHOULD apply standard rate
limiting to protect their endpoints. As noted in Section 4.4 and
Section 3.4, Clients SHOULD NOT retry indefinitely.
8.6. Trust Between Recipient and Issuing Authorization Server
This specification does not establish trust between a recipient
(Processing Authorization Server or Protected Resource) and the
Issuing Authorization Server. The Client mediates between them and
can add, remove, or modify the claim list it received in
required_claims before forwarding it as requested_claims. For this
reason requested_claims is advisory.
McGuinness Expires 28 November 2026 [Page 25]
Internet-Draft OAuth Claims Challenge May 2026
The Issuing Authorization Server SHOULD evaluate the request against
the Client's identity, the requested audience, and its local release
policy. The Issuing Authorization Server MUST NOT infer a recipient
requirement from requested_claims alone. It MUST NOT treat the
parameter's presence as authorization to release any claim.
9. Privacy Considerations
The mechanism in this document is designed to reduce, not increase,
claim disclosure relative to a static policy. Without
required_claims, an Issuing Authorization Server that wishes to
interoperate with multiple recipients must either include claims
speculatively (releasing data that may not be needed) or omit them
and break the downstream operation. With required_claims, an
Authorization Server can release claims only when a specific exchange
requires them, subject to its own policy.
Operators of recipients (Processing Authorization Servers and
Protected Resources) SHOULD request the minimum set of claims
necessary, and SHOULD NOT enumerate claims they do not consume.
Operators of Issuing Authorization Servers SHOULD apply consent,
contractual, or regulatory release controls before honoring any
specific entry in requested_claims.
10. IANA Considerations
10.1. OAuth Extensions Error Registry
IANA is requested to add the following entry to the "OAuth Extensions
Error" registry established by Section 11.4 of [RFC6749].
Name: insufficient_claims
Usage Location: Token Endpoint Error Response, Resource Access Error
Response
Protocol Extension: This document
Change Controller: IETF
Specification Document(s): This document
Description: Indicates that the credential presented by the Client
is acceptable but does not carry claims sufficient for the
recipient to fulfill the request. Returned in OAuth 2.0 Token
Endpoint error responses and in OAuth 2.0 Bearer authentication
challenges at Protected Resources.
McGuinness Expires 28 November 2026 [Page 26]
Internet-Draft OAuth Claims Challenge May 2026
10.2. OAuth Parameters Registry
IANA is requested to add the following entries to the "OAuth
Parameters" registry established by Section 11.2 of [RFC6749].
10.2.1. required_claims
Name: required_claims
Parameter Usage Location: token response
Change Controller: IETF
Specification Document(s): This document
Notes: The required_claims parameter appears in the JSON error
response body of OAuth 2.0 Token Endpoint error responses
(Section 5.2 of [RFC6749]) and in the JSON error response body of
Protected Resources returning insufficient_claims (Section 3.4).
10.2.2. requested_claims
Name: requested_claims
Parameter Usage Location: token request
Change Controller: IETF
Specification Document(s): This document
10.3. OAuth Protected Resource Metadata Registry
IANA is requested to add the following entry to the "OAuth Protected
Resource Metadata" registry established by Section 7.1 of [RFC9728].
Metadata Name: required_claims
Metadata Description: A JSON array of claim entries (bare claim
names or constraint objects) enumerating claims the Protected
Resource may require in Access Tokens, advisory and not
necessarily a complete or stable contract; see Section 5.1.
Change Controller: IETF
Specification Document(s): This document
McGuinness Expires 28 November 2026 [Page 27]
Internet-Draft OAuth Claims Challenge May 2026
10.4. OAuth Authorization Server Metadata Registry
IANA is requested to add the following entry to the "OAuth
Authorization Server Metadata" registry established by Section 7.1 of
[RFC8414].
Metadata Name: requested_claims_parameter_supported
Metadata Description: Boolean value indicating whether the
Authorization Server supports the requested_claims Token Endpoint
request parameter defined in this document; see Section 5.2.
Change Controller: IETF
Specification Document(s): This document
11. References
11.1. Normative References
[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>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/rfc/rfc6749>.
[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>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/rfc/rfc7519>.
[RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland,
"Assertion Framework for OAuth 2.0 Client Authentication
and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521,
May 2015, <https://www.rfc-editor.org/rfc/rfc7521>.
[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>.
McGuinness Expires 28 November 2026 [Page 28]
Internet-Draft OAuth Claims Challenge May 2026
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[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>.
[RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J.,
and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693,
DOI 10.17487/RFC8693, January 2020,
<https://www.rfc-editor.org/rfc/rfc8693>.
[RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource
Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707,
February 2020, <https://www.rfc-editor.org/rfc/rfc8707>.
[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>.
11.2. Informative References
[I-D.ietf-oauth-identity-assertion-authz-grant]
Parecki, A., McGuinness, K., and B. Campbell, "Identity
Assertion JWT Authorization Grant", Work in Progress,
Internet-Draft, draft-ietf-oauth-identity-assertion-authz-
grant-04, 21 May 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
identity-assertion-authz-grant-04>.
[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0 incorporating
errata set 2", December 2023,
<https://openid.net/specs/openid-connect-core-1_0.html>.
[RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security
Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0
Client Authentication and Authorization Grants", RFC 7522,
DOI 10.17487/RFC7522, May 2015,
<https://www.rfc-editor.org/rfc/rfc7522>.
McGuinness Expires 28 November 2026 [Page 29]
Internet-Draft OAuth Claims Challenge May 2026
[RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token
(JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May
2015, <https://www.rfc-editor.org/rfc/rfc7523>.
[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>.
Appendix A. Worked End-to-End Example
This appendix is non-normative. It walks through a complete just-in-
time (JIT) provisioning flow using the Identity Assertion
Authorization Grant ([I-D.ietf-oauth-identity-assertion-authz-grant])
profile, the Token Exchange retry path of Section 4.1, and the
Protected Resource Metadata advertisement of Section 5.1. HTTP
messages are shown in full; JWT contents are shown as decoded
payloads for readability.
A.1. Actors
* *End user:* Alice, an employee of Example Corp.
* *Client:* Acme Tools (client_id=acme-tools), an enterprise SaaS
application that uses Alice's IdP session to access a downstream
API on her behalf.
* *Identity Provider Authorization Server (IdP AS):*
https://idp.example.com/. This is the Issuing Authorization Server
in the terminology of Section 4.1.
* *Resource Authorization Server (RAS):* https://ras.example.com/.
This is the Processing Authorization Server.
* *Downstream resource:* https://api.example.com/.
The RAS performs JIT account provisioning when the subject is unknown
to it. Its policy requires email, given_name, and family_name to
provision a new account.
McGuinness Expires 28 November 2026 [Page 30]
Internet-Draft OAuth Claims Challenge May 2026
A.2. Step 1: Client obtains an ID-JAG from the IdP AS
The Client has authenticated Alice via OpenID Connect at the IdP and
holds her ID Token. The Client sends a Token Exchange request to the
IdP AS for an ID-JAG bound to the RAS's audience. In this first
attempt, the Client does not yet know which claims the RAS requires
and sends no requested_claims.
POST /oauth2/token HTTP/1.1
Host: idp.example.com
Authorization: Basic YWNtZS10b29sczpzM2NyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid-jag
&subject_token=eyJhbGciOiJSUzI1NiIs...
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
&audience=https%3A%2F%2Fras.example.com%2F
The IdP AS validates the ID Token, applies its default release policy
for this Client and audience, and issues an ID-JAG with minimal
content. Decoded payload:
{
"iss": "https://idp.example.com/",
"sub": "alice-uuid-12345",
"aud": "https://ras.example.com/",
"client_id": "acme-tools",
"exp": 1748190000,
"iat": 1748189700
}
The Token Exchange response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"issued_token_type": "urn:ietf:params:oauth:token-type:id-jag",
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "N_A",
"expires_in": 300
}
The access_token field carries the ID-JAG by convention of [RFC8693].
McGuinness Expires 28 November 2026 [Page 31]
Internet-Draft OAuth Claims Challenge May 2026
A.3. Step 2: Client presents the ID-JAG to the RAS
The Client presents the ID-JAG to the RAS using the JWT Bearer
assertion grant ([RFC7523]). The ID-JAG carries the audience
identifier of the RAS in its aud claim, so no separate audience form
parameter is needed.
POST /oauth2/token HTTP/1.1
Host: ras.example.com
Authorization: Basic YWNtZS10b29sczpzM2NyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJSUzI1NiIs...
A.4. Step 3: RAS returns insufficient_claims
The RAS validates the ID-JAG (signature, issuer, audience, freshness)
and accepts it. It then attempts to resolve sub=alice-uuid-12345 to
a local account; no match. To JIT-provision Alice, it needs email,
given_name, and family_name. The ID-JAG carries none of these, so
the RAS challenges the Client:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "insufficient_claims",
"error_description":
"Cannot provision user; missing required claims.",
"required_claims": ["email", "given_name", "family_name"]
}
A.5. Step 4: Client retries the Token Exchange with requested_claims
The Client extracts the required_claims JSON array from the response
body, percent-encodes the array as the requested_claims form value,
and sends a new Token Exchange request to the IdP AS with the same
audience and the original ID Token as the subject token:
McGuinness Expires 28 November 2026 [Page 32]
Internet-Draft OAuth Claims Challenge May 2026
POST /oauth2/token HTTP/1.1
Host: idp.example.com
Authorization: Basic YWNtZS10b29sczpzM2NyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid-jag
&subject_token=eyJhbGciOiJSUzI1NiIs...
&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
&audience=https%3A%2F%2Fras.example.com%2F
&requested_claims=%5B%22email%22%2C%22given_name%22%2C%22family_name%22%5D
The requested_claims value above is the URL-encoded form of the JSON
array ["email","given_name","family_name"] returned in the RAS's
required_claims field, forwarded verbatim.
A.6. Step 5: IdP AS issues an enriched ID-JAG
The IdP AS checks that Alice has consented to share these claims with
Acme Tools (or that the deployment's policy otherwise permits
release). It then issues an ID-JAG that includes the requested
claims. Decoded payload:
{
"iss": "https://idp.example.com/",
"sub": "alice-uuid-12345",
"aud": "https://ras.example.com/",
"client_id": "acme-tools",
"exp": 1748190600,
"iat": 1748190300,
"email": "alice@example.com",
"given_name": "Alice",
"family_name": "Carter"
}
A.7. Step 6: Client re-presents the enriched ID-JAG to the RAS
The Client repeats the JWT Bearer request from Step 2, this time
using the enriched ID-JAG returned in Step 5.
POST /oauth2/token HTTP/1.1
Host: ras.example.com
Authorization: Basic YWNtZS10b29sczpzM2NyZXQ=
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJSUzI1NiIs...
McGuinness Expires 28 November 2026 [Page 33]
Internet-Draft OAuth Claims Challenge May 2026
A.8. Step 7: RAS provisions Alice's account and issues an Access Token
The RAS:
1. Validates the enriched ID-JAG.
2. Confirms no existing account for sub=alice-uuid-12345.
3. Creates a local account using email, given_name, and family_name.
4. Issues an Access Token for the downstream API.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
A.9. Step 8: Client calls the downstream API
GET /v1/projects HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
The downstream API validates the Access Token, finds Alice's now-
provisioned account, and returns her project list.
A.10. Avoiding the Round Trip with Protected Resource Metadata
If the RAS publishes its claim requirements via Protected Resource
Metadata (Section 5.1), the Client can include requested_claims on
its very first Token Exchange request and skip Steps 3 and 4
entirely.
Example PRM document at https://ras.example.com/.well-known/oauth-
protected-resource:
McGuinness Expires 28 November 2026 [Page 34]
Internet-Draft OAuth Claims Challenge May 2026
HTTP/1.1 200 OK
Content-Type: application/json
{
"resource": "https://ras.example.com/",
"authorization_servers": ["https://idp.example.com/"],
"required_claims": ["email", "given_name", "family_name"]
}
A Client that fetches this metadata at startup includes
requested_claims=%5B%22email%22%2C%22given_name%22%2C%22family_name%22%5D
(the URL-encoded form of ["email","given_name","family_name"]) in
Step 1, and the IdP AS issues the enriched ID-JAG on the first
attempt. The remainder of the flow proceeds directly to Step 7.
A.11. Authorization Server Metadata Discovery
A Client that consults the IdP AS's metadata can also confirm support
for the requested_claims parameter before sending it, avoiding wasted
requests against an Authorization Server that does not recognize the
parameter. Example IdP AS metadata fragment at
https://idp.example.com/.well-known/oauth-authorization-server:
{
"issuer": "https://idp.example.com/",
"token_endpoint": "https://idp.example.com/oauth2/token",
"grant_types_supported": [
"authorization_code",
"refresh_token",
"urn:ietf:params:oauth:grant-type:token-exchange"
],
"requested_claims_parameter_supported": true
}
Acknowledgments
The author thanks the OAuth working group participants who raised the
underlying interoperability gap in the Identity Assertion
Authorization Grant draft.
Author's Address
Karl McGuinness
Independent
Email: public@karlmcguinness.com
McGuinness Expires 28 November 2026 [Page 35]