[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 draft-ietf-oauth-jwt-bearer

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]


Html markup produced by rfcmarkup 1.126, available from https://tools.ietf.org/tools/rfcmarkup/