Network Working Group M. Jones
Internet-Draft Microsoft
Intended status: Standards Track March 28, 2011
Expires: September 29, 2011
JSON Web Token (JWT) Bearer Profile for OAuth 2.0
draft-jones-oauth-jwt-bearer-00
Abstract
This specification defines the use of a JSON Web Token (JWT) bearer
token as a means of requesting an OAuth 2.0 access token.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
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
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 29, 2011.
Copyright Notice
Copyright (c) 2011 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) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Jones Expires September 29, 2011 [Page 1]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3
2. JWT Access Token Request . . . . . . . . . . . . . . . . . . . 3
2.1. Client Requests Access Token . . . . . . . . . . . . . . . 4
2.2. JWT Content and Processing Requirements . . . . . . . . . . 4
2.3. Error Response . . . . . . . . . . . . . . . . . . . . . . 5
2.4. Example (non-normative) . . . . . . . . . . . . . . . . . . 6
3. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
4.1. OAuth Parameters Registration . . . . . . . . . . . . . . . 7
4.1.1. The "jwt" OAuth Parameter . . . . . . . . . . . . . . . 7
5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Normative References . . . . . . . . . . . . . . . . . . . 7
5.2. Informative References . . . . . . . . . . . . . . . . . . 8
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8
Appendix B. Document History . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
Jones Expires September 29, 2011 [Page 2]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
1. Introduction
JSON Web Token (JWT) [JWT] is a JSON-based security token encoding
that enables identity and security information to be shared across
security domains. JWTs utilize JSON data structures, as defined in
RFC 4627 [RFC4627].
The OAuth 2.0 Authorization Protocol [I-D.ietf-oauth-v2] provides a
method for making authenticated HTTP requests to a resource using an
access token. Access tokens are issued to third-party clients by an
authorization server (AS) with the (sometimes implicit) approval of
the resource owner. In OAuth, an authorization grant is an abstract
term used to describe intermediate credentials that represent the
resource owner authorization. An authorization grant is used by the
client to obtain an access token.
Several authorization grant types are defined to support a wide range
of client types and user experiences. OAuth also allows for the
definition of new extension grant types to support additional clients
or to provide a bridge between OAuth and other trust frameworks.
This specification defines an extension grant type that profiles the
use of a JSON Web Token (JWT) in requesting an OAuth 2.0 access
token.
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 [RFC2119].
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
1.2. Terminology
All terms are as defined in [I-D.ietf-oauth-v2] and [JWT].
2. JWT Access Token Request
A JSON Web Token (JWT) bearer token can be used to request an access
token when a client wishes to utilize an existing trust relationship,
expressed through the semantics of the JWT, without a direct user
approval step at the authorization server.
The process by which the client obtains the JWT, prior to exchanging
it with the authorization server, is out of scope.
Jones Expires September 29, 2011 [Page 3]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
+--------+ +---------------+
| | | |
| |--(A)-- JSON Web Token (JWT) ->| Authorization |
| Client | | Server |
| |<-(B)----- Access Token -------| |
| | | |
+--------+ +---------------+
Figure 1: Access Token Request using JWT Bearer Token
The request/response flow illustrated in Figure 1 includes the
following steps:
(A) The client sends an access token request to the authorization
server that includes a JWT bearer token and a grant_type of
"http://oauth.net/grant_type/jwt/1.0/bearer".
(B) The authorization server validates the JWT per the processing
rules defined in the JWT specification and in this specification
and issues an access token.
2.1. Client Requests Access Token
The client includes the JWT in the access token request, the core
details of which are defined in OAuth [I-D.ietf-oauth-v2], by
specifying "http://oauth.net/grant_type/jwt/1.0/bearer" as the
absolute URI value of the "grant_type" parameter and by adding the
following parameter:
jwt
REQUIRED. The value of the "jwt" parameter MUST be a single
JWT that is represented using the Compact Serialization.
scope
OPTIONAL. The scope of the access request expressed as a list
of space-delimited strings. The value is defined by the
authorization server. If the value contains multiple space-
delimited strings, their order does not matter, and each string
adds an additional access range to the requested scope.
2.2. JWT Content and Processing Requirements
Prior to issuing an access token response as described in
[I-D.ietf-oauth-v2], the authorization server MUST validate the JWT
according to the criteria below. If present, the authorization
server MUST also validate the client credentials. Application of
additional restrictions and policy are at the discretion of the
authorization server.
Jones Expires September 29, 2011 [Page 4]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
o The JWT MUST contain an "iss" (issuer) claim that contains a
unique identifier for the entity that issued the JWT.
o The JWT MUST contain a "prn" (principal) claim. The principal
MUST identify the resource owner for whom the access token is
being requested.
o The JWT MUST contain an "aud" (audience) claim containing a URI
reference that identifies the authorization server as the intended
audience. The authorization server MUST verify that it is an
intended audience for the JWT.
o The JWT MUST contain an "exp" (expiration) claim that limits the
time window during which the JWT can be used. The authorization
server MUST verify that the expiration time has not passed,
subject to allowable clock skew between systems. The
authorization server MAY reject JWTs with an "exp" claim value
that is unreasonably far in the future.
o The JWT MAY contain an "iat" (issued at) claim containing the UTC
time at which the JWT was issued. This time is represented as an
"IntDate", as defined by [JWT].
o The JWT MAY contain other claims.
o The JWT MUST be digitally signed by the issuer in the manner
described in the JWT specification and the authorization server
MUST verify the signature.
o The authorization server MUST verify that the JWT is valid in all
other respects per [JWT].
2.3. Error Response
If the JWT is not valid or has expired, the authorization server MUST
construct an error response as defined in [I-D.ietf-oauth-v2]. The
value of the error parameter MUST be the "invalid_grant" error code.
The authorization server MAY include additional information regarding
the reasons the JWT was considered invalid using the
"error_description" or "error_uri" parameters.
Jones Expires September 29, 2011 [Page 5]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error":"invalid_grant",
"error_description":"Audience validation failed"
}
2.4. Example (non-normative)
Though non-normative, the following examples illustrate what a
conforming JWT and access token request would look like.
Below is an example JSON object that could be encoded to produce the
JWT Claims Object for a JWT:
{"iss":"https://jwt-idp.example.com",
"prn":"mailto:mike@example.com",
"aud":"https://jwt-rp.example.net",
"iat":1300815780,
"exp":1300819380,
"http://claims.example.com/member":true}
Figure 2: Example JWT Claims Object
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
algorithm.
{"alg":"ES256"}
Figure 3: Example JWT Header Object
To present a JWT with the claims and header shown above as part of an
access token request, for example, the client might make the
following HTTPS request (line breaks are for display purposes only):
POST /token.oauth2 HTTP/1.1
Host: authz.example.net
Content-Type: application/x-www-form-urlencoded
grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fjwt%2F1.0%2Fbearer&
jwt=eyJhbGciOiJFUzI1NiJ9.eyJpc3Mi[...omitted for brevity...].
J9l-ZhwP_2n[...omitted for brevity...]
Figure 4: Example Request
Jones Expires September 29, 2011 [Page 6]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
3. Security Considerations
Authorization servers SHOULD issue access tokens with a limited
lifetime and require clients to refresh them by requesting a new
access token using the same JWT, if it is still valid, or with a new
JWT. The authorization server SHOULD NOT issue a refresh token.
4. IANA Considerations
4.1. OAuth Parameters Registration
This specification registers the following parameters in the OAuth
Parameters Registry established by [I-D.ietf-oauth-v2].
4.1.1. The "jwt" OAuth Parameter
Parameter name: jwt
Parameter usage location: token request
Change controller: IETF
Specification document(s): [[ this document ]]
Related information: None
5. References
5.1. Normative References
[I-D.ietf-oauth-v2]
Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth
2.0 Authorization Protocol", draft-ietf-oauth-v2-13 (work
in progress), February 2011.
[JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer,
J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)",
March 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
Jones Expires September 29, 2011 [Page 7]
Internet-Draft JWT Bearer Profile for OAuth 2.0 March 2011
5.2. Informative References
[I-D.ietf-oauth-saml2-bearer]
Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion
Grant Type Profile for OAuth 2.0",
draft-ietf-oauth-saml2-bearer-03 (work in progress),
February 2011.
Appendix A. Acknowledgements
This profile was derived from the SAML2 Bearer Assertion Grant Type
Profile for OAuth 2.0 [I-D.ietf-oauth-saml2-bearer] by Brian Campbell
and Chuck Mortimore.
Appendix B. Document History
[[ to be removed by RFC editor before publication as an RFC ]]
-00
o Initial draft.
Author's Address
Michael B. Jones
Microsoft
Email: mbj@microsoft.com
URI: http://self-issued.info/
Jones Expires September 29, 2011 [Page 8]