idnits 2.17.1 draft-bradley-oauth-jwt-encoded-state-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 15, 2015) is 3045 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Bradley, Ed. 3 Internet-Draft Ping 4 Intended status: Experimental T. Lodderstedt 5 Expires: June 17, 2016 Deutsche Telekom AG 6 H. Zandbelt 7 Ping 8 December 15, 2015 10 Encoding claims in the OAuth 2 state parameter using a JWT 11 draft-bradley-oauth-jwt-encoded-state-05 13 Abstract 15 This draft provides a method for a client to encode one or more 16 elements encoding information about the session into the OAuth 2 17 "state" parameter. 19 Requirements Language 21 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 22 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 23 document are to be interpreted as described in RFC 2119 [RFC2119]. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on June 17, 2016. 42 Copyright Notice 44 Copyright (c) 2015 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. The state JSON Web Token claims . . . . . . . . . . . . . . . 3 61 3. Validating the state parameter . . . . . . . . . . . . . . . 5 62 4. Creating a Request Forgery Protection (rfp) claim value. . . 5 63 4.1. Stateful Clients. . . . . . . . . . . . . . . . . . . . . 6 64 4.2. Stateless Clients. . . . . . . . . . . . . . . . . . . . 6 65 4.3. Responses Initiated by the Issuer . . . . . . . . . . . . 6 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 68 6.1. State Redirection . . . . . . . . . . . . . . . . . . . . 7 69 6.2. State Modification . . . . . . . . . . . . . . . . . . . 7 70 6.3. State Confidentiality . . . . . . . . . . . . . . . . . . 7 71 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 7 73 Appendix A. Document History . . . . . . . . . . . . . . . . . . 8 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 In the OAuth 2.0 Authorization protocol [RFC6749] , the Authorization 79 server SHOULD perform an exact string comparison of the 80 "redirect_uri" parameter with the "redirect_uri" parameter registered 81 by by the client. This is essential for preventing token leakage to 82 third parties in the OAuth implicit flow. 84 As a result of this clients can not safely add extra query parameters 85 to the "redirect_uri" parameter that encode additional client state 86 information. 88 The Client MUST use the "state" parameter to encode both Cross Site 89 Request Forgery protection and any other state information it wishes 90 to preserve for itself regarding the authorization request. 92 This draft proposes a mechanism whereby multiple state attributes can 93 be encoded into a JSON Web Token JWT [RFC7519] for use as the value 94 of the "state" parameter. 96 The JWT may be sent without integrity protection, with integrity 97 protection JWS [RFC7515], or with both integrity and confidentiality 98 protection JWE [RFC7516]. The client is free to choose the 99 appropriate protection for its use-case as the "state" parameter is 100 treated as opaque by the Authorization Server (AS). 102 2. The state JSON Web Token claims 104 The OAuth Authorization request "state" parameter consists of a JWT 105 [RFC7519], optionally signed with JWS [RFC7515] or encrypted with JWE 106 [RFC7516], whose payload contains claims as defined here. 108 rfp 109 REQUIRED. string containing a verifiable identifier for the 110 browser session, that cannot be guessed by a third party. The 111 verification of this element by the client protects it from 112 accepting authorization responses generated in response to forged 113 requests generated by third parties. 115 kid 116 RECOMMENDED if signed or encrypted. Identifier of the key used to 117 sign this state token at the issuer. Identifier of the key used 118 to encrypt this JWT state token at the issuer. This SHOULD be 119 included in the JWE [RFC7516] header. 121 iat 122 OPTIONAL. Timestamp of when this Authorization Request was 123 issued. 125 exp 126 OPTIONAL. The "exp" (expiration time) claim identifies the 127 expiration time on or after which the JWT MUST NOT be accepted for 128 processing. The processing of the "exp" claim requires that the 129 current date/time MUST be before the expiration date/time listed 130 in the "exp" claim. Implementers MAY provide for some small 131 leeway, usually no more than a few minutes, to account for clock 132 skew. Its value MUST be a number containing an IntDate value. 133 Use of this claim is OPTIONAL. This is RECOMMENDED if the JWT 134 [RFC7519] state token is being produced by the AS. 136 iss 137 OPTIONAL. string identifying the party that issued this state 138 value. 140 aud 141 OPTIONAL. string identifying the client that this state value is 142 intended for. 144 target_link_uri 145 OPTIONAL. URI containing the location the user agent is to be 146 redirected to after authorization. 148 as 149 OPTIONAL. string identifying the authorization server that this 150 request was sent to. 152 jti 153 RECOMMENDED. The "jti" (JWT ID) claim provides a unique 154 identifier for the JWT. The identifier value MUST be assigned in 155 a manner that ensures that there is a negligible probability that 156 the same value will be accidentally assigned to a different data 157 object. The "jti" claim can be used to prevent the JWT from being 158 replayed. The "jti" value is a case-sensitive string. Use of 159 this claim is OPTIONAL. 161 at_hash 162 OPTIONAL. Access Token hash value. Its value is the base64url 163 encoding of the left-most half of the hash of the octets of the 164 ASCII representation of the "access_token" value, where the hash 165 algorithm used is the hash algorithm used in the "alg" parameter 166 of the State Token's JWS [RFC7515] header. For instance, if the 167 "alg" is "RS256", hash the "access_token" value with SHA-256, then 168 take the left-most 128 bits and base64url encode them. The 169 "at_hash" value is a case sensitive string. This is REQUIRED if 170 the JWT [RFC7519] state token is being produced by the AS and 171 issued with a "access_token" in the authorization response. 173 c_hash 174 OPTIONAL. Code hash value. Its value is the base64url encoding 175 of the left-most half of the hash of the octets of the ASCII 176 representation of the "code" value, where the hash algorithm used 177 is the hash algorithm used in the "alg" header parameter of the 178 State Token's JWS [RFC7515] header. For instance, if the "alg" is 179 "HS512", hash the "code" value with SHA-512, then take the left- 180 most 256 bits and base64url encode them. The "c_hash" value is a 181 case sensitive string. This is REQUIRED if the JWT [RFC7519] 182 state token is being produced by the AS and issued with a "code" 183 in the authorization response. 185 The issuer may add additional claims to the token. The producer and 186 the consumer of the JWT are the same or closely related entities so 187 collision resistance of claim names should not be a concern. 189 The issuer SHOULD sign the JWT [RFC7519] with JWS [RFC7515] in such a 190 way that it can verify the signature. The JWA [RFC7518] algorithm 191 HS256 with a key of 256bits is recommended. 193 The issuer MAY sign the JWT [RFC7519] with JWS [RFC7515] using JWA 194 [RFC7518] algorithm "none" if integrity protecting the contents of 195 the "state" parameter is not required. 197 If the "state" parameter contains information the client doesn't want 198 to disclose to the Authorization server or user, the issuer MAY 199 encrypt the JWT [RFC7519] with JWE [RFC7516]. The JWA [RFC7518] 200 algorithm ("alg") of "dir" and encryption algorithm ("enc") of 201 "A128CBC-HS256" are recommended for symmetric encryption. 203 In the case of the "state" value being created by the Issuer the 204 "iss" and "aud" claims MUST be included in the JWT. The jwt MUST 205 also be signed with JWT [RFC7515]. If the State token is issued with 206 a code "c_hash" MUST be included. If the State Token is issued with 207 a Access Token "at_hash" MUST be included. 209 3. Validating the state parameter 211 Upon receiving a state parameter the client must validate its 212 integrity. The client parses it as a JWT. It then verifies the 213 signature of the JWT (if signed) using JWS [RFC7515]. The key used 214 to sign the JWT [RFC7519] MAY be indicated by the kid field. The 215 client MAY use other means to validate the JWT and determine its 216 authenticity. 218 The client then reads the fields inside the JWT [RFC7519] and uses 219 these to configure the user experience and security parameters of the 220 authorization. 222 The "rfp" claim MUST be validated by the client by comparing it to 223 the secret information that it used to create the "rfp" value. 225 The "as" claim if present MUST correspond to the URI endpoint 226 registered as the "redirect_uri" for that AS. 228 4. Creating a Request Forgery Protection (rfp) claim value. 230 The client MUST create a value that cannot be guessed by a third 231 party attacker and used to forge requests. There are many possible 232 ways to create this value. For reference two common ways will be 233 listed. 235 It is completely up to the purview of the particular client which 236 generation methods, and which claims, they will accept. 238 4.1. Stateful Clients. 240 Many clients that are web servers maintain session state for browsers 241 in a server side store. 243 These clients can generate a random value with sufficient entropy 244 that an attacker cannot guess future values. This value can be 245 stored in the server side store and used directly as the value of 246 "rfp". 248 4.2. Stateless Clients. 250 Some clients that are web servers maintain session state for browsers 251 using browser stored cookies or HTML5 local storage. 253 These clients can generate a hash value based on a HTTPS: bound 254 session cookie or other browser side information that is not 255 accessible to third parties. This hash value can be used as the 256 value of "rfp". 258 While OAuth strongly recommends that clients use TLS to secure their 259 endpoints, if a client is not using TLS it MUST produce the value of 260 "rfp" by using a HMAC algorithm with a secret known only to itself 261 over the browser stored information. 263 4.3. Responses Initiated by the Issuer 265 Some clients may be willing to rely on the Authorization server 266 providing protection for Cross Site Request Forgery. In Cases where 267 the Authorization server and the client have a pre-established 268 relationship, and the client is willing to accept flows initiated by 269 the Authorization server, the string "iss" may be used as the value 270 of "rfp". 272 5. IANA Considerations 274 [ maybe we register the "rfp" claim above? ] 276 This document makes no request of IANA. 278 Note to RFC Editor: this section may be removed on publication as an 279 RFC. 281 6. Security Considerations 282 6.1. State Redirection 284 A client Authorization request might be redirected from the AS 285 intended by the client, as part of an attack to confuse the client, 286 and cause it to deliver a code or access tokens to a endpoint that 287 the attacker can intercept them from. A Client that has client_id 288 issued by more than one AS SHOULD register a distinct "redirect_uri" 289 value with each AS. 291 The "redirect_uri" that the Authorization response is received on 292 MUST match the AS identified in the "as" claim. 294 If the AS allows pattern matching of query paramaters in the 295 "redirect_uri" the identifier for the AS MUST be contained in the URI 296 path component. 298 6.2. State Modification 300 Some information in the state JWT such as target_link_uri value for 301 redirecting the user to the application might have some security 302 impact is the user modifies them intentionally or unintentionally. 303 To prevent tampering with the "state" value the client may integrity 304 protect the contents of the JWT. 306 6.3. State Confidentiality 308 The client may have information that it wants to protect from 309 disclosure to the Authorization server, in logs, to proxies, or to 310 the user. In this case encrypting the JWT as a JWE is required to 311 protect the confidentiality of the state information. 313 7. Acknowledgements 315 8. Normative References 317 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 318 Requirement Levels", BCP 14, RFC 2119, 319 DOI 10.17487/RFC2119, March 1997, 320 . 322 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 323 RFC 6749, DOI 10.17487/RFC6749, October 2012, 324 . 326 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 327 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 328 2015, . 330 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 331 RFC 7516, DOI 10.17487/RFC7516, May 2015, 332 . 334 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 335 DOI 10.17487/RFC7518, May 2015, 336 . 338 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 339 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 340 . 342 Appendix A. Document History 344 [[ to be removed by the RFC editor before publication as an RFC ]] 346 -04 348 o Updated references to JOSE/JWT 350 Authors' Addresses 352 John Bradley (editor) 353 Ping Identity 355 Email: ve7jtb@ve7jtb.com 356 URI: http://www.thread-safe.com/ 358 Dr.-Ing. Torsten Lodderstedt 359 Deutsche Telekom AG 361 Email: torsten@lodderstedt.net 363 Hans Zandbelt 364 Ping Identity 366 Email: hzandbelt@pingidentity.com 367 URI: http://hanszandbelt.wordpress.com