draft-ietf-oauth-jwt-bearer-01.txt   draft-ietf-oauth-jwt-bearer-02.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track B. Campbell Intended status: Standards Track B. Campbell
Expires: January 7, 2013 Ping Identity Expires: March 18, 2013 Ping Identity
C. Mortimore C. Mortimore
Salesforce Salesforce
July 6, 2012 September 14, 2012
JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0 JSON Web Token (JWT) Bearer Token Profiles for OAuth 2.0
draft-ietf-oauth-jwt-bearer-01 draft-ietf-oauth-jwt-bearer-02
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 use as a means of client authentication.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 7, 2013. This Internet-Draft will expire on March 18, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. HTTP Parameter Bindings for Transporting Assertions . . . . . . 4 2. HTTP Parameter Bindings for Transporting Assertions . . . . . 4
2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4 2.1. Using JWTs as Authorization Grants . . . . . . . . . . . . 4
2.2. Using JWTs for Client Authentication . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . 6 3.1. Authorization Grant Processing . . . . . . . . . . . . . . 7
3.2. Client Authentication Processing . . . . . . . . . . . . . 6 3.2. Client Authentication Processing . . . . . . . . . . . . . 7
4. Authorization Grant Example . . . . . . . . . . . . . . . . . . 6 4. Authorization Grant Example . . . . . . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6.1. Sub-Namespace Registration of 6.1. Sub-Namespace Registration of
urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . . 7 urn:ietf:params:oauth:grant-type:jwt-bearer . . . . . . . 8
6.2. Sub-Namespace Registration of 6.2. Sub-Namespace Registration of
urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 8 urn:ietf:params:oauth:client-assertion-type:jwt-bearer . . 9
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . . 9
7.2. Informative References . . . . . . . . . . . . . . . . . . 9 7.2. Informative References . . . . . . . . . . . . . . . . . . 10
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
Appendix B. Document History . . . . . . . . . . . . . . . . . . . 9 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON) JSON Web Token (JWT) [JWT] is a JavaScript Object Notation (JSON)
[RFC4627] based security token encoding that enables identity and [RFC4627] based security token encoding that enables identity and
security information to be shared across security domains. A security information to be shared across security domains. A
security token is generally issued by an identity provider and security token is generally issued by an identity provider and
consumed by a relying party that relies on its content to identify consumed by a relying party that relies on its content to identify
the token's subject for security related purposes. the token's subject for security related purposes.
skipping to change at page 3, line 48 skipping to change at page 3, line 48
intentionally similar, though not identical, to those in the closely intentionally similar, though not identical, to those in the closely
related SAML 2.0 Bearer Assertion Profiles for OAuth 2.0 related SAML 2.0 Bearer Assertion Profiles for OAuth 2.0
[I-D.ietf-oauth-saml2-bearer]. [I-D.ietf-oauth-saml2-bearer].
This document defines how a JSON Web Token (JWT) Bearer Token can be This document defines how a JSON Web Token (JWT) Bearer Token can be
used to request an access token when a client wishes to utilize an used to request an access token when a client wishes to utilize an
existing trust relationship, expressed through the semantics of (and existing trust relationship, expressed through the semantics of (and
digital signature calculated over) the JWT, without a direct user digital signature calculated over) the JWT, without a direct user
approval step at the authorization server. It also defines how a JWT approval step at the authorization server. It also defines how a JWT
can be used as a client authentication mechanism. The use of a can be used as a client authentication mechanism. The use of a
security token for client authentication is orthogonal and separable security token for client authentication is orthogonal to and
from using a security token as an authorization grant and the two can separable from using a security token as an authorization grant.
be used either in combination or in isolation. They can be used either in combination or separately. Client
authentication using a JWT is nothing more than an alternative way
for a client to authenticate to the token endpoint and must be used
in conjunction with some grant type to form a complete and meaningful
protocol request. JWT authorization grants may be used with or
without client authentication or identification. Whether or not
client authentication is needed in conjunction with a JWT
authorization grant, as well as the supported types of client
authentication, are policy decisions at the discretion of the
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].
skipping to change at page 4, line 40 skipping to change at page 4, line 49
2.1. Using JWTs as Authorization Grants 2.1. Using JWTs as Authorization Grants
To use a JWT Bearer Token as an authorization grant, use the To use a JWT Bearer Token as an authorization grant, use the
following parameter values and encodings. following parameter values and encodings.
The value of the "grant_type" parameter MUST be The value of the "grant_type" parameter MUST be
"urn:ietf:params:oauth:grant-type:jwt-bearer". "urn:ietf:params:oauth:grant-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 following non-normative example demonstrates an Access Token
Request with a JWT as an authorization grant (with extra line breaks
for display purposes only):
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=eyJhbGciOiJFUzI1NiJ9.
eyJpc3Mi[...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 grant, use the To use a JWT Bearer Token for client authentication grant, use the
following parameter values and encodings. following parameter values and encodings.
The value of the "client_assertion_type" parameter MUST be The value of the "client_assertion_type" parameter MUST be
"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 MUST contain a single The value of the "client_assertion" parameter MUST contain a single
JWT. JWT.
The following non-normative example demonstrates client
authentication using a JWT during the presentation of an
authorization code grant in an Access Token Request (with extra line
breaks for display purposes only):
POST /token.oauth2 HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
client-assertion-type%3Ajwt-bearer&
client_assertion=eyJhbGciOiJSUzI1NiJ9.
eyJpc3Mi[...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 The OAuth In order to issue an access token response as described in The OAuth
2.0 Authorization Framework [I-D.ietf-oauth-v2] or to rely on a JWT 2.0 Authorization Framework [I-D.ietf-oauth-v2] or to rely on a JWT
for client authentication, the authorization server MUST validate the for client authentication, the authorization server MUST validate the
JWT according to the criteria below. Application of additional JWT according to the criteria below. Application of additional
restrictions and policy are at the discretion of the authorization restrictions and policy are at the discretion of the authorization
server. server.
o The JWT MUST contain an "iss" (issuer) claim that contains a o The JWT MUST contain an "iss" (issuer) claim that contains a
skipping to change at page 6, line 29 skipping to change at page 7, line 22
If the JWT is not valid, or the current time is not within the If the JWT is not valid, or the current time is not within the
token's valid time window for use, the authorization server MUST token's valid time window for use, the authorization server MUST
construct an error response as defined in OAuth 2.0 construct an error response as defined in OAuth 2.0
[I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the [I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the
"invalid_grant" error code. The authorization server MAY include "invalid_grant" error code. The authorization server MAY include
additional information regarding the reasons the JWT was considered additional information regarding the reasons the JWT was considered
invalid using the "error_description" or "error_uri" parameters. invalid using the "error_description" or "error_uri" parameters.
For example: For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{ HTTP/1.1 400 Bad Request
"error":"invalid_grant", Content-Type: application/json
"error_description":"Audience validation failed" Cache-Control: no-store
}
{
"error":"invalid_grant",
"error_description":"Audience validation failed"
}
3.2. Client Authentication Processing 3.2. Client Authentication Processing
If the client JWT is not valid, or its subject confirmation If the client JWT is not valid, or its subject confirmation
requirements cannot be met, the authorization server MUST construct requirements cannot be met, the authorization server MUST construct
an error response as defined in OAuth 2.0 [I-D.ietf-oauth-v2]. The an error response as defined in OAuth 2.0 [I-D.ietf-oauth-v2]. The
value of the "error" parameter MUST be the "invalid_client" error value of the "error" parameter MUST be the "invalid_client" error
code. The authorization server MAY include additional information code. The authorization server MAY include additional information
regarding the reasons the JWT was considered invalid using the regarding the reasons the JWT was considered invalid using the
"error_description" or "error_uri" parameters. "error_description" or "error_uri" parameters.
4. Authorization Grant Example 4. Authorization Grant Example
Though non-normative, the following examples illustrate what a Though non-normative, the following examples illustrate what a
conforming JWT and access token request would look like. conforming JWT and access token request would look like.
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 Object for a JWT:
{"iss":"https://jwt-idp.example.com",
"prn":"mailto:mike@example.com", {"iss":"https://jwt-idp.example.com",
"aud":"https://jwt-rp.example.net", "prn":"mailto:mike@example.com",
"nbf":1300815780, "aud":"https://jwt-rp.example.net",
"exp":1300819380, "nbf":1300815780,
"http://claims.example.com/member":true} "exp":1300819380,
"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 ECDSA P-256 SHA-256
algorithm. algorithm.
{"alg":"ES256"}
{"alg":"ES256"}
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 line breaks for display might make the following HTTPS request (with extra line breaks for
purposes only): display purposes only):
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 POST /token.oauth2 HTTP/1.1
&assertion=eyJhbGciOiJFUzI1NiJ9. Host: authz.example.net
eyJpc3Mi[...omitted for brevity...]. Content-Type: application/x-www-form-urlencoded
J9l-ZhwP_2n[...omitted for brevity...]
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiJ9.
eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...omitted for brevity...]
5. Security Considerations 5. Security Considerations
No additional security considerations apply beyond those described No additional security considerations apply beyond those described
within The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2], the within The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2], the
Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and
the JSON Web Token (JWT) [JWT] specification. the JSON Web Token (JWT) [JWT] specification.
6. IANA Considerations 6. IANA Considerations
skipping to change at page 9, line 28 skipping to change at page 10, line 28
Appendix A. Acknowledgements Appendix A. Acknowledgements
This profile was derived from SAML 2.0 Bearer Assertion Profiles for This profile was derived from SAML 2.0 Bearer Assertion Profiles for
OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell and Chuck
Mortimore. Mortimore.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-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 -01
o Tracked specification name changes: "The OAuth 2.0 Authorization o Tracked specification name changes: "The OAuth 2.0 Authorization
Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth Protocol" to "The OAuth 2.0 Authorization Framework" and "OAuth
2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0". 2.0 Assertion Profile" to "Assertion Framework for OAuth 2.0".
o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and o Merged in changes between draft-ietf-oauth-saml2-bearer-11 and
draft-ietf-oauth-saml2-bearer-13. All changes were strictly draft-ietf-oauth-saml2-bearer-13. All changes were strictly
editorial. editorial.
 End of changes. 17 change blocks. 
50 lines changed or deleted 105 lines changed or added

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