]> Okta

aaron@parecki.com

Security Web Authorization Protocol jwt dpop authorization This specification defines a new OAuth 2.0 authorization grant type for exchanging a JSON Web Token (JWT) assertion that is bound to a key for an access token. To use the assertion, the client must prove possession of that key using the Demonstrating Proof of Possession (DPoP) mechanism. Unlike the JWT bearer grant, a stolen assertion cannot be used by a party that does not hold the private key. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants defines the use of a JWT as an authorization grant, using the grant type urn:ietf:params:oauth:grant-type:jwt-bearer. This grant type describes the use of a JWT authorization grant as a bearer token, which is susceptible to reuse by any party that obtains one. OAuth 2.0 Demonstrating Proof of Possession (DPoP) defines a mechanism to bind access tokens to a specific cryptographic key. This prevents the token from being used by any party that does not have access to the private key. This specification extends the proof-of-possession concept to the authorization grant itself. It defines a new grant type, urn:ietf:params:oauth:grant-type:jwt-dpop, for cases where the JWT assertion is already bound to a DPoP key. To exchange the assertion for an access token, the client must provide a DPoP proof demonstrating possession of the key to which the assertion is bound. This makes the JWT assertion a sender-constrained credential. A motivating use case is the Identity Assertion JWT Authorization Grant , in which a client obtains a JWT assertion from an identity provider, typically using Token Exchange , and presents it to the authorization server of a different trust domain. Binding that assertion to a DPoP key prevents it from being used by any party other than the client that requested it, and allows the resulting access token to be bound to the same key.

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 when, and only when, they appear in all capitals, as shown here.

Terminology This specification uses the terminology of , , , and .

DPoP-bound JWT assertion:

A JWT assertion that contains a cnf claim with a jkt confirmation method member identifying the public key to which the assertion is bound.

Obtaining a DPoP-Bound JWT Assertion This specification does not define how a client obtains a DPoP-bound JWT assertion. Any mechanism may be used, provided that the issuer of the assertion binds it to a key controlled by the client. This section describes requirements on the issuer, and one way of meeting them. The issuer of a DPoP-bound JWT assertion:

• MUST include a cnf claim containing a jkt confirmation method member, whose value is the JWK SHA-256 Thumbprint of the client's public key, as described in .
• SHOULD verify that the client possesses the private key corresponding to that public key before issuing the assertion.
• MUST NOT include more than one jkt value, or any other confirmation method member alongside jkt.

When the assertion is obtained from an OAuth token endpoint, such as by Token Exchange , the client can demonstrate possession of the key by including a DPoP header field in that request, as defined in . The issuer validates the DPoP proof and uses the thumbprint of the public key in the proof as the value of cnf.jkt in the issued assertion. The client then uses the same key when presenting the assertion as described in . For example, when obtaining an Identity Assertion JWT Authorization Grant (ID-JAG) as described in , the client includes a DPoP header field in the Token Exchange request to the identity provider, and the identity provider includes the resulting cnf.jkt value in the issued ID-JAG. The following non-normative example shows the decoded claims of a DPoP-bound ID-JAG:

HTTP Parameter Bindings for Transporting Assertions The OAuth Assertion Framework defines generic HTTP parameters for transporting assertions (a.k.a. security tokens) during interactions with a token endpoint. This section defines specific parameters and treatments of those parameters for use with DPoP-bound JWT assertions.

Using DPoP-Bound JWT Assertions as Authorization Grants To use a DPoP-bound JWT assertion as an authorization grant, the client makes an access token request as defined in with the following specific parameter values and encodings.

grant_type:

REQUIRED - The value MUST be urn:ietf:params:oauth:grant-type:jwt-dpop

assertion:

REQUIRED - A single JWT, as defined in , that contains a cnf claim as described in .

scope:

OPTIONAL - The scope parameter may be used, as defined in , to indicate the requested scope.

Authentication of the client is optional, as described in and consequently, the client_id is only needed when a form of client authentication that relies on the parameter is used. The client MUST also include a DPoP header field as defined in , which constitutes a proof of possession for the key to which the assertion is bound. The following example demonstrates an access token request with a DPoP-bound JWT assertion as an authorization grant (with extra line breaks for display purposes only). The complete request, with decoded values, is shown in .

JWT Format and Processing Requirements The authorization server MUST validate the JWT according to the criteria below. Application of additional restrictions and policy are at the discretion of the authorization server.

