draft-ietf-oauth-jwt-bearer-12.txt   rfc7523.txt 
OAuth Working Group M. Jones Internet Engineering Task Force (IETF) M. Jones
Internet-Draft Microsoft Request for Comments: 7523 Microsoft
Intended status: Standards Track B. Campbell Category: Standards Track B. Campbell
Expires: May 16, 2015 Ping Identity ISSN: 2070-1721 Ping Identity
C. Mortimore C. Mortimore
Salesforce Salesforce
November 12, 2014 May 2015
JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and JSON Web Token (JWT) Profile
Authorization Grants for OAuth 2.0 Client Authentication and Authorization Grants
draft-ietf-oauth-jwt-bearer-12
Abstract Abstract
This specification defines the use of a JSON Web Token (JWT) Bearer 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 Token as a means for requesting an OAuth 2.0 access token as well as
for use as a means of client authentication. for client authentication.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
This Internet-Draft will expire on May 16, 2015. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7523.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 23 skipping to change at page 2, line 21
2.1. Using JWTs as Authorization Grants . . . . . . . . . . . 4 2.1. Using JWTs as Authorization Grants . . . . . . . . . . . 4
2.2. Using JWTs for Client Authentication . . . . . . . . . . 5 2.2. Using JWTs for Client Authentication . . . . . . . . . . 5
3. JWT Format and Processing Requirements . . . . . . . . . . . 5 3. JWT Format and Processing Requirements . . . . . . . . . . . 5
3.1. Authorization Grant Processing . . . . . . . . . . . . . 7 3.1. Authorization Grant Processing . . . . . . . . . . . . . 7
3.2. Client Authentication Processing . . . . . . . . . . . . 8 3.2. Client Authentication Processing . . . . . . . . . . . . 8
4. Authorization Grant Example . . . . . . . . . . . . . . . . . 8 4. Authorization Grant Example . . . . . . . . . . . . . . . . . 8
5. Interoperability Considerations . . . . . . . . . . . . . . . 9 5. Interoperability Considerations . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8.1. Sub-Namespace Registration of urn:ietf:params:oauth 8.1. Sub-Namespace Registration of
:grant-type:jwt-bearer . . . . . . . . . . . . . . . . . 10 urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . 10
8.2. Sub-Namespace Registration of urn:ietf:params:oauth 8.2. Sub-Namespace Registration of
:client-assertion-type:jwt-bearer . . . . . . . . . . . . 10 urn:ietf:params:oauth:client-assertion-type:jwt-bearer . 10
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
9.1. Normative References . . . . . . . . . . . . . . . . . . 11 9.1. Normative References . . . . . . . . . . . . . . . . . . 11
9.2. Informative References . . . . . . . . . . . . . . . . . 11 9.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12
Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON) JSON Web Token (JWT) [JWT] is a JSON-based [RFC7159] security token
[RFC7159] based security token encoding that enables identity and encoding that enables identity and security information to be shared
security information to be shared across security domains. A across security domains. A security token is generally issued by an
security token is generally issued by an identity provider and Identity Provider and consumed by a Relying Party that relies on its
consumed by a relying party that relies on its content to identify content to identify the token's subject for security-related
the token's subject for security related purposes. purposes.
The OAuth 2.0 Authorization Framework [RFC6749] provides a method for The OAuth 2.0 Authorization Framework [RFC6749] provides a method for
making authenticated HTTP requests to a resource using an access making authenticated HTTP requests to a resource using an access
token. Access tokens are issued to third-party clients by an token. Access tokens are issued to third-party clients by an
authorization server (AS) with the (sometimes implicit) approval of authorization server (AS) with the (sometimes implicit) approval of
the resource owner. In OAuth, an authorization grant is an abstract the resource owner. In OAuth, an authorization grant is an abstract
term used to describe intermediate credentials that represent the term used to describe intermediate credentials that represent the
resource owner authorization. An authorization grant is used by the resource owner authorization. An authorization grant is used by the
client to obtain an access token. Several authorization grant types client to obtain an access token. Several authorization grant types
are defined to support a wide range of client types and user are defined to support a wide range of client types and user
experiences. OAuth also allows for the definition of new extension experiences. OAuth also allows for the definition of new extension
grant types to support additional clients or to provide a bridge grant types to support additional clients or to provide a bridge
between OAuth and other trust frameworks. Finally, OAuth allows the between OAuth and other trust frameworks. Finally, OAuth allows the
definition of additional authentication mechanisms to be used by definition of additional authentication mechanisms to be used by
clients when interacting with the authorization server. clients when interacting with the authorization server.
The Assertion Framework for OAuth 2.0 Client Authentication and "Assertion Framework for OAuth 2.0 Client Authentication and
Authorization Grants [I-D.ietf-oauth-assertions] specification is an Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0
abstract extension to OAuth 2.0 that provides a general framework for that provides a general framework for the use of assertions (a.k.a.
the use of Assertions (a.k.a. Security Tokens) as client credentials security tokens) as client credentials and/or authorization grants
and/or authorization grants with OAuth 2.0. This specification with OAuth 2.0. This specification profiles the OAuth Assertion
profiles the Assertion Framework for OAuth 2.0 Client Authentication Framework [RFC7521] to define an extension grant type that uses a JWT
and Authorization Grants [I-D.ietf-oauth-assertions] specification to
define an extension grant type that uses a JSON Web Token (JWT)
Bearer Token to request an OAuth 2.0 access token as well as for use Bearer Token to request an OAuth 2.0 access token as well as for use
as client credentials. The format and processing rules for the JWT as client credentials. The format and processing rules for the JWT
defined in this specification are intentionally similar, though not defined in this specification are intentionally similar, though not
identical, to those in the closely related SAML 2.0 Profile for OAuth identical, to those in the closely related specification "Security
2.0 Client Authentication and Authorization Grants Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client
[I-D.ietf-oauth-saml2-bearer] specification. The differences arise Authentication and Authorization Grants" [RFC7522]. The differences
where the structure and semantics of JWTs differ from SAML arise where the structure and semantics of JWTs differ from SAML
assertions. JWTs, for example, have no direct equivalent to the Assertions. JWTs, for example, have no direct equivalent to the
<SubjectConfirmation> or <AuthnStatement> elements of SAML <SubjectConfirmation> or <AuthnStatement> elements of SAML
assertions. Assertions.
This document defines how a JSON Web Token (JWT) Bearer Token can be This document defines how a JWT Bearer Token can be used to request
used to request an access token when a client wishes to utilize an an access token when a client wishes to utilize an existing trust
existing trust relationship, expressed through the semantics of (and relationship, expressed through the semantics of the JWT, without a
digital signature or Message Authentication Code calculated over) the direct user-approval step at the authorization server. It also
JWT, without a direct user approval step at the authorization server. defines how a JWT can be used as a client authentication mechanism.
It also defines how a JWT can be used as a client authentication The use of a security token for client authentication is orthogonal
mechanism. The use of a security token for client authentication is to and separable from using a security token as an authorization
orthogonal to and separable from using a security token as an grant. They can be used either in combination or separately. Client
authorization grant. They can be used either in combination or authentication using a JWT is nothing more than an alternative way
separately. Client authentication using a JWT is nothing more than for a client to authenticate to the token endpoint and must be used
an alternative way for a client to authenticate to the token endpoint in conjunction with some grant type to form a complete and meaningful
and must be used in conjunction with some grant type to form a protocol request. JWT authorization grants may be used with or
complete and meaningful protocol request. JWT authorization grants without client authentication or identification. Whether or not
may be used with or without client authentication or identification. client authentication is needed in conjunction with a JWT
Whether or not client authentication is needed in conjunction with a authorization grant, as well as the supported types of client
JWT authorization grant, as well as the supported types of client
authentication, are policy decisions at the discretion of the authentication, are policy decisions at the discretion of the
authorization server. authorization server.
The process by which the client obtains the JWT, prior to exchanging The process by which the client obtains the JWT, prior to exchanging
it with the authorization server or using it for client it with the authorization server or using it for client
authentication, is out of scope. authentication, is out of scope.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
Unless otherwise noted, all the protocol parameter names and values Unless otherwise noted, all the protocol parameter names and values
are case sensitive. are case sensitive.
1.2. Terminology 1.2. Terminology
All terms are as defined in The OAuth 2.0 Authorization Framework All terms are as defined in the following specifications: "The OAuth
[RFC6749], the Assertion Framework for OAuth 2.0 Client 2.0 Authorization Framework" [RFC6749], the OAuth Assertion Framework
Authentication and Authorization Grants [I-D.ietf-oauth-assertions], [RFC7521], and "JSON Web Token (JWT)" [JWT].
and the JSON Web Token (JWT) [JWT] specifications.
2. HTTP Parameter Bindings for Transporting Assertions 2. HTTP Parameter Bindings for Transporting Assertions
The Assertion Framework for OAuth 2.0 Client Authentication and The OAuth Assertion Framework [RFC7521] defines generic HTTP
Authorization Grants [I-D.ietf-oauth-assertions] specification parameters for transporting assertions (a.k.a. security tokens)
defines generic HTTP parameters for transporting Assertions (a.k.a. during interactions with a token endpoint. This section defines
Security Tokens) during interactions with a token endpoint. This specific parameters and treatments of those parameters for use with
section defines specific parameters and treatments of those JWT Bearer Tokens.
parameters for use with JWT bearer tokens.
2.1. Using JWTs as Authorization Grants 2.1. Using JWTs as Authorization Grants
To use a Bearer JWT as an authorization grant, the client uses an To use a Bearer JWT as an authorization grant, the client uses an
access token request as defined in Section 4 of the Assertion access token request as defined in Section 4 of the OAuth Assertion
Framework for OAuth 2.0 Client Authentication and Authorization Framework [RFC7521] with the following specific parameter values and
Grants [I-D.ietf-oauth-assertions] specification with the following encodings.
specific parameter values and encodings.
The value of the "grant_type" is "urn:ietf:params:oauth:grant- The value of the "grant_type" is "urn:ietf:params:oauth:grant-
type:jwt-bearer". type:jwt-bearer".
The value of the "assertion" parameter MUST contain a single JWT. The value of the "assertion" parameter MUST contain a single JWT.
The "scope" parameter may be used, as defined in the Assertion The "scope" parameter may be used, as defined in the OAuth Assertion
Framework for OAuth 2.0 Client Authentication and Authorization Framework [RFC7521], to indicate the requested scope.
Grants [I-D.ietf-oauth-assertions] specification, to indicate the
requested scope.
Authentication of the client is optional, as described in Authentication of the client is optional, as described in
Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the Section 3.2.1 of OAuth 2.0 [RFC6749] and consequently, the
"client_id" is only needed when a form of client authentication that "client_id" is only needed when a form of client authentication that
relies on the parameter is used. relies on the parameter is used.
The following example demonstrates an Access Token Request with a JWT The following example demonstrates an access token request with a JWT
as an authorization grant (with extra line breaks for display as an authorization grant (with extra line breaks for display
purposes only): purposes only):
POST /token.oauth2 HTTP/1.1 POST /token.oauth2 HTTP/1.1
Host: as.example.com Host: as.example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiJ9. &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
eyJpc3Mi[...omitted for brevity...]. eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...] J9l-ZhwP[...omitted for brevity...]
2.2. Using JWTs for Client Authentication 2.2. Using JWTs for Client Authentication
To use a JWT Bearer Token for client authentication, the client uses To use a JWT Bearer Token for client authentication, the client uses
the following parameter values and encodings. the following parameter values and encodings.
The value of the "client_assertion_type" is The value of the "client_assertion_type" is
"urn:ietf:params:oauth:client-assertion-type:jwt-bearer". "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
The value of the "client_assertion" parameter contains a single JWT. The value of the "client_assertion" parameter contains a single JWT.
It MUST NOT contain more than one JWT. It MUST NOT contain more than one JWT.
The following example demonstrates client authentication using a JWT The following example demonstrates client authentication using a JWT
during the presentation of an authorization code grant in an Access during the presentation of an authorization code grant in an access
Token Request (with extra line breaks for display purposes only): token request (with extra line breaks for display purposes only):
POST /token.oauth2 HTTP/1.1 POST /token.oauth2 HTTP/1.1
Host: as.example.com Host: as.example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code& grant_type=authorization_code&
code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo& code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
client-assertion-type%3Ajwt-bearer& client-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJSUzI1NiJ9. client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
eyJpc3Mi[...omitted for brevity...]. eyJpc3Mi[...omitted for brevity...].
cC4hiUPo[...omitted for brevity...] cC4hiUPo[...omitted for brevity...]
3. JWT Format and Processing Requirements 3. JWT Format and Processing Requirements
In order to issue an access token response as described in OAuth 2.0 In order to issue an access token response as described in OAuth 2.0
[RFC6749] or to rely on a JWT for client authentication, the [RFC6749] or to rely on a JWT for client authentication, the
authorization server MUST validate the JWT according to the criteria authorization server MUST validate the JWT according to the criteria
below. Application of additional restrictions and policy are at the below. Application of additional restrictions and policy are at the
discretion of the authorization server. discretion of the authorization server.
1. The JWT MUST contain an "iss" (issuer) claim that contains a 1. The JWT MUST contain an "iss" (issuer) claim that contains a
unique identifier for the entity that issued the JWT. In the unique identifier for the entity that issued the JWT. In the
absence of an application profile specifying otherwise, absence of an application profile specifying otherwise,
compliant applications MUST compare Issuer values using the compliant applications MUST compare issuer values using the
Simple String Comparison method defined in Section 6.2.1 of RFC Simple String Comparison method defined in Section 6.2.1 of RFC
3986 [RFC3986]. 3986 [RFC3986].
2. The JWT MUST contain a "sub" (subject) claim identifying the 2. The JWT MUST contain a "sub" (subject) claim identifying the
principal that is the subject of the JWT. Two cases need to be principal that is the subject of the JWT. Two cases need to be
differentiated: differentiated:
A. For the authorization grant, the subject typically A. For the authorization grant, the subject typically
identifies an authorized accessor for which the access token identifies an authorized accessor for which the access token
is being requested (i.e., the resource owner or an is being requested (i.e., the resource owner or an
skipping to change at page 6, line 31 skipping to change at page 6, line 31
user. user.
B. For client authentication, the subject MUST be the B. For client authentication, the subject MUST be the
"client_id" of the OAuth client. "client_id" of the OAuth client.
3. The JWT MUST contain an "aud" (audience) claim containing a 3. The JWT MUST contain an "aud" (audience) claim containing a
value that identifies the authorization server as an intended value that identifies the authorization server as an intended
audience. The token endpoint URL of the authorization server audience. The token endpoint URL of the authorization server
MAY be used as a value for an "aud" element to identify the MAY be used as a value for an "aud" element to identify the
authorization server as an intended audience of the JWT. The authorization server as an intended audience of the JWT. The
Authorization Server MUST reject any JWT that does not contain authorization server MUST reject any JWT that does not contain
its own identity as the intended audience In the absence of an its own identity as the intended audience. In the absence of an
application profile specifying otherwise, compliant applications application profile specifying otherwise, compliant applications
MUST compare the audience values using the Simple String MUST compare the audience values using the Simple String
Comparison method defined in Section 6.2.1 of RFC 3986 Comparison method defined in Section 6.2.1 of RFC 3986
[RFC3986]. As noted in Section 5, the precise strings to be [RFC3986]. As noted in Section 5, the precise strings to be
used as the audience for a given Authorization Server must be used as the audience for a given authorization server must be
configured out-of-band by the Authorization Server and the configured out of band by the authorization server and the
Issuer of the JWT. issuer of the JWT.
4. The JWT MUST contain an "exp" (expiration) claim that limits the 4. The JWT MUST contain an "exp" (expiration time) claim that
time window during which the JWT can be used. The authorization limits the time window during which the JWT can be used. The
server MUST reject any JWT with an expiration time that has authorization server MUST reject any JWT with an expiration time
passed, subject to allowable clock skew between systems. Note that has passed, subject to allowable clock skew between
that the authorization server may reject JWTs with an "exp" systems. Note that the authorization server may reject JWTs
claim value that is unreasonably far in the future. with an "exp" claim value that is unreasonably far in the
future.
5. The JWT MAY contain an "nbf" (not before) claim that identifies 5. The JWT MAY contain an "nbf" (not before) claim that identifies
the time before which the token MUST NOT be accepted for the time before which the token MUST NOT be accepted for
processing. processing.
6. The JWT MAY contain an "iat" (issued at) claim that identifies 6. The JWT MAY contain an "iat" (issued at) claim that identifies
the time at which the JWT was issued. Note that the the time at which the JWT was issued. Note that the
authorization server may reject JWTs with an "iat" claim value authorization server may reject JWTs with an "iat" claim value
that is unreasonably far in the past. that is unreasonably far in the past.
7. The JWT MAY contain a "jti" (JWT ID) claim that provides a 7. The JWT MAY contain a "jti" (JWT ID) claim that provides a
unique identifier for the token. The authorization server MAY unique identifier for the token. The authorization server MAY
ensure that JWTs are not replayed by maintaining the set of used ensure that JWTs are not replayed by maintaining the set of used
"jti" values for the length of time for which the JWT would be "jti" values for the length of time for which the JWT would be
considered valid based on the applicable "exp" instant. considered valid based on the applicable "exp" instant.
8. The JWT MAY contain other claims. 8. The JWT MAY contain other claims.
9. The JWT MUST be digitally signed or have a Message 9. The JWT MUST be digitally signed or have a Message
Authentication Code applied by the issuer. The authorization Authentication Code (MAC) applied by the issuer. The
server MUST reject JWTs with an invalid signature or Message authorization server MUST reject JWTs with an invalid signature
Authentication Code. or MAC.
10. The authorization server MUST reject a JWT that is not valid in 10. The authorization server MUST reject a JWT that is not valid in
all other respects per JSON Web Token (JWT) [JWT]. all other respects per "JSON Web Token (JWT)" [JWT].
3.1. Authorization Grant Processing 3.1. Authorization Grant Processing
JWT authorization grants may be used with or without client JWT authorization grants may be used with or without client
authentication or identification. Whether or not client authentication or identification. Whether or not client
authentication is needed in conjunction with a JWT authorization authentication is needed in conjunction with a JWT authorization
grant, as well as the supported types of client authentication, are grant, as well as the supported types of client authentication, are
policy decisions at the discretion of the authorization server. policy decisions at the discretion of the authorization server.
However, if client credentials are present in the request, the However, if client credentials are present in the request, the
authorization server MUST validate them. authorization server MUST validate them.
skipping to change at page 8, line 40 skipping to change at page 8, line 40
The example shows a JWT issued and signed by the system entity The example shows a JWT issued and signed by the system entity
identified as "https://jwt-idp.example.com". The subject of the JWT identified as "https://jwt-idp.example.com". The subject of the JWT
is identified by email address as "mike@example.com". The intended is identified by email address as "mike@example.com". The intended
audience of the JWT is "https://jwt-rp.example.net", which is an audience of the JWT is "https://jwt-rp.example.net", which is an
identifier with which the authorization server identifies itself. identifier with which the authorization server identifies itself.
The JWT is sent as part of an access token request to the The JWT is sent as part of an access token request to the
authorization server's token endpoint at "https://authz.example.net/ authorization server's token endpoint at "https://authz.example.net/
token.oauth2". token.oauth2".
Below is an example JSON object that could be encoded to produce the Below is an example JSON object that could be encoded to produce the
JWT Claims Object for a JWT: JWT Claims Set for a JWT:
{"iss":"https://jwt-idp.example.com", {"iss":"https://jwt-idp.example.com",
"sub":"mailto:mike@example.com", "sub":"mailto:mike@example.com",
"aud":"https://jwt-rp.example.net", "aud":"https://jwt-rp.example.net",
"nbf":1300815780, "nbf":1300815780,
"exp":1300819380, "exp":1300819380,
"http://claims.example.com/member":true} "http://claims.example.com/member":true}
The following example JSON object, used as the header of a JWT, The following example JSON object, used as the header of a JWT,
declares that the JWT is signed with the ECDSA P-256 SHA-256 declares that the JWT is signed with the Elliptic Curve Digital
algorithm. Signature Algorithm (ECDSA) P-256 SHA-256 using a key identified by
the "kid" value "16".
{"alg":"ES256"} {"alg":"ES256","kid":"16"}
To present the JWT with the claims and header shown in the previous To present the JWT with the claims and header shown in the previous
example as part of an access token request, for example, the client example as part of an access token request, for example, the client
might make the following HTTPS request (with extra line breaks for might make the following HTTPS request (with extra line breaks for
display purposes only): display purposes only):
POST /token.oauth2 HTTP/1.1 POST /token.oauth2 HTTP/1.1
Host: authz.example.net Host: authz.example.net
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiJ9. &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
eyJpc3Mi[...omitted for brevity...]. eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...] J9l-ZhwP[...omitted for brevity...]
5. Interoperability Considerations 5. Interoperability Considerations
Agreement between system entities regarding identifiers, keys, and Agreement between system entities regarding identifiers, keys, and
endpoints is required in order to achieve interoperable deployments endpoints is required in order to achieve interoperable deployments
of this profile. Specific items that require agreement are as of this profile. Specific items that require agreement are as
follows: values for the issuer and audience identifiers, the location follows: values for the issuer and audience identifiers, the location
of the token endpoint, the key used to apply and verify the digital of the token endpoint, the key used to apply and verify the digital
signature or Message Authentication Code over the JWT, one-time use signature or MAC over the JWT, one-time use restrictions on the JWT,
restrictions on the JWT, maximum JWT lifetime allowed, and the maximum JWT lifetime allowed, and the specific subject and claim
specific subject and claim requirements of the JWT. The exchange of requirements of the JWT. The exchange of such information is
such information is explicitly out of scope for this specification. explicitly out of scope for this specification. In some cases,
In some cases, additional profiles may be created that constrain or additional profiles may be created that constrain or prescribe these
prescribe these values or specify how they are to be exchanged. values or specify how they are to be exchanged. Examples of such
Examples of such profiles include the OAuth 2.0 Dynamic Client profiles include the OAuth 2.0 Dynamic Client Registration Core
Registration Core Protocol [I-D.ietf-oauth-dyn-reg], OpenID Connect Protocol [OAUTH-DYN-REG], OpenID Connect Dynamic Client Registration
Dynamic Client Registration 1.0 [OpenID.Registration], and OpenID 1.0 [OpenID.Registration], and OpenID Connect Discovery 1.0
Connect Discovery 1.0 [OpenID.Discovery]. [OpenID.Discovery].
The "RS256" algorithm, from [I-D.ietf-jose-json-web-algorithms], is a The "RS256" algorithm, from [JWA], is a mandatory-to-implement JSON
mandatory to implement JSON Web Signature algorithm for this profile. Web Signature algorithm for this profile.
6. Security Considerations 6. Security Considerations
The security considerations described within the Assertion Framework The security considerations described within the following
for OAuth 2.0 Client Authentication and Authorization Grants specifications are all applicable to this document: "Assertion
[I-D.ietf-oauth-assertions], The OAuth 2.0 Authorization Framework Framework for OAuth 2.0 Client Authentication and Authorization
[RFC6749], and the JSON Web Token (JWT) [JWT] specifications are all Grants" [RFC7521], "The OAuth 2.0 Authorization Framework" [RFC6749],
applicable to this document. and "JSON Web Token (JWT)" [JWT].
The specification does not mandate replay protection for the JWT The specification does not mandate replay protection for the JWT
usage for either the authorization grant or for client usage for either the authorization grant or for client
authentication. It is an optional feature, which implementations may authentication. It is an optional feature, which implementations may
employ at their own discretion. employ at their own discretion.
7. Privacy Considerations 7. Privacy Considerations
A JWT may contain privacy-sensitive information and, to prevent A JWT may contain privacy-sensitive information and, to prevent
disclosure of such information to unintended parties, should only be disclosure of such information to unintended parties, should only be
transmitted over encrypted channels, such as TLS. In cases where it transmitted over encrypted channels, such as Transport Layer Security
is desirable to prevent disclosure of certain information to the (TLS). In cases where it is desirable to prevent disclosure of
client, the JWT should be be encrypted to the authorization server. certain information to the client, the JWT should be encrypted to the
authorization server.
Deployments should determine the minimum amount of information Deployments should determine the minimum amount of information
necessary to complete the exchange and include only such claims in necessary to complete the exchange and include only such claims in
the JWT. In some cases, the "sub" (subject) claim can be a value the JWT. In some cases, the "sub" (subject) claim can be a value
representing an anonymous or pseudonymous user, as described in representing an anonymous or pseudonymous user, as described in
Section 6.3.1 of the Assertion Framework for OAuth 2.0 Client Section 6.3.1 of the OAuth Assertion Framework [RFC7521].
Authentication and Authorization Grants [I-D.ietf-oauth-assertions].
8. IANA Considerations 8. IANA Considerations
8.1. Sub-Namespace Registration of urn:ietf:params:oauth:grant- 8.1. Sub-Namespace Registration of
type:jwt-bearer urn:ietf:params:oauth:grant-type:jwt-bearer
This specification registers the value "grant-type:jwt-bearer" in the This section registers the value "grant-type:jwt-bearer" in the IANA
IANA urn:ietf:params:oauth registry established in An IETF URN Sub- "OAuth URI" registry established by "An IETF URN Sub-Namespace for
Namespace for OAuth [RFC6755]. OAuth" [RFC6755].
o URN: urn:ietf:params:oauth:grant-type:jwt-bearer o URN: urn:ietf:params:oauth:grant-type:jwt-bearer
o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0 o Common Name: JWT Bearer Token Grant Type Profile for OAuth 2.0
o Change Controller: IESG
o Specification Document: RFC 7523
o Change controller: IESG 8.2. Sub-Namespace Registration of
urn:ietf:params:oauth:client-assertion-type:jwt-bearer
o Specification Document: [[this document]]
8.2. Sub-Namespace Registration of urn:ietf:params:oauth:client-
assertion-type:jwt-bearer
This specification registers the value "client-assertion-type:jwt- This section registers the value "client-assertion-type:jwt-bearer"
bearer" in the IANA urn:ietf:params:oauth registry established in An in the IANA "OAuth URI" registry established by "An IETF URN Sub-
IETF URN Sub-Namespace for OAuth [RFC6755]. Namespace for OAuth" [RFC6755].
o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer o URN: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client o Common Name: JWT Bearer Token Profile for OAuth 2.0 Client
Authentication Authentication
o Change Controller: IESG
o Change controller: IESG o Specification Document: RFC 7523
o Specification Document: [[this document]]
9. References 9. References
9.1. Normative References 9.1. Normative References
[I-D.ietf-jose-json-web-algorithms] [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- DOI 10.17487/RFC7518, May 2015,
json-web-algorithms-36 (work in progress), October 2014. <http://www.rfc-editor.org/info/rfc7518>.
[I-D.ietf-oauth-assertions]
Campbell, B., Mortimore, C., Jones, M., and Y. Goland,
"Assertion Framework for OAuth 2.0 Client Authentication
and Authorization Grants", draft-ietf-oauth-assertions
(work in progress), October 2014.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
progress), October 2014. <http://www.rfc-editor.org/info/rfc7519>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. 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 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66,
3986, January 2005. RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
6749, October 2012. RFC 6749, DOI 10.17487/RFC6749, October 2012,
<http://www.rfc-editor.org/info/rfc6749>.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. 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 9.2. Informative References
[I-D.ietf-oauth-dyn-reg] [OAUTH-DYN-REG]
Richer, J., Jones, M., Bradley, J., Machulak, M., and P. Richer, J., Jones, M., Bradley, J., Machulak, M., and P.
Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
draft-ietf-oauth-dyn-reg-20 (work in progress), August Work in Progress, draft-ietf-oauth-dyn-reg-29, May 2015.
2014.
[I-D.ietf-oauth-saml2-bearer]
Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0
Profile for OAuth 2.0 Client Authentication and
Authorization Grants", draft-ietf-oauth-saml2-bearer (work
in progress), November 2014.
[OpenID.Discovery] [OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
Connect Discovery 1.0", February 2014. Connect Discovery 1.0 incorporating errata set 1",
November 2014, <http://openid.net/specs/
openid-connect-discovery-1_0.html>.
[OpenID.Registration] [OpenID.Registration]
Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
Dynamic Client Registration 1.0", February 2014. 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 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, October 2012. for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<http://www.rfc-editor.org/info/rfc6755>.
Appendix A. Acknowledgements
This profile was derived from SAML 2.0 Profile for OAuth 2.0 Client
Authentication and Authorization Grants [I-D.ietf-oauth-saml2-bearer]
by Brian Campbell and Chuck Mortimore.
Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]]
draft-ietf-oauth-jwt-bearer-12
o Fix typo per http://www.ietf.org/mail-archive/web/oauth/current/
msg13790.html
draft-ietf-oauth-jwt-bearer-11
o Changes/suggestions from IESG reviews.
draft-ietf-oauth-jwt-bearer-10
o Added Privacy Considerations section per AD review discussion
http://www.ietf.org/mail-archive/web/oauth/current/msg13148.html
and http://www.ietf.org/mail-archive/web/oauth/current/
msg13144.html
draft-ietf-oauth-jwt-bearer-09
o Clarified some text around the treatment of subject based on the
rough rough consensus from the thread staring at
http://www.ietf.org/mail-archive/web/oauth/current/msg12630.html
draft-ietf-oauth-jwt-bearer-08
o Updated references, including replacing references to RFC 4627
with RFC 7159.
o Clean up language around subject per http://www.ietf.org/mail-
archive/web/oauth/current/msg12250.html.
o As suggested in http://www.ietf.org/mail-
archive/web/oauth/current/msg12251.html stated that "In the
absence of an application profile specifying otherwise, compliant
applications MUST compare the audience values using the Simple
String Comparison method defined in Section 6.2.1 of RFC 3986."
o Added one-time use, maximum lifetime, and specific subject and
attribute requirements to Interoperability Considerations based on
http://www.ietf.org/mail-archive/web/oauth/current/msg12252.html.
o Remove "or its subject confirmation requirements cannot be met"
text.
o Reword security considerations and mention that replay protection
is not mandated based on http://www.ietf.org/mail-
archive/web/oauth/current/msg12259.html.
-06
o Stated that issuer and audience values SHOULD be compared using
the Simple String Comparison method defined in Section 6.2.1 of
RFC 3986 unless otherwise specified by the application.
-05
o Changed title from "JSON Web Token (JWT) Bearer Token Profiles for
OAuth 2.0" to "JSON Web Token (JWT) Profile for OAuth 2.0 Client
Authentication and Authorization Grants" to be more explicit about
the scope of the document per http://www.ietf.org/mail-
archive/web/oauth/current/msg11063.html.
o Numbered the list of processing rules.
o Smallish editorial cleanups to try and improve readability and
comprehensibility.
o Cleaner split out of the processing rules in cases where they
differ for client authentication and authorization grants.
o Clarified the parameters that are used/available for authorization
grants.
o Added Interoperability Considerations section.
o Added more explanatory context to the example in Section 4.
-04
o Changed the name of the "prn" claim to "sub" (subject) both to
more closely align with SAML name usage and to use a more
intuitive name.
o Added seriesInfo information to Internet Draft references.
-03
o Reference RFC 6749 and RFC 6755.
-02
o Add more text to intro explaining that an assertion/JWT grant type
can be used with or without client authentication/identification
and that client assertion/JWT authentication is nothing more than
an alternative way for a client to authenticate to the token
endpoint
o Add examples to Sections 2.1 and 2.2
o Update references
-01
o Tracked specification name changes: "The OAuth 2.0 Authorization
Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth
2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0".
o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security
draft-ietf-oauth-saml2-bearer-13. All changes were strictly Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0
editorial. Client Authentication and Authorization Grants", RFC 7522,
DOI 10.17487/RFC7522, May 2015,
<http://www.rfc-editor.org/info/rfc7522>.
-00 Acknowledgements
o Created the initial IETF draft based upon draft-jones-oauth-jwt- This profile was derived from "Security Assertion Markup Language
bearer-04 with no normative changes. (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and
Authorization Grants" [RFC7522], which has the same authors as this
document.
Authors' Addresses Authors' Addresses
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com EMail: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
Brian Campbell Brian Campbell
Ping Identity Ping Identity
Email: brian.d.campbell@gmail.com EMail: brian.d.campbell@gmail.com
Chuck Mortimore Chuck Mortimore
Salesforce Salesforce
Email: cmortimore@salesforce.com EMail: cmortimore@salesforce.com
 End of changes. 65 change blocks. 
306 lines changed or deleted 180 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/