One document matched: draft-jones-oauth-jwt-bearer-00.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<rfc category='std' ipr='trust200902' docName='draft-jones-oauth-jwt-bearer-00'>
  <?rfc strict='yes' ?>
  <?rfc toc='yes' ?>
  <?rfc tocdepth='3' ?>
  <?rfc symrefs='yes' ?>
  <?rfc sortrefs='yes' ?>
  <?rfc compact='yes' ?>
  <?rfc subcompact='no' ?>

  <front>
    <title abbrev='JWT Bearer Profile for OAuth 2.0'>JSON Web Token (JWT) Bearer Profile for OAuth 2.0</title>

    <author fullname="Michael B. Jones" surname="Jones" initials="M.B."> <!-- role="editor" -->
      <organization>Microsoft</organization>
      <address>
        <email>mbj@microsoft.com</email>
        <uri>http://self-issued.info/</uri>
      </address>
    </author>

    <date year="2011" month="March" day="28" />

    <abstract>
      <t>
	This specification defines the use of a JSON Web Token (JWT)
	bearer token as a means of requesting an OAuth 2.0 access
	token.
      </t>
    </abstract>
  </front>

  <middle>

    <section title='Introduction'>
      <t>
	JSON Web Token (JWT) <xref target="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
	<xref target="RFC4627">RFC 4627</xref>.
      </t>
      <t>
	The OAuth 2.0 Authorization Protocol <xref
	target="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.
      </t>
      <t>
	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.
      </t>
      <t>
	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.
      </t>

      <section title='Notational Conventions'>
        <t>
          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 <xref target='RFC2119' />.
        </t>
        <t>
          Unless otherwise noted, all the protocol parameter names and values are case sensitive.
        </t>
      </section>

      <section title='Terminology'>
        <t>
          All terms are as defined in <xref target="I-D.ietf-oauth-v2"
          /> and <xref target="JWT" />.
        </t>
      </section>
    </section>

    <section title='JWT Access Token Request'>
      <t>
	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.
      </t>
      <t>
	The process by which the client obtains the JWT, prior to
	exchanging it with the authorization server, is out of scope.
      </t>
      <figure title='Access Token Request using JWT Bearer Token' anchor='Figure 1'>
	<artwork>