1. The authorization server MUST validate the DPoP proof in the DPoP header field as described in .
2. The authorization server MUST validate the JWT assertion according to the processing rules in (including ) and .
3. The authorization server MUST verify that the JWT assertion contains a cnf claim as defined in , and that the cnf claim contains a jkt confirmation method member as defined in .
4. The authorization server MUST verify that the public key in the jwk JOSE Header Parameter of the DPoP proof matches the key to which the JWT assertion is bound. This is done in the same way a resource server confirms that a DPoP-bound access token matches the key of a DPoP proof (check 12 in ), using the JWK Thumbprint confirmation method of : compute the base64url-encoded JWK SHA-256 Thumbprint of that public key, and compare it to the value of cnf.jkt in the assertion.

If the DPoP proof is missing or invalid (step 1), the authorization server MUST return an error response as described in (invalid_dpop_proof), or (use_dpop_nonce) if a nonce is required. If any of the remaining validation steps fail, the authorization server MUST return an invalid_grant error response.

DPoP Nonces and Replay The authorization server MAY require the client to include a nonce in the DPoP proof, as described in . In that case the authorization server responds to a request without a valid nonce with a use_dpop_nonce error and a DPoP-Nonce header field, and the client retries the request with a new DPoP proof containing the provided nonce and the same assertion. The authorization server SHOULD perform replay detection on the jti claim of the DPoP proof, as described in . The authorization server MAY also reject assertions whose jti has already been used, as described in . If the authorization server records assertion jti values to detect replay, it MUST NOT record the assertion's jti as used when the request is rejected because of an invalid or missing DPoP proof or nonce. Otherwise a client following the nonce retry described above would have its assertion rejected as a replay. Performing the validation steps in the order given in achieves this.

Use with the JWT Bearer Grant Type An authorization server that supports the grant type defined in this specification MUST NOT accept a DPoP-bound JWT assertion as an authorization grant using the urn:ietf:params:oauth:grant-type:jwt-bearer grant type defined in , and MUST return an invalid_grant error response if one is presented. This applies whether or not the request includes a DPoP header field. An authorization server that supports this specification SHOULD include urn:ietf:params:oauth:grant-type:jwt-dpop in the grant_types_supported value of its authorization server metadata .

Access Token Response If the request is valid, the authorization server issues an access token. The issued access token SHOULD be DPoP-bound to the key from the DPoP proof, which is the same key to which the assertion is bound. In this case the token_type in the response MUST be DPoP, as described in . The authorization server MAY instead issue a bearer access token, for example when the protected resources for which the token is intended do not support DPoP. In this case the token_type MUST be Bearer. See for the security implications. If the authorization server issues a refresh token, the refresh token is subject to the binding requirements of : a refresh token issued to a public client MUST be bound to the key from the DPoP proof. The authorization server SHOULD NOT issue a refresh token whose lifetime extends beyond what is permitted by the policy under which the assertion was issued.

Security Considerations The security considerations described within the following specifications are all applicable to this document: "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" , "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants" , "Updates to OAuth 2.0 JSON Web Token (JWT) Client Authentication and Assertion-Based Authorization Grants" , "OAuth 2.0 Demonstrating Proof of Possession (DPoP)" , "The OAuth 2.0 Authorization Framework" , and "JSON Web Token (JWT)" .

Downgrade to the JWT Bearer Grant The binding of a DPoP-bound JWT assertion only provides protection if the authorization server enforces it. An attacker that obtains a DPoP-bound JWT assertion, but not the corresponding private key, could present the assertion using the urn:ietf:params:oauth:grant-type:jwt-bearer grant type instead of the grant type defined in this specification. An authorization server that processes the assertion only according to would ignore the cnf claim and issue an access token, defeating the binding entirely. Authorization servers that support this specification prevent this attack by rejecting DPoP-bound JWT assertions presented with the jwt-bearer grant type, as required by . Authorization servers that do not implement this specification are not aware of this requirement and may accept a DPoP-bound JWT assertion as a bearer assertion. For this reason, an issuer of DPoP-bound JWT assertions SHOULD NOT issue one for use at an authorization server unless it knows that the authorization server supports this specification, for example because the authorization server advertises urn:ietf:params:oauth:grant-type:jwt-dpop in its grant_types_supported metadata , or by prior configuration.

Issuing Bearer Access Tokens When the authorization server issues a bearer access token in response to this grant, the DPoP binding no longer protects the access token. The assertion cannot be used by a party that does not hold the private key, but the resulting access token can be used by any party that obtains it. Authorization servers SHOULD issue DPoP-bound access tokens whenever the intended protected resources support them. Even when a bearer access token is issued, a refresh token issued to a public client is still bound to the DPoP key, as described in . As noted there, binding only the refresh token can improve the security posture even when protected resources do not support DPoP, since a stolen refresh token cannot be used to obtain new access tokens without the private key.

