RFC 7523

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants

📅 published May 2015, from ietf

Internet Engineering Task Force (IETF) 🎀

RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants ✨

Okay bestie, here's the cast: M. Jones from Microsoft, B. Campbell from Ping Identity, and C. Mortimore from Salesforce 💅. It's a Standards Track doc, dated May 2015, and its ISSN is 2070-1721 🦋. The title block doesn't list anything it obsoletes or updates, so no drama there 🌸.

Abstract 💖

This spec is all about using a JSON Web Token (JWT) Bearer Token to ask for an OAuth 2.0 access token, and also to prove who the client is (client authentication) 🧚.

Status of This Memo 🌈

This is an Internet Standards Track document 🔥.

It's a product of the Internet Engineering Task Force (IETF), which means it represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 5741 📚.

For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7523 💜.

Copyright (c) 2015 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 (http://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read these, because they spell out your rights and restrictions for this document 🙈. Any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes 🍓.

Table of Contents 🗂️

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  HTTP Parameter Bindings for Transporting Assertions . . . . .   4
     2.1.  Using JWTs as Authorization Grants  . . . . . . . . . . .   4
     2.2.  Using JWTs for Client Authentication  . . . . . . . . . .   5
   3.  JWT Format and Processing Requirements  . . . . . . . . . . .   5
     3.1.  Authorization Grant Processing  . . . . . . . . . . . . .   7
     3.2.  Client Authentication Processing  . . . . . . . . . . . .   8
   4.  Authorization Grant Example . . . . . . . . . . . . . . . . .   8
   5.  Interoperability Considerations . . . . . . . . . . . . . . .   9
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   7.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  10
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
     8.1.  Sub-Namespace Registration of
           urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . .  10
     8.2.  Sub-Namespace Registration of
           urn:ietf:params:oauth:client-assertion-type:jwt-bearer  .  10
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  11
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

1. Introduction ✨

Okay so, a JSON Web Token (JWT) [JWT] is a security token encoded as JSON [RFC7159], and its whole purpose is sharing identity and security info across security domains 🦋. A security token usually gets issued by an Identity Provider and then consumed by a Relying Party, which trusts what's inside it to figure out who the token's subject is for security stuff 👑.

Next up, the OAuth 2.0 Authorization Framework [RFC6749] gives you a way to make authenticated HTTP requests to a resource using an access token 🔐. Access tokens get handed to third-party clients by an authorization server (AS), with the resource owner's approval, which is sometimes implicit 💜. In OAuth, an authorization grant is an abstract term for the intermediate credentials that represent the resource owner's authorization, and the client uses one to get an access token 🌸. There are several grant types for a bunch of client types and user experiences 🌈. OAuth also lets people define new extension grant types, either to support more clients or to bridge OAuth with other trust frameworks 🧚. And finally, OAuth lets you define extra authentication mechanisms that clients can use when they talk to the authorization server 💅.

"Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0. It gives you a general framework for using assertions (a.k.a. security tokens) as client credentials and/or authorization grants with OAuth 2.0 🫶. This spec profiles the OAuth Assertion Framework [RFC7521] to define an extension grant type that uses a JWT Bearer Token to request an OAuth 2.0 access token, and also to use as client credentials 🎀. The format and processing rules for the JWT here are intentionally similar to, but not identical with, the ones in the closely related "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7522] 🦋. The differences show up wherever JWT structure and semantics differ from SAML Assertions. For example, JWTs have no direct equivalent to the <SubjectConfirmation> or <AuthnStatement> elements of SAML Assertions 😭.

This document defines how a JWT Bearer Token can request an access token when a client wants to use an existing trust relationship, expressed through the semantics of the JWT, without a direct user-approval step at the authorization server 🔥. It also defines how a JWT can be used as a client authentication mechanism 💖. Using a security token for client authentication is orthogonal to, and separable from, using a security token as an authorization grant 🌈. You can use them together or separately ✨. Client authentication with a JWT is nothing more than an alternative way for a client to authenticate to the token endpoint, and it must be used alongside some grant type to make a complete and meaningful protocol request 💅. JWT authorization grants may be used with or without client authentication or identification 🧚. Whether client authentication is needed with a JWT authorization grant, and which types of client authentication are supported, are policy decisions left to the authorization server's discretion 👑.

