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]