Privacy Considerations The jkt value in a DPoP-bound JWT assertion is a stable identifier of the client's key. When a client uses the same key with an identity provider, with one or more authorization servers, and with the protected resources to which DPoP-bound access tokens are presented, each of these parties observes the same key, either in DPoP proofs or as cnf.jkt in assertions and access tokens. Colluding parties could use this to correlate the client's activity across them, beyond what is already possible from the identity of the client or the user. To limit this, a client MAY use a different DPoP key for each authorization server at which it presents DPoP-bound JWT assertions. Since the assertion is bound to the key used when requesting it (see ), the client needs to choose the key it will use at the target authorization server before requesting the assertion. A client SHOULD NOT reuse a DPoP key across unrelated users or sessions where doing so would let those otherwise unlinked activities be correlated. This specification does not change the claims about the user that are conveyed in the assertion, and the privacy considerations of the specification defining the assertion, such as , continue to apply.

IANA Considerations

OAuth URI Registration This specification requests registration of the following value in the "OAuth URI" registry established by .

• URN: urn:ietf:params:oauth:grant-type:jwt-dpop
• Common Name: DPoP-bound JWT Authorization Grant
• Change Controller: IESG
• Specification Document(s): this document

References Normative References This document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. This specification defines a method for computing a hash value over a JSON Web Key (JWK). It defines which fields in a JWK are used in the hash computation, the method of creating a canonical form for those fields, and how to convert the resulting Unicode string into a byte sequence to be hashed. The resulting hash value can be used for identifying or selecting the key represented by the JWK that is the subject of the thumbprint. This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. Self-Issued Consulting Ping Identity Disney Okta This document updates RFC7521, RFC7522, RFC7523 and RFC9126 with respect to the treatment of audience values in OAuth 2.0 Client Assertion Authentication and Assertion-based Authorization Grants to address a security vulnerability identified in the previous requirements for those audience values in multiple OAuth 2.0 specifications. This document describes a mechanism for sender-constraining OAuth 2.0 tokens via a proof-of-possession mechanism on the application level. This mechanism allows for the detection of replay attacks with access and refresh tokens. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation. Okta Independent Ping Identity This specification provides a mechanism for an application to use an identity assertion to obtain an access token for a third-party API by coordinating through an identity provider that the downstream Resource Authorization Server already trusts for single sign-on (SSO), using Token Exchange [RFC8693] and JWT Profile for OAuth 2.0 Authorization Grants [RFC7523]. This pattern is informally referred to as Cross-App Access (XAA).

Complete Example This appendix contains a complete example of an access token request using a DPoP-bound ID-JAG. The signatures in this example can be verified using the public keys shown. Line breaks within JWTs and within the canonical JWK below are for display purposes only.

Identity Provider Key The ID-JAG is signed by the identity provider using the following key, shown as a JWK:

DPoP-Bound JWT Assertion The decoded JOSE header of the ID-JAG: The decoded claims of the ID-JAG: The encoded and signed ID-JAG:

DPoP Proof The decoded JOSE header of the DPoP proof, which contains the client's public key: The decoded claims of the DPoP proof: The encoded and signed DPoP proof:

Thumbprint Comparison The authorization server constructs the canonical JWK of the public key in the jwk header of the DPoP proof, as described in : The base64url-encoded SHA-256 hash of this value is: This matches the value of cnf.jkt in the ID-JAG, so the assertion is bound to the key used to sign the DPoP proof.

Access Token Request The resulting access token request:

Acknowledgments The authors would like to thank the following people for their contributions and reviews of this specification: Filip Skokan, Karl McGuinness.

Document History [[ To be removed from the final specification ]] -02

• Rewrote the abstract to describe binding of the assertion rather than the access token.
• Defined "DPoP-bound JWT assertion" and used the term consistently.
• Use DPoP error codes for DPoP proof validation failures.
• Moved Access Token Response to a top-level section.
• Added a section describing requirements on the issuer of a DPoP-bound JWT assertion, with an example.
• Added the Identity Assertion JWT Authorization Grant as a motivating use case.
• Added Privacy Considerations.
• Added a complete, verifiable example in an appendix.
• Added guidance on DPoP nonces and replay detection, including not consuming the assertion on a nonce retry.
• Clarified when bearer access tokens may be issued, and the binding of refresh tokens.
• Added requirement to reject DPoP-bound JWT assertions presented with the jwt-bearer grant type, and security considerations for downgrade attacks.
• Clarified that the DPoP proof's jwk is compared to cnf.jkt by computing its JWK SHA-256 Thumbprint, as a resource server does for DPoP-bound access tokens.

-01

• Changed DPoP check to use jkt string instead of jwk object to be able to use simple string comparison.