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

Versions: 00

Network Working Group                                    J. Bradley, Ed.
Internet-Draft                                                      Ping
Intended status: Experimental                               May 04, 2014
Expires: November 5, 2014

       Encoding claims in the OAuth 2 state paramater using a JWT


   This draft provides a method for a client to encode one or more
   elements encoding information about the session into the OAuth 2
   "state" paramater.

Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in RFC 2119 [RFC2119].

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 November 5, 2014.

Copyright Notice

   Copyright (c) 2014 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

Bradley                 Expires November 5, 2014                [Page 1]

Internet-Draft              Abbreviated-Title                   May 2014

   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  The state JSON Web Token claims . . . . . . . . . . . . . . .   3
   3.  Validating the state paramater  . . . . . . . . . . . . . . .   4
   4.  Creating a xsrf claim value.  . . . . . . . . . . . . . . . .   4
     4.1.  Statefull Clients.  . . . . . . . . . . . . . . . . . . .   4
     4.2.  Stateless Clients.  . . . . . . . . . . . . . . . . . . .   4
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   5
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .   5
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   In the OAuth 2.0 Authorization protocol [RFC6749] , the Authorization
   server SHOULD perform an exact string comparison of the
   "redirect_uri" paramater with the "redirect_uri" paramater registered
   by by the client.  This is essential for stopping token leakage to
   third parties in the OAuth implicit flow.

   As a result of this clients can not safely add extra query paramaters
   to the "redirect_uri" paramater that encode additional client state

   The Client MUST use the "state" paramater to encode both Cross Site
   Request Forgery protection and any other state information it wishes
   to preserve for itself regarding the authorization request.

   This draft proposes a mechanism whereby multiple state attributes can
   be encoded into a JSON Web Token [JWT] for use as the value of the
   "state" paramater.

   The JWT may be sent without integrity protection, with integrity
   protection [JWA], or with both integrity and confidentiality
   protection [JWE].  The client is free to choose the appropriate
   protection for it's use-case as the "state" paramater is treated as
   opaque by the Authorization Server (AS).

Bradley                 Expires November 5, 2014                [Page 2]

Internet-Draft              Abbreviated-Title                   May 2014

2.  The state JSON Web Token claims

   The OAuth Authorization request "state" paramater consists of a
   [JWT], optionally signed with [JWS] or encrypted with [JWE], whose
   payload contains claims as defined here.

   xsrf  REQUIRED. string containing a verifiable identifier for the
      browser session, that cannot be guessed by a third party.  The
      verification of this element by the client protects it from
      accepting authorization responses generated in response to
      requests generated by third parities.

   kid  RECOMMENDED if signed.  Identifier of the key used to sign this
      client identifier at the issuer.

   iat  OPTIONAL.  Timestamp of when this Authorization Request was

   iss  OPTIONAL. string identifying the party that issued this state

   aud  OPTIONAL. string identifying the client that this state value is
      intended for.

   target_uri  OPTIONAL.  URI containing the location the user agent is
      to be redirected to after authorization.

   as OPTIONAL. string identifying the authorization server that this
      request was sent to.

   The issuer may add additional claims to the token.  The producer and
   the consumer of the JWT are the same or closely related entities so
   collision resistance of claim names should not be a concern.

   The issuer SHOULD sign the JWT with JWS [JWS] in such a way that it
   can verify the signature.  The JWA [JWA] algorithm HS256 with a key
   of 256bits is recommended.

   The issuer MAY sign the JWT with JWA algorithm none if integrity
   protecting the contents of the "state" paramater is not required.

   If the "state" paramater contains information the client dosen't want
   to disclose to the Authorization server or user, the issuer MAY
   encrypt the JWT with JWE.  The JWA [JWA] algorithm ("alg") of "dir"
   and encryption algorithm ("enc") of "A128CBC-HS256" are recommended
   for symmetric encryption.

Bradley                 Expires November 5, 2014                [Page 3]

Internet-Draft              Abbreviated-Title                   May 2014

3.  Validating the state paramater

   Upon receiving a state paramater the client must validate its
   integrity.  The client parses it as a JWT.  It then verifies the
   signature if the JWT (if signed) using JWS [JWS].  T he key used to
   sign the JWT MAY be indicated by the kid field.  The client MAY use
   other means to validate the JWT and determine its authenticity.

   The client then reads the fields inside the JWT and uses these to
   configure the user experience and security parameters of the

   The "xsrf" claim MUST be validated by the client by comparing it to
   the secret information that it used to create the "xrsf" value.

4.  Creating a xsrf claim value.

   The client MUST create a value that cannot be guessed by a third
   party attacker and used to forge requests.  There are many possible
   ways to create this value.  For reference two common ways will be

   It is completely up to the purview of the particular client which
   generation methods, and which claims, they will accept.

4.1.  Statefull Clients.

   Many clients that are web servers maintain session state for browsers
   in a server side store.

   These clients can generate a random value with sufficient entropy
   that an attacker cannot guess future values.  This value can be
   stored in the server side store and used directly as the value of

4.2.  Stateless Clients.

   Some clients that are web servers maintain session state for browsers
   using browser stored cookies or HTML5 local storage.

   These clients can generate a hash value based on a HTTPS: bound
   session cookie or other browser side information that is not
   accessible to third parties.  This hash value can directly as the
   value of "xsrf".

   While OAuth strongly recommends that clients use TLS to secure there
   endpoints, if a client is not using TLS it MUST produce the value of

Bradley                 Expires November 5, 2014                [Page 4]

Internet-Draft              Abbreviated-Title                   May 2014

   "xsrf" by using a HMAC algorithm with a secret known only to itself
   over the browser stored information.

5.  IANA Considerations

   [ maybe we register the "xsrf" claim above? ]

   This document makes no request of IANA.

   Note to RFC Editor: this section may be removed on publication as an

6.  Security Considerations

   Some information in the state JWT such as target uri for redirecting
   the user to might have some security impact is the user modifies them
   intentionally or unintentionally.  To prevent tampering with the
   "state" value the client may integrity protect the contents of the

   The client may have information that it wants to protect from
   disclosure to the Authorization server, in loggs. to proxies, or to
   the user.  In this case encrypting the JWT as a JWE is required to
   protect the confidentiality of the state information.

7.  Acknowledgements

8.  Normative References

   [JWA]      Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose-
              json-web-algorithms (work in progress), April 2014.

   [JWE]      Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              draft-ietf-jose-json-web-encryption (work in progress),
              April 2014.

   [JWS]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", draft-ietf-jose-json-web-signature (work
              in progress), April 2014.

   [JWT]      Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", draft-ietf-oauth-json-web-token (work in
              progress), March 2014.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

Bradley                 Expires November 5, 2014                [Page 5]

Internet-Draft              Abbreviated-Title                   May 2014

   [RFC6749]  Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
              6749, October 2012.

Author's Address

   John Bradley (editor)
   Ping Identity

   Email: ve7jtb@ve7jtb.com
   URI:   http://www.thread-safe.com/

Bradley                 Expires November 5, 2014                [Page 6]

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