| Internet-Draft | TODO - Abbreviation | April 2025 |
| Lombardo & Babeanu | Expires 13 October 2025 | [Page] |
This specification defines new claims for JWT profiled access tokens [RFC9068] so that resource providers can benefit from more granular information about the client to make better informed access decisions. The proposed new claims include: the client authentication methods, the client OAuth grant flow used as well as the OAuth grant flow extensions used as part of the issuance of the associated tokens.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://identitymonk.github.io/draft-lombardo-oauth-client-extension-claims/draft-lombardo-oauth-client-extension-claims.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-lombardo-oauth-client-extension-claims/.¶
Discussion of this document takes place on the Web Authorization Protocol 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/identitymonk/draft-lombardo-oauth-client-extension-claims.¶
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 13 October 2025.¶
Copyright (c) 2025 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.¶
Resource providers need information about the subject, the action, the resource, and the context involved in the request in order to be able to determine properly if a resource can be disclosed. This decision may also involve the help of a Policy Decision Point (PDP).¶
When accessed with a JWT profiled OAuth2 Access Token [RFC9068] presented as a bearer token [RFC6750], a Resource Server (RS) receives information about the subject as claims, such as:
- The subject, sub,
- Any user profile claim set by the Authorization Server if applicable,
- Authenticaton Information claims like the user class of authentication (acrclaim) or user methord of authentication (claim amr [RFC8176])
- Any Authorization Information if applicable¶
On the other hand, the RS has very little information about the client, often only a client_id [RFC8693] claim. In particular, the RS lacks any insight about the type of authorization grant flow that the client itself went through, the level of assurance that the client itself may have reached during its own authentication, and in general, lacks any information that would enable it to determine if the client itself can be trusted at all.¶
This document defines 4 new claims for the JWT profile of OAuth access tokens, which describe in detail the interaction between the OAuth client and the Authorization Server (AS) during the flow that resulted in the issuance of the token.¶
The process by which the client interacts with the authorization server is out of scope.¶
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.¶
An OAuth 2.0 access token encoded in JWT format and complying with the requirements described in [RFC9068].¶
This specification uses the terms "access token", "authorization server", "authorization endpoint", "authorization request", "client", "protected resource", and "resource server" defined by "The OAuth 2.0 Authorization Framework" [RFC6749].¶
The following claims extend the [RFC9068] access token payload data structure:¶
The claims listed below reflect the grant type and extensions used by the OAuth client with the Authorization Server during the authorization request. Their values are generated dynamically and consistent across all the tokens generated for the given authorization request.¶
gty:REQUIRED - a string that describes the OAuth2 authorization grant type the client requested for the issuance of the access token. The value used as the gty claim MUST comply to existing grant flows described in the following specifications: section 1.3 of [RFC6749], section 2. of [RFC7591], section 2.1 of [RFC8693], and section 4 of [OpenID.CIBA]. Furthermore since future grants may also be developped, this claim is not limited to existing flows, but should also encompass future innovations. The possible values of this claim are registered with IANA (see below). Non-normative example value: "client_credentials".¶
cxt:REQUIRED - defines the list of extensions the client used in conjonction with the OAuth2 authorization grant type used for the issuance of the access token. For example but not limited to: Proof Key for Code Exchange by OAuth Public Clients (or PKCE) as defined in [RFC7636], Demonstrating Proof of Possession (or DPoP) as defined in [RFC9449]. The claim value is an array of strings that lists the identifiers of extensions used. Values used in the cxt Claim MUST be valid values registered with the IANA OAuth Parameters registry @TODO. These values reference, without being limited to, values established through section 2 of [RFC8414], and Section 5.1 of [RFC9449]. Non-normative example: "[dpop,pkce]".¶
The claims listed in this section MAY be issued and reflect strength of the mechanism used to authenticate the OAuth2 Client client itself as part of the access token issuance flow. Their values are fixed and remain the same across all access tokens that derive from a given authorization response, whether the access token was obtained directly in the response (e.g., via the implicit flow) or after obtaining a new access token using a refresh token. Those values may change if an access token is exchanged for another through the Token Exchange [RFC8693] procedure, in that case these claims will reflect the details of this new request.¶
ccr:OPTIONAL - refers to the authentication context class that the Oauth client achieved with the AS during the authorization flow. The value of this claim must be an absolute URI that can be registered with IANA. It should support present, future or custom values. If IANA registered URIs are used, then their meaning and semantics should be respected and used as defined in the registry. Parties using this custom claim values need to agree upon the semantics of the values used, which may be context specific. Non-normative example: "urn:org:iana:client:assurance:level_1".¶
cmr:OPTIONAL - an Identifier String that defines the authentication methods the client used when authenticating to the authorization server. The claim may indicate the usage of private JWT as defined in [RFC7521] and [RFC7523] or HTTP message signature as defined in [RFC9421], or simple client secret as defined in [RFC6749] . The cmr value is a case-sensitive string, which values SHOULD be registered with the IANA OAuth Token Endpoint Authentication Methods Values registry [IANA.oauth-parameters_token-endpoint-auth-method] defined by [RFC7591]; parties using this claim will need to agree upon the meanings of any unregistered values used, which may be context specific.¶
Not all Authorizartion Servers (AS) may support the claims described in this specification. It is therefore necessary to provide a way for an OAuth Resource Server to determine whether it can rely on the claims described here. This document therefore extends the OAuth2.0 Authorization Server Metadata [RFC8414] specification by adding the following metadata value :¶
support_client_extentison_claims:Boolean parameter indicating whether the authorization server will return the extension claims described in this RFC.¶
Note that the non presence of support_client_extentison_claims is sufficient for the client to determine that the server is not capable and therefore will not return the extension claimns described in this RFC. This ensures backward compatibility with all existing AS implementations.¶
An authorization server supporting the claims described in this document MUST issue a JWT access token with client extensions claims described in this RFC in response to any authorization grant defined by [RFC6749], as well as subsequent extensions meant to result in an access token.¶
This specification does not change any of the requirements for validating access tokens, as defined in section 4 of the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens specification [RFC9068].¶
The JWT access token data layout described here is the same as the struture of the JWT access token as defined by the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens specification [RFC9068].¶
The Best Current Practice for OAuth 2.0 Security [RFC9700] is still applicable.¶
This specification registers the following grant type in the [IANA.oauth-parameters] OAuth Grant Type registry.¶
jwt-bearer grant type
urn:ietf:params:oauth:grant-type:jwt-bearer¶
IETF¶
section 2. of [RFC7591] and section 6 of [I-D.parecki-oauth-identity-assertion-authz-grant]¶
ciba grant type
urn:openid:params:grant-type:ciba¶
IETF¶
section 4. of [OpenID.CIBA]¶
This specification registers the following grant extension type in the [IANA.oauth-parameters] OAuth Grant Extension Type registry.¶
wpt grant extension type
wpt¶
IETF¶
This RFC as a reference to section 4.2 of [I-D.ietf-wimse-s2s-protocol]¶
This specification registers additional token endpoint authentication methods in the [IANA.oauth-parameters] OAuth Token Endpoint Authentication Methods registry.¶
jwt-bearer token endpoint authentication method
jwt-bearer¶
IETF¶
This RFC as a reference to [RFC7591] and [I-D.parecki-oauth-identity-assertion-authz-grant]¶
jwt-svid token endpoint authentication method
jwt-svid¶
IETF¶
This RFC as a reference to SPIFFE JWT-SVID¶
wit token endpoint authentication method
wit¶
IETF¶
This RFC as a reference to [I-D.ietf-wimse-s2s-protocol]¶
txn_token token endpoint authentication method
txn_token¶
IETF¶
This RFC as a reference to [I-D.ietf-oauth-transaction-tokens]¶
Section X.Y of this specification refers to the attributes gty, cxt, ccr, and cmr to express client metadata JWT access tokens. This section registers those attributes as claims in the [IANA.jwt] registry introduced in [RFC7519].¶
gty claim definition
Specification Document(s): Section X.Y of this document¶
TODO acknowledge.¶