draft-ietf-oauth-jwt-bearer-02.txt   draft-ietf-oauth-jwt-bearer-03.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: March 18, 2013 Ping Identity Expires: May 10, 2013 Ping Identity
C. Mortimore C. Mortimore
Salesforce Salesforce
September 14, 2012 November 6, 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-02 draft-ietf-oauth-jwt-bearer-03
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 March 18, 2013. This Internet-Draft will expire on May 10, 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
skipping to change at page 3, line 14 skipping to change at page 3, line 14
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.
The OAuth 2.0 Authorization Framework [I-D.ietf-oauth-v2] provides a The OAuth 2.0 Authorization Framework [RFC6749] provides a method for
method for making authenticated HTTP requests to a resource using an making authenticated HTTP requests to a resource using an access
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
skipping to change at page 4, line 28 skipping to change at page 4, line 28
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 OAuth 2.0 Authorization Framework
[I-D.ietf-oauth-v2], Assertion Framework for OAuth 2.0 [RFC6749], Assertion Framework for OAuth 2.0
[I-D.ietf-oauth-assertions], and JSON Web Token (JWT) [JWT]. [I-D.ietf-oauth-assertions], and JSON Web Token (JWT) [JWT].
2. HTTP Parameter Bindings for Transporting Assertions 2. HTTP Parameter Bindings for Transporting Assertions
The Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions] The Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions]
defines generic HTTP parameters for transporting Assertions (a.k.a. defines generic HTTP parameters for transporting Assertions (a.k.a.
Security Tokens) during interactions with a token endpoint. This Security Tokens) during interactions with a token endpoint. This
section defines the values of those parameters for use with JWT section defines the values of those parameters for use with JWT
Bearer Tokens. Bearer Tokens.
skipping to change at page 5, line 17 skipping to change at page 5, line 17
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=eyJhbGciOiJFUzI1NiJ9.
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 grant, use the To use a JWT Bearer Token for client authentication, 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 The following non-normative example demonstrates client
authentication using a JWT during the presentation of an authentication using a JWT during the presentation of an
skipping to change at page 5, line 46 skipping to change at page 5, line 46
code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo& code=vAZEIHjQTHuGgaSvyW9hO0RpusLzkvTOww3trZBxZpo&
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=eyJhbGciOiJSUzI1NiJ9.
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 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 [RFC6749] or to rely on a JWT for client
for client authentication, the authorization server MUST validate the authentication, the authorization server MUST validate the JWT
JWT according to the criteria below. Application of additional 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
unique identifier for the entity that issued the JWT. unique identifier for the entity that issued the JWT.
o The JWT MUST contain a "prn" (principal) claim identifying the o The JWT MUST contain a "prn" (principal) claim identifying the
subject of the transaction. The principal MAY identify the subject of the transaction. The principal MAY identify the
resource owner for whom the access token is being requested. For resource owner for whom the access token is being requested. For
client authentication, the principal MUST be the "client_id" of client authentication, the principal MUST be the "client_id" of
skipping to change at page 7, line 15 skipping to change at page 7, line 15
o The authorization server MUST verify that the JWT is valid in all o The authorization server MUST verify that the JWT is valid in all
other respects per JSON Web Token (JWT) [JWT]. other respects per JSON Web Token (JWT) [JWT].
3.1. Authorization Grant Processing 3.1. Authorization Grant Processing
If present, the authorization server MUST also validate the client If present, the authorization server MUST also validate the client
credentials. credentials.
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 [RFC6749]. The
[I-D.ietf-oauth-v2]. The value of the "error" parameter MUST be the value of the "error" parameter MUST be the "invalid_grant" error
"invalid_grant" error code. The authorization server MAY include code. The authorization server MAY include additional information
additional information regarding the reasons the JWT was considered regarding the reasons the JWT was considered invalid using the
invalid using the "error_description" or "error_uri" parameters. "error_description" or "error_uri" parameters.
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"error":"invalid_grant", "error":"invalid_grant",
"error_description":"Audience validation failed" "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 [RFC6749]. The value of
value of the "error" parameter MUST be the "invalid_client" error the "error" parameter MUST be the "invalid_client" error code. The
code. The authorization server MAY include additional information authorization server MAY include additional information regarding the
regarding the reasons the JWT was considered invalid using the reasons the JWT was considered invalid using the "error_description"
"error_description" or "error_uri" parameters. 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", {"iss":"https://jwt-idp.example.com",
skipping to change at page 8, line 38 skipping to change at page 8, line 38
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=eyJhbGciOiJFUzI1NiJ9.
eyJpc3Mi[...omitted for brevity...]. eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP[...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 [RFC6749], the Assertion
Assertion Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and Framework for OAuth 2.0 [I-D.ietf-oauth-assertions], and the JSON Web
the JSON Web Token (JWT) [JWT] specification. Token (JWT) [JWT] specification.
6. IANA Considerations 6. IANA Considerations
6.1. Sub-Namespace Registration of 6.1. Sub-Namespace Registration of
urn:ietf:params:oauth:grant-type:jwt-bearer urn:ietf:params:oauth:grant-type:jwt-bearer
This specification registers the value "grant-type:jwt-bearer" in the This specification registers the value "grant-type:jwt-bearer" in the
IANA urn:ietf:params:oauth registry established in An IETF URN Sub- IANA urn:ietf:params:oauth registry established in An IETF URN Sub-
Namespace for OAuth [I-D.ietf-oauth-urn-sub-ns]. Namespace for 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: IETF o Change controller: IETF
o Specification Document: [[this document]] o Specification Document: [[this document]]
6.2. Sub-Namespace Registration of 6.2. Sub-Namespace Registration of
urn:ietf:params:oauth:client-assertion-type:jwt-bearer urn:ietf:params:oauth:client-assertion-type:jwt-bearer
This specification registers the value This specification registers the value
"client-assertion-type:jwt-bearer" in the IANA urn:ietf:params:oauth "client-assertion-type:jwt-bearer" in the IANA urn:ietf:params:oauth
registry established in An IETF URN Sub-Namespace for OAuth registry established in An IETF URN Sub-Namespace for OAuth
[I-D.ietf-oauth-urn-sub-ns]. [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: IETF o Change controller: IETF
o Specification Document: [[this document]] o Specification Document: [[this document]]
7. References 7. References
7.1. Normative References 7.1. Normative References
[I-D.ietf-oauth-assertions] [I-D.ietf-oauth-assertions]
Campbell, B., Mortimore, C., Jones, M., and Y. Goland, Campbell, B., Mortimore, C., Jones, M., and Y. Goland,
"Assertion Framework for OAuth 2.0", "Assertion Framework for OAuth 2.0",
draft-ietf-oauth-assertions-04 (work in progress), draft-ietf-oauth-assertions-06 (work in progress),
July 2012. September 2012.
[I-D.ietf-oauth-urn-sub-ns]
Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", draft-ietf-oauth-urn-sub-ns-05 (work in
progress), June 2012.
[I-D.ietf-oauth-v2]
Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth
2.0 Authorization Framework", draft-ietf-oauth-v2-28 (work
in progress), June 2012.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", July 2012. (JWT)", November 2012.
[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, March 1997.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
RFC 6749, October 2012.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, October 2012.
7.2. Informative References 7.2. Informative References
[I-D.ietf-oauth-saml2-bearer] [I-D.ietf-oauth-saml2-bearer]
Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion
Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-13 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-14
(work in progress), July 2012. (work in progress), September 2012.
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 ]]
-03
o Reference RFC 6749 and RFC 6755.
-02 -02
o Add more text to intro explaining that an assertion/JWT grant type o Add more text to intro explaining that an assertion/JWT grant type
can be used with or without client authentication/identification can be used with or without client authentication/identification
and that client assertion/JWT authentication is nothing more than and that client assertion/JWT authentication is nothing more than
an alternative way for a client to authenticate to the token an alternative way for a client to authenticate to the token
endpoint endpoint
o Add examples to Sections 2.1 and 2.2 o Add examples to Sections 2.1 and 2.2
 End of changes. 18 change blocks. 
42 lines changed or deleted 42 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/