]> Okta

aaron@parecki.com

Security Web Authorization Protocol jwt dpop authorization This specification defines a new OAuth 2.0 authorization grant type that uses a JSON Web Token (JWT) assertion to request an access token that is bound to a specific key using the Demonstration of Proof-of-Possession (DPoP) mechanism. This provides a higher level of security than a simple bearer token, as the client must prove possession of the key to use the access token. 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 Demonstration of Proof-of-Possession at the Application Layer (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.

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 .

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 JWT DPoP-Bound Tokens.

Using DPoP-Bound JWTs as Authorization Grants To use a DPoP-bound JWT 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 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 JWT as an authorization grant (with extra line breaks for display purposes only):

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 as described in . The htm claim of the DPoP JWT MUST be POST, and the htu claim must match the token endpoint URL.
2. The authorization server MUST validate the JWT assertion according to the processing rules in and .
3. The authorization server MUST verify that the JWT assertion contains a cnf claim as defined in . This cnf claim MUST contain a jkt property with the hash of the public key as defined in .
4. The authorization server MUST verify that the value of the the jkt property of the cnf claim of the JWT assertion exactly matches the value of the jkt in the DPoP proof.

If any of these validation steps fail, the authorization server MUST return an invalid_grant error response.

Access Token Response If the request is valid, the authorization server issues an access token. The issued access token SHOULD also be DPoP-bound to the same key from the DPoP proof. In this case, the token_type of the access token MUST be DPoP, and the response MUST include a token_type parameter with the value DPoP. If a bearer token is issued, the token_type MUST be Bearer.

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)" .

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

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 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 specification updates the requirements for 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.

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 ]] -01

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