idnits 2.17.1 draft-bradley-oauth-jwt-encoded-state-08.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 (January 05, 2018) is 2295 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: July 9, 2018 6 H. Zandbelt 7 Ping 8 January 05, 2018 10 Encoding claims in the OAuth 2 state parameter using a JWT 11 draft-bradley-oauth-jwt-encoded-state-08 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 https://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 July 9, 2018. 42 Copyright Notice 44 Copyright (c) 2018 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 (https://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 6.4. Passing paramaters to the AS . . . . . . . . . . . . . . 7 72 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 73 8. Normative References . . . . . . . . . . . . . . . . . . . . 7 74 Appendix A. Document History . . . . . . . . . . . . . . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 77 1. Introduction 79 In the OAuth 2.0 Authorization protocol [RFC6749] , the Authorization 80 server SHOULD perform an exact string comparison of the 81 "redirect_uri" parameter with the "redirect_uri" parameter registered 82 by by the client. This is essential for preventing token leakage to 83 third parties in the OAuth implicit flow. 85 As a result of this clients can not safely add extra query parameters 86 to the "redirect_uri" parameter that encode additional client state 87 information. 89 The Client MUST use the "state" parameter to encode both Cross Site 90 Request Forgery protection and any other state information it wishes 91 to preserve for itself regarding the authorization request. 93 This draft proposes a mechanism whereby multiple state attributes can 94 be encoded into a JSON Web Token JWT [RFC7519] for use as the value 95 of the "state" parameter. 97 The JWT may be sent without integrity protection, with integrity 98 protection JWS [RFC7515], or with both integrity and confidentiality 99 protection JWE [RFC7516]. The client is free to choose the 100 appropriate protection for its use-case as the "state" parameter is 101 treated as opaque by the Authorization Server (AS). 103 2. The state JSON Web Token claims 105 The OAuth Authorization request "state" parameter consists of a JWT 106 [RFC7519], optionally signed with JWS [RFC7515] or encrypted with JWE 107 [RFC7516], whose payload contains claims as defined here. 109 rfp 110 REQUIRED. string containing a verifiable identifier for the 111 browser session, that cannot be guessed by a third party. The 112 verification of this element by the client protects it from 113 accepting authorization responses generated in response to forged 114 requests generated by third parties. 116 kid 117 RECOMMENDED if signed or encrypted. Identifier of the key used to 118 sign this state token at the issuer. Identifier of the key used 119 to encrypt this JWT state token at the issuer. This SHOULD be 120 included in the JWE [RFC7516] header. 122 iat 123 OPTIONAL. Timestamp of when this Authorization Request was 124 issued. 126 exp 127 OPTIONAL. The "exp" (expiration time) claim identifies the 128 expiration time on or after which the JWT MUST NOT be accepted for 129 processing. The processing of the "exp" claim requires that the 130 current date/time MUST be before the expiration date/time listed 131 in the "exp" claim. Implementers MAY provide for some small 132 leeway, usually no more than a few minutes, to account for clock 133 skew. Its value MUST be a number containing an IntDate value. 134 Use of this claim is OPTIONAL. This is RECOMMENDED if the JWT 135 [RFC7519] state token is being produced by the AS. 137 iss 138 OPTIONAL. string identifying the party that issued this state 139 value. 141 aud 142 OPTIONAL. string identifying the client that this state value is 143 intended for. 145 target_link_uri 146 OPTIONAL. URI containing the location the user agent is to be 147 redirected to after authorization. 149 as 150 OPTIONAL. string identifying the authorization server that this 151 request was sent to. 153 jti 154 RECOMMENDED. The "jti" (JWT ID) claim provides a unique 155 identifier for the JWT. The identifier value MUST be assigned in 156 a manner that ensures that there is a negligible probability that 157 the same value will be accidentally assigned to a different data 158 object. The "jti" claim can be used to prevent the JWT from being 159 replayed. The "jti" value is a case-sensitive string. Use of 160 this claim is OPTIONAL. 162 at_hash 163 OPTIONAL. Access Token hash value. Its value is the base64url 164 encoding of the left-most half of the hash of the octets of the 165 ASCII representation of the "access_token" value, where the hash 166 algorithm used is the hash algorithm used in the "alg" parameter 167 of the State Token's JWS [RFC7515] header. For instance, if the 168 "alg" is "RS256", hash the "access_token" value with SHA-256, then 169 take the left-most 128 bits and base64url encode them. The 170 "at_hash" value is a case sensitive string. This is REQUIRED if 171 the JWT [RFC7519] state token is being produced by the AS and 172 issued with a "access_token" in the authorization response. 174 c_hash 175 OPTIONAL. Code hash value. Its value is the base64url encoding 176 of the left-most half of the hash of the octets of the ASCII 177 representation of the "code" value, where the hash algorithm used 178 is the hash algorithm used in the "alg" header parameter of the 179 State Token's JWS [RFC7515] header. For instance, if the "alg" is 180 "HS512", hash the "code" value with SHA-512, then take the left- 181 most 256 bits and base64url encode them. The "c_hash" value is a 182 case sensitive string. This is REQUIRED if the JWT [RFC7519] 183 state token is being produced by the AS and issued with a "code" 184 in the authorization response. 186 The issuer may add additional claims to the token. The producer and 187 the consumer of the JWT are the same or closely related entities so 188 collision resistance of claim names should not be a concern. 190 The issuer SHOULD sign the JWT [RFC7519] with JWS [RFC7515] in such a 191 way that it can verify the signature. The JWA [RFC7518] algorithm 192 HS256 with a key of 256bits is recommended. 194 The issuer MAY sign the JWT [RFC7519] with JWS [RFC7515] using JWA 195 [RFC7518] algorithm "none" if integrity protecting the contents of 196 the "state" parameter is not required. 198 If the "state" parameter contains information the client doesn't want 199 to disclose to the Authorization server or user, the issuer MAY 200 encrypt the JWT [RFC7519] with JWE [RFC7516]. The JWA [RFC7518] 201 algorithm ("alg") of "dir" and encryption algorithm ("enc") of 202 "A128CBC-HS256" are recommended for symmetric encryption. 204 In the case of the "state" value being created by the Issuer the 205 "iss" and "aud" claims MUST be included in the JWT. The jwt MUST 206 also be signed with JWT [RFC7515]. If the State token is issued with 207 a code "c_hash" MUST be included. If the State Token is issued with 208 a Access Token "at_hash" MUST be included. 210 3. Validating the state parameter 212 Upon receiving a state parameter the client must validate its 213 integrity. The client parses it as a JWT. It then verifies the 214 signature of the JWT (if signed) using JWS [RFC7515]. The key used 215 to sign the JWT [RFC7519] MAY be indicated by the kid field. The 216 client MAY use other means to validate the JWT and determine its 217 authenticity. 219 The client then reads the fields inside the JWT [RFC7519] and uses 220 these to configure the user experience and security parameters of the 221 authorization. 223 The "rfp" claim MUST be validated by the client by comparing it to 224 the secret information that it used to create the "rfp" value. 226 The "as" claim if present MUST correspond to the URI endpoint 227 registered as the "redirect_uri" for that AS. 229 4. Creating a Request Forgery Protection (rfp) claim value. 231 The client MUST create a value that cannot be guessed by a third 232 party attacker and used to forge requests. There are many possible 233 ways to create this value. For reference two common ways will be 234 listed. 236 It is completely up to the purview of the particular client which 237 generation methods, and which claims, they will accept. 239 4.1. Stateful Clients. 241 Many clients that are web servers maintain session state for browsers 242 in a server side store. 244 These clients can generate a random value with sufficient entropy 245 that an attacker cannot guess future values. This value can be 246 stored in the server side store and used directly as the value of 247 "rfp". 249 4.2. Stateless Clients. 251 Some clients that are web servers maintain session state for browsers 252 using browser stored cookies or HTML5 local storage. 254 These clients can generate a hash value based on a HTTPS: bound 255 session cookie or other browser side information that is not 256 accessible to third parties. This hash value can be used as the 257 value of "rfp". 259 While OAuth strongly recommends that clients use TLS to secure their 260 endpoints, if a client is not using TLS it MUST produce the value of 261 "rfp" by using a HMAC algorithm with a secret known only to itself 262 over the browser stored information. 264 4.3. Responses Initiated by the Issuer 266 Some clients may be willing to rely on the Authorization server 267 providing protection for Cross Site Request Forgery. In Cases where 268 the Authorization server and the client have a pre-established 269 relationship, and the client is willing to accept flows initiated by 270 the Authorization server, the string "iss" may be used as the value 271 of "rfp". 273 5. IANA Considerations 275 [ maybe we register the "rfp" claim above? ] 277 This document makes no request of IANA. 279 Note to RFC Editor: this section may be removed on publication as an 280 RFC. 282 6. Security Considerations 283 6.1. State Redirection 285 A client Authorization request might be redirected from the AS 286 intended by the client, as part of an attack to confuse the client, 287 and cause it to deliver a code or access tokens to a endpoint that 288 the attacker can intercept them from. A Client that has multiple 289 client_id issued by more than one AS SHOULD register a distinct 290 "redirect_uri" value with each AS. 292 The "redirect_uri" that the Authorization response is received on 293 MUST match the AS identified in the "as" claim. 295 If the AS allows pattern matching of query paramaters in the 296 "redirect_uri" the identifier for the AS MUST be contained in the URI 297 path component. 299 6.2. State Modification 301 Some information in the state JWT such as target_link_uri value for 302 redirecting the user to the application might have some security 303 impact is the user modifies them intentionally or unintentionally. 304 To prevent tampering with the "state" value the client may integrity 305 protect the contents of the JWT. 307 6.3. State Confidentiality 309 The client may have information that it wants to protect from 310 disclosure to the Authorization server, in logs, to proxies, or to 311 the user. In this case encrypting the JWT as a JWE is required to 312 protect the confidentiality of the state information. 314 6.4. Passing paramaters to the AS 316 OAuth Signed Authorization request 317 [I-D.ietf-oauth-signed-http-request] should be used to integrity 318 protect paramaters sent by the client to the authorization server. 319 The state paramater is intended for the consumption of the client, 320 and to be opaque to the AS. Signed State should not be used to pass 321 paramaters from the client to the AS. 323 7. Acknowledgements 325 8. Normative References 327 [I-D.ietf-oauth-signed-http-request] 328 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 329 Signing HTTP Requests for OAuth", draft-ietf-oauth-signed- 330 http-request-03 (work in progress), August 2016. 332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14, RFC 2119, 334 DOI 10.17487/RFC2119, March 1997, 335 . 337 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 338 RFC 6749, DOI 10.17487/RFC6749, October 2012, 339 . 341 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 342 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 343 2015, . 345 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 346 RFC 7516, DOI 10.17487/RFC7516, May 2015, 347 . 349 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 350 DOI 10.17487/RFC7518, May 2015, 351 . 353 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 354 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 355 . 357 Appendix A. Document History 359 [[ to be removed by the RFC editor before publication as an RFC ]] 361 -05 363 o Added reference to OAuth Signed request 365 -04 367 o Updated references to JOSE/JWT 369 Authors' Addresses 371 John Bradley (editor) 372 Yubico 374 Email: ve7jtb@ve7jtb.com 375 URI: http://www.thread-safe.com/ 376 Dr.-Ing. Torsten Lodderstedt 378 Email: torsten@lodderstedt.net 380 Hans Zandbelt 381 Ping Identity 383 Email: hzandbelt@pingidentity.com 384 URI: http://hanszandbelt.wordpress.com