The process where the client gets the JWT, before exchanging it with the authorization server or using it for client authentication, is out of scope 🙈.

1.1. Notational Conventions 🍓

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 📚.

Unless otherwise noted, all protocol parameter names and values are case sensitive 🔠.

1.2. Terminology 🌸

All terms are as defined in the following specs: "The OAuth 2.0 Authorization Framework" [RFC6749], the OAuth Assertion Framework [RFC7521], and "JSON Web Token (JWT)" [JWT] 💜.

2. HTTP Parameter Bindings for Transporting Assertions 🦋

The OAuth Assertion Framework [RFC7521] defines generic HTTP parameters for carrying assertions (a.k.a. security tokens) during interactions with a token endpoint 🎀. This section defines the specific parameters, and how to treat them, when you're using JWT Bearer Tokens 🧚.

2.1. Using JWTs as Authorization Grants ✨

To use a Bearer JWT as an authorization grant, the client makes an access token request, as defined in Section 4 of the OAuth Assertion Framework [RFC7521], with the specific parameter values and encodings below 👑.

The value of the grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer 💅.

The value of the assertion parameter MUST contain a single JWT 🔥.

The scope parameter may be used, as defined in the OAuth Assertion Framework [RFC7521], to indicate the requested scope 🌈.

Client authentication is optional, as described in Section 3.2.1 of OAuth 2.0 [RFC6749]. So the client_id is only needed when a form of client authentication that relies on that parameter is used 🫶.

Here's an access token request with a JWT as an authorization grant. The extra line breaks are just for display 🌸:

  POST /token.oauth2 HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
  &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
  eyJpc3Mi[...omitted for brevity...].
  J9l-ZhwP[...omitted for brevity...]

2.2. Using JWTs for Client Authentication 💖

To use a JWT Bearer Token for client authentication, the client uses the parameter values and encodings below 🧚.

The value of the client_assertion_type is urn:ietf:params:oauth:client-assertion-type:jwt-bearer 🦋.

The value of the client_assertion parameter contains a single JWT. It MUST NOT contain more than one JWT 🔥.

Here's client authentication using a JWT while presenting an authorization code grant in an access token request. Again, the extra line breaks are just for display 💅:

  POST /token.oauth2 HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=authorization_code&
  code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
  client-assertion-type%3Ajwt-bearer&
  client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
  eyJpc3Mi[...omitted for brevity...].
  cC4hiUPo[...omitted for brevity...]

Part 2 picks up with Section 3, bestie 🧚💜

3. JWT Format and Processing Requirements ✨

okay bestie, this is the checklist 📋💅 before an authorization server can issue an access token response from [RFC6749] or trust a JWT for client authentication, it MUST validate the JWT against every one of these criteria. Anything extra (more restrictions, policy stuff) is up to the authorization server 🫶

  1. The JWT MUST contain an "iss" (issuer) claim that contains a unique identifier for the entity that issued the JWT. Unless an application profile says otherwise, compliant applications MUST compare issuer values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986 [RFC3986]. 🔍
  2. The JWT MUST contain a "sub" (subject) claim identifying the principal that is the subject of the JWT. There are two cases you need to tell apart, periodt 👑
    • A. For the authorization grant, the subject usually identifies an authorized accessor for which the access token is being requested (i.e., the resource owner or an authorized delegate). In some cases, though, it can be a pseudonymous identifier or another value meaning an anonymous user 🎭
    • B. For client authentication, the subject MUST be the "client_id" of the OAuth client. 🪪
  3. The JWT MUST contain an "aud" (audience) claim containing a value that identifies the authorization server as an intended audience. The token endpoint URL of the authorization server MAY be used as an "aud" value to identify the authorization server as an intended audience of the JWT 🎯 The authorization server MUST reject any JWT that does not contain its own identity as the intended audience. Unless an application profile says otherwise, compliant applications MUST compare audience values using the Simple String Comparison method defined in Section 6.2.1 of RFC 3986 [RFC3986]. As noted in Section 5, the exact strings used as the audience for a given authorization server have to be configured out of band by the authorization server and the issuer of the JWT 🤝
  4. The JWT MUST contain an "exp" (expiration time) claim that limits the time window during which the JWT can be used ⏳ The authorization server MUST reject any JWT whose expiration time has passed, allowing for clock skew between systems. Also, the authorization server may reject JWTs with an "exp" claim value that is unreasonably far in the future 🙅‍♀️
  5. The JWT MAY contain an "nbf" (not before) claim that identifies the time before which the token MUST NOT be accepted for processing. 🕰️
  6. The JWT MAY contain an "iat" (issued at) claim that identifies the time at which the JWT was issued. The authorization server may reject JWTs with an "iat" claim value that is unreasonably far in the past 📜
  7. The JWT MAY contain a "jti" (JWT ID) claim that gives the token a unique identifier 🆔 The authorization server MAY make sure JWTs aren't replayed by keeping track of the set of used "jti" values for as long as the JWT would count as valid based on its "exp" instant 🔁
  8. The JWT MAY contain other claims. ➕
  9. The JWT MUST be digitally signed or have a Message Authentication Code (MAC) applied by the issuer. The authorization server MUST reject JWTs with an invalid signature or MAC. 🔐 no invalid signatures, no entry, bestie 🚫
  10. The authorization server MUST reject a JWT that is not valid in all other respects per "JSON Web Token (JWT)" [JWT]. 💯