<![CDATA[+--------+                               +---------------+
|        |                               |               |
|        |--(A)-- JSON Web Token (JWT) ->| Authorization |
| Client |                               |     Server    |
|        |<-(B)----- Access Token -------|               |
|        |                               |               |
+--------+                               +---------------+]]>
	</artwork>
      </figure>
      <t>
	The request/response flow illustrated in <xref
        target='Figure 1' /> includes the following steps:
	<list>
	  <t>
	    (A) The client sends an access token request to the
	    authorization server that includes a JWT bearer token and a grant_type
	    of <spanx style="verb">http://oauth.net/grant_type/jwt/1.0/bearer</spanx>.
	  </t>
	  <t>
	    (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.
	  </t>
	</list>
      </t>

      <section title="Client Requests Access Token">
	<t>
	  The client includes the JWT in the access token request, the
	  core details of which are defined in OAuth <xref
	  target="I-D.ietf-oauth-v2" />, by specifying
	  <spanx style="verb">http://oauth.net/grant_type/jwt/1.0/bearer</spanx> as the absolute
	  URI value of the <spanx style="verb">grant_type</spanx> parameter and by adding the
	  following parameter:
	</t>
	<t>
	  <list style='hanging' hangIndent='6'>
	    <t hangText='jwt'>
	      <vspace />
	      REQUIRED.  The value of the <spanx
	      style="verb">jwt</spanx> parameter MUST be a single JWT
	      that is represented using the Compact Serialization.
	    </t>
	    <t hangText='scope'>
	      <vspace />
	      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.
	    </t>
	  </list>
	</t>
      </section>

      <section title="JWT Content and Processing Requirements">
	<t>
	  Prior to issuing an access token response as described in
	  <xref target="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.
	</t>
	<t>
	  <list style="symbols">
	    <t>
	      The JWT MUST contain an <spanx style="verb">iss</spanx>
	      (issuer) claim that contains a unique identifier for the
	      entity that issued the JWT.
	    </t>
	    <t>
	      The JWT MUST contain a <spanx style="verb">prn</spanx>
	      (principal) claim.  The principal MUST identify the
	      resource owner for whom the access token is being
	      requested.
	    </t>
	    <t>
	      The JWT MUST contain an <spanx style="verb">aud</spanx>
	      (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.
	    </t>
	    <t>
	      The JWT MUST contain an <spanx style="verb">exp</spanx>
	      (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 <spanx
	      style="verb">exp</spanx> claim value that is
	      unreasonably far in the future.
	    </t>
	    <t>
	      The JWT MAY contain an <spanx style="verb">iat</spanx>
	      (issued at) claim containing the UTC time at which the
	      JWT was issued.  This time is represented as an <spanx
	      style="verb">IntDate</spanx>, as defined by <xref
	      target="JWT" />.
	    </t>
	    <t>
	      The JWT MAY contain other claims.
	    </t>
	    <t>
	      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.
	    </t>
	    <t>
	      The authorization server MUST verify that the JWT is
	      valid in all other respects per <xref
	      target="JWT" />.
	    </t>
	  </list>
	</t>
      </section>

      <section title="Error Response">
	<t>
	  If the JWT is not valid or has expired, the authorization
	  server MUST construct an error response as defined in <xref
	  target="I-D.ietf-oauth-v2" />.  The value of the error
	  parameter MUST be the <spanx
	  style="verb">invalid_grant</spanx> error code.  The
	  authorization server MAY include additional information
	  regarding the reasons the JWT was considered invalid using
	  the <spanx style="verb">error_description</spanx> or <spanx
	  style="verb">error_uri</spanx> parameters.
	</t>
	<figure>
	  <preamble>
	    For example:
	  </preamble>
	  <artwork>
<![CDATA[HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error":"invalid_grant",
  "error_description":"Audience validation failed"
}]]>
	  </artwork>
	</figure>
      </section>

      <section title="Example (non-normative)">
	<t>
	  Though non-normative, the following examples illustrate what
	  a conforming JWT and access token request would look like.
	</t>
	<figure title="Example JWT Claims Object" anchor="Figure 2">
	  <preamble>
	    Below is an example JSON object that could be encoded to
	    produce the JWT Claims Object for a JWT:
	  </preamble>
	  <artwork><![CDATA[{"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}]]></artwork>
	</figure>
	<figure title="Example JWT Header Object" anchor="Figure 3">
	  <preamble>
	    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.
	  </preamble>
	  <artwork><![CDATA[{"alg":"ES256"}]]></artwork>
	</figure>
	<figure title="Example Request" anchor="Figure 4">
	  <preamble>
	    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):
	  </preamble>
	  <artwork>
<![CDATA[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...]]]>
	  </artwork>
	</figure>
      </section>
    </section>

    <section title='Security Considerations' anchor="sec-con">
      <t>
	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.
      </t>
    </section>

    <section title='IANA Considerations'>   

      <section title='OAuth Parameters Registration'>
        <t>
          This specification registers the following parameters in the OAuth Parameters Registry
          established by <xref target="I-D.ietf-oauth-v2" />.
        </t>

        <section title='The "jwt" OAuth Parameter'>
          <t>
            <list style='hanging'>
              <t hangText='Parameter name:'>
                jwt
              </t>
              <t hangText='Parameter usage location:'>
                token request
              </t>
              <t hangText='Change controller:'>
                IETF
              </t>
              <t hangText='Specification document(s):'>
                [[ this document ]]
              </t>
              <t hangText='Related information:'>
                None
              </t>
            </list>
          </t>
        </section>

      </section>

    </section> 

  </middle>

  <back>

    <references title='Normative References'>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml' ?>
      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-v2-13.xml' ?>

      <reference anchor="JWT">
        <front>
          <title>JSON Web Token (JWT)</title>

	  <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
	    <organization>Microsoft</organization>
	    <address>
	      <email>mbj@microsoft.com</email>
	      <uri>http://self-issued.info/</uri>
	    </address>
	  </author>

	  <author fullname="Dirk Balfanz" initials="D." surname="Balfanz">
	    <organization>Google</organization>
	    <address>
	      <email>balfanz@google.com</email>
	    </address>
	  </author>

	  <author fullname="John Bradley" initials="J." surname="Bradley">
	    <organization>independent</organization>
	    <address>
	      <email>ve7jtb@ve7jtb.com</email>
	    </address>
	  </author>

	  <author fullname="Yaron Y. Goland" initials="Y.Y." surname="Goland">
	    <organization>Microsoft</organization>
	    <address>
	      <email>yarong@microsoft.com</email>
	    </address>
	  </author>

	  <author fullname="John Panzer" initials="J." surname="Panzer">
	    <organization>Google</organization>
	    <address>
	      <email>jpanzer@google.com</email>
	    </address>
	  </author>

	  <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
	    <organization>Nomura Research Institute</organization>
	    <address>
	      <email>n-sakimura@nri.co.jp</email>
	    </address>
	  </author>

	  <author fullname="Paul Tarjan" initials="P." surname="Tarjan">
	    <organization>Facebook</organization>
	    <address>
	      <email>pt@fb.com</email>
	    </address>
	  </author>

	  <date day="28" month="March" year="2011" />
        </front>
        <format target="http://self-issued.info/docs/draft-jones-json-web-token.html" type="HTML" />
      </reference>

    </references>

    <references title="Informative References">

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-saml2-bearer-03.xml' ?>

    </references> 

    <section title='Acknowledgements'>
      <t>
	This profile was derived from the SAML2 Bearer Assertion Grant
	Type Profile for OAuth 2.0 <xref
	target="I-D.ietf-oauth-saml2-bearer" /> by Brian
	Campbell and Chuck Mortimore.
      </t>
    </section>

    <section title='Document History'>
      <t>
        [[ to be removed by RFC editor before publication as an RFC ]]
      </t>
      <t>
        -00
        <list style='symbols'>
          <t>
            Initial draft.
          </t>
        </list>
      </t>
    </section>     

  </back>

</rfc>