Network Working Group J. Bradley, Ed. Internet-Draft Ping Intended status: Experimental T. Lodderstedt Expires: November 9, 2014 Deutsche Telekom AG May 08, 2014 Encoding claims in the OAuth 2 state paramater using a JWT draft-bradley-oauth-jwt-encoded-state-00 Abstract 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", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 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 9, 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 Bradley & Lodderstedt Expires November 9, 2014 [Page 1] Internet-Draft Abbreviated-Title May 2014 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. The state JSON Web Token claims . . . . . . . . . . . . . . . 3 3. Validating the state paramater . . . . . . . . . . . . . . . 4 4. Creating a Request Forgery Protection (rfp) claim value. . . 5 4.1. Statefull Clients. . . . . . . . . . . . . . . . . . . . 5 4.2. Stateless Clients. . . . . . . . . . . . . . . . . . . . 5 4.3. Responses Initiated by the Issuer . . . . . . . . . . . . 5 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 8. Normative References . . . . . . . . . . . . . . . . . . . . 6 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 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 information. 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 & Lodderstedt Expires November 9, 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. rfp 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 forged 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 issued. iss OPTIONAL. string identifying the party that issued this state value. 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. at_hash OPTIONAL. Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the "access_token" value, where the hash algorithm used is the hash algorithm used in the "alg" parameter of the State Token's JWS [JWS] header. For instance, if the "alg" is "RS256", hash the "access_token" value with SHA-256, then take the left-most 128 bits and base64url encode them. The "at_hash" value is a case sensitive string. c_hash Bradley & Lodderstedt Expires November 9, 2014 [Page 3] Internet-Draft Abbreviated-Title May 2014 OPTIONAL. Code hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the "code" value, where the hash algorithm used is the hash algorithm used in the "alg" header parameter of the State Token's JWS [JWS] header. For instance, if the "alg" is "HS512", hash the "code" value with SHA-512, then take the left- most 256 bits and base64url encode them. The "c_hash" value is a case sensitive string. 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] in such a way that it can verify the signature. The [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. In the case of the "state" value being created by the Issuer the "iss" and "aud" claims MUST be included in the JWT. The jwt MUST also be signed with [JWS]. If the State token is issued with a code "c_hash" MUST be included. If the State Token is issued with a Access Token "at_hash" MUST be included. 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]. 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 authorization. The "rfp" claim MUST be validated by the client by comparing it to the secret information that it used to create the "rfp" value. Bradley & Lodderstedt Expires November 9, 2014 [Page 4] Internet-Draft Abbreviated-Title May 2014 4. Creating a Request Forgery Protection (rfp) 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 listed. 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 "rfp". 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 "rfp" by using a HMAC algorithm with a secret known only to itself over the browser stored information. 4.3. Responses Initiated by the Issuer Some clients may be willing to rely on the Authorization server providing protection for Cross Site Request Forgery. In Cases where the Authorization server and the client have a pre-established relationship, and the client is willing to accept flows initiated by the Authorization server, the string "iss" may be used as the value of "rfp". Bradley & Lodderstedt Expires November 9, 2014 [Page 5] Internet-Draft Abbreviated-Title May 2014 5. IANA Considerations [ maybe we register the "rfp" claim above? ] This document makes no request of IANA. Note to RFC Editor: this section may be removed on publication as an RFC. 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 JWT. 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. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. Bradley & Lodderstedt Expires November 9, 2014 [Page 6] Internet-Draft Abbreviated-Title May 2014 Authors' Addresses John Bradley (editor) Ping Identity Email: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/ Dr.-Ing. Torsten Lodderstedt Deutsche Telekom AG Email: torsten@lodderstedt.net Bradley & Lodderstedt Expires November 9, 2014 [Page 7]