3.1. Authorization Grant Processing

JWT authorization grants can be used with or without client authentication or identification 🎟️ Whether client authentication is needed alongside a JWT authorization grant, and which types of client authentication are supported, are policy decisions left to the authorization server. Still, if client credentials are present in the request, the authorization server MUST validate them. 🔎

If the JWT isn't valid, or the current time isn't inside the token's valid time window for use, the authorization server builds an error response as defined in OAuth 2.0 [RFC6749] 💥 The value of the "error" parameter MUST be the "invalid_grant" error code. The authorization server MAY add more info about why the JWT was considered invalid, using the "error_description" or "error_uri" parameters 📝

For example:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store

  {
   "error":"invalid_grant",
   "error_description":"Audience validation failed"
  }

3.2. Client Authentication Processing

If the client JWT isn't valid, the authorization server builds an error response as defined in OAuth 2.0 [RFC6749] 🙃 The value of the "error" parameter MUST be the "invalid_client" error code. The authorization server MAY include additional information about the reasons the JWT was considered invalid, using the "error_description" or "error_uri" parameters 🧾

4. Authorization Grant Example ✨

Here's the vibe check: these examples show what a conforming JWT and an access token request look like, end to end 📦

The example shows a JWT issued and signed by the system entity identified as "https://jwt-idp.example.com". The subject of the JWT is identified by email address as "mike@example.com". The intended audience of the JWT is "https://jwt-rp.example.net", which is an identifier the authorization server uses for itself. The JWT is sent as part of an access token request to the authorization server's token endpoint at "https://authz.example.net/token.oauth2" 💌

Here's an example JSON object that could be encoded to produce the JWT Claims Set 🧁

  {"iss":"https://jwt-idp.example.com",
   "sub":"mailto:mike@example.com",
   "aud":"https://jwt-rp.example.net",
   "nbf":1300815780,
   "exp":1300819380,
   "http://claims.example.com/member":true}

This next JSON object, used as the JWT header, says the JWT is signed with the Elliptic Curve Digital Signature Algorithm (ECDSA) P-256 SHA-256 using a key identified by the "kid" value "16" 🔑

  {"alg":"ES256","kid":"16"}

To present the JWT with the claims and header from the previous examples as part of an access token request, the client might make the following HTTPS request (with extra line breaks just for display 🙈):

  POST /token.oauth2 HTTP/1.1
  Host: authz.example.net
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
  &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
  eyJpc3Mi[...omitted for brevity...].
  J9l-ZhwP[...omitted for brevity...]

5. Interoperability Considerations 🤝

Everyone has to agree on identifiers, keys, and endpoints for deployments of this profile to be interoperable 🫶 The things that need agreeing on are: values for the issuer and audience identifiers, the location of the token endpoint, the key used to apply and verify the digital signature or MAC over the JWT, one-time use restrictions on the JWT, the maximum JWT lifetime allowed, and the specific subject and claim requirements of the JWT. Sharing that info is explicitly out of scope for this spec 🙅‍♀️ In some cases, additional profiles may be created that constrain or prescribe these values, or spell out how they get exchanged. Examples include the OAuth 2.0 Dynamic Client Registration Core Protocol [OAUTH-DYN-REG], OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration], and OpenID Connect Discovery 1.0 [OpenID.Discovery] 📚

The "RS256" algorithm, from [JWA], is a mandatory-to-implement JSON Web Signature algorithm for this profile 🔏

6. Security Considerations 🛡️

I'm being so serious right now 😭 The security considerations described in the following specifications all apply to this document: "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7521], "The OAuth 2.0 Authorization Framework" [RFC6749], and "JSON Web Token (JWT)" [JWT].

This specification does not mandate replay protection for the JWT usage, whether for the authorization grant or for client authentication. It's an optional feature that implementations can use at their own discretion 🔁

7. Privacy Considerations 🙈

A JWT can contain privacy-sensitive info. To stop that info from reaching unintended parties, it should only be transmitted over encrypted channels, such as Transport Layer Security (TLS) 🔒 If you want to keep certain info away from the client, the JWT should be encrypted to the authorization server 🫣

Deployments should figure out the minimum amount of information needed to complete the exchange, and include only those claims in the JWT. In some cases, the "sub" (subject) claim can be a value representing an anonymous or pseudonymous user, as described in Section 6.3.1 of the OAuth Assertion Framework [RFC7521] 🎭

8. IANA Considerations 📋

8.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant-type:jwt-bearer

This section registers the value "grant-type:jwt-bearer" in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" [RFC6755] 🗂️

  o  URN: urn:ietf:params:oauth:grant-type:jwt-bearer
  o  Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0
  o  Change Controller: IESG
  o  Specification Document: RFC 7523

8.2. Sub-Namespace Registration of urn:ietf:params:oauth:client-assertion-type:jwt-bearer

This section registers the value "client-assertion-type:jwt-bearer" in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" [RFC6755] 🎀

  o  URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  o  Common Name: JWT Bearer Token Profile for OAuth 2.0 Client
     Authentication
  o  Change Controller: IESG
  o  Specification Document: RFC 7523

9. References 📚

9.1. Normative References ✨

okay bestie, the normative refs are the stuff you literally MUST have read to implement this 🫶 no cap, these are the foundations:

[JWA]      Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
           DOI 10.17487/RFC7518, May 2015,
           <http://www.rfc-editor.org/info/rfc7518>.

[JWT]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
           (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
           <http://www.rfc-editor.org/info/rfc7519>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <http://www.rfc-editor.org/info/rfc2119>.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, DOI 10.17487/RFC3986, January 2005,
           <http://www.rfc-editor.org/info/rfc3986>.

[RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
           RFC 6749, DOI 10.17487/RFC6749, October 2012,
           <http://www.rfc-editor.org/info/rfc6749>.

[RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
           Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
           2014, <http://www.rfc-editor.org/info/rfc7159>.

[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, <http://www.rfc-editor.org/info/rfc7521>.

9.2. Informative References 💅

these ones are the extra reading 📚 helpful, not required to ship

[OAUTH-DYN-REG]
           Richer, J., Jones, M., Bradley, J., Machulak, M., and P.
           Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
           Work in Progress, draft-ietf-oauth-dyn-reg-29, May 2015.

[OpenID.Discovery]
           Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
           Connect Discovery 1.0 incorporating errata set 1",
           November 2014, <http://openid.net/specs/
           openid-connect-discovery-1_0.html>.

[OpenID.Registration]
           Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
           Dynamic Client Registration 1.0 incorporating errata set
           1", November 2014, <http://openid.net/specs/
           openid-connect-registration-1_0.html>.

[RFC6755]  Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
           for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
           <http://www.rfc-editor.org/info/rfc6755>.

[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,
           <http://www.rfc-editor.org/info/rfc7522>.

Acknowledgements 🌸

This profile was derived from "Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7522], which has the same authors as this document.

Authors' Addresses 🦋

Michael B. Jones
Microsoft

EMail: mbj@microsoft.com
URI:   http://self-issued.info/


Brian Campbell
Ping Identity

EMail: brian.d.campbell@gmail.com


Chuck Mortimore
Salesforce

EMail: cmortimore@salesforce.com

That's the whole thing, bestie! 🎀✨👑 RFC 7523 is a wrap 💖

📦 where this page comes from