idnits 2.17.1 draft-hevroni-oauth-seamless-flow-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 25, 2018) is 2195 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 412 -- Looks like a reference, but probably isn't: '2' on line 414 -- Looks like a reference, but probably isn't: '3' on line 417 -- Looks like a reference, but probably isn't: '4' on line 419 -- Looks like a reference, but probably isn't: '5' on line 422 -- Looks like a reference, but probably isn't: '6' on line 425 -- Looks like a reference, but probably isn't: '7' on line 427 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group O. Levi Hevroni 3 Internet-Draft Soluto by Asurion 4 Intended status: Informational March 25, 2018 5 Expires: September 26, 2018 7 Seamless OAuth 2.0 Client Assertion Grant 8 draft-hevroni-oauth-seamless-flow-00 10 Abstract 12 This specification defines the use of a One Time Password, encoded as 13 JSON Web Token (JWS) Bearer Token, as a means for requesting an OAuth 14 2.0 access token as well as for client authentication. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on September 26, 2018. 33 Copyright Notice 35 Copyright (c) 2018 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.2. Existing Solutions . . . . . . . . . . . . . . . . . . . 3 53 1.2.1. Client Credentials grant . . . . . . . . . . . . . . 3 54 1.2.2. Device grant . . . . . . . . . . . . . . . . . . . . 3 55 1.2.3. JWT Client Assertion . . . . . . . . . . . . . . . . 3 56 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Note to Readers . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. HTTP Parameter Bindings for Transporting Assertions . . . . . 4 59 3.1. Using OTP JWS for client authentication . . . . . . . . . 4 60 4. JWS format and request processing . . . . . . . . . . . . . . 5 61 4.1. One Time Password generation . . . . . . . . . . . . . . 5 62 4.2. Creating the JWS . . . . . . . . . . . . . . . . . . . . 5 63 4.3. Request processing . . . . . . . . . . . . . . . . . . . 6 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 65 5.1. Replay Attacks . . . . . . . . . . . . . . . . . . . . . 6 66 5.2. Compromised Signing key . . . . . . . . . . . . . . . . . 7 67 5.3. Man in the Middle . . . . . . . . . . . . . . . . . . . . 7 68 5.4. Reverse Engineering . . . . . . . . . . . . . . . . . . . 7 69 5.5. OTP Generation . . . . . . . . . . . . . . . . . . . . . 7 70 5.6. Signing Key Consideration . . . . . . . . . . . . . . . . 8 71 5.6.1. Generation and Storage . . . . . . . . . . . . . . . 8 72 5.6.2. Algorithm . . . . . . . . . . . . . . . . . . . . . . 8 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 76 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 79 1. Introduction 81 1.1. Motivation 83 Authentication is a crucial part of modern application. There are 84 various authentication methods for client side applications, and all 85 those methods requires user interaction (e.g. login). This is due to 86 the fact that there is no secure way to embed credentials in the 87 application code. 89 While asking the user to login in order to authenticate the app is a 90 strong authentication solution, it has impact on the application 91 behavior. A login is just another step the user has to complete in 92 order to use the apps, which users don't always like to fulfill. 94 Also, there are cases for applications without any UI, for example - 95 Internet of Things applications. For those applications, adding a 96 login steps could be a challenge. 98 In this document, we propose an extension to OAuth 2.0 protocol that 99 provides a new authentication grant dedicated for those cases. This 100 grant will allow an application to use strong authentication solution 101 without user interaction. 103 This document defines how a One Time Password, encoded in a JWS, can 104 be used to authenticate the client. In order for the client to 105 perform an authentication request, an initial registration step is 106 required. This registration step is not part of this protocol, and 107 should be defined by the authorization server. 109 1.2. Existing Solutions 111 There are alternatives to this protocol, this section will discuss 112 them. Interactive grants (authorization code, resource owner etc) 113 will not be discussed. 115 1.2.1. Client Credentials grant 117 This grant (as defined in [RFC6749]) allows applications to 118 authenticate without user interaction. It is intend to be used by 119 applications running on trusted environment. Mobile applications are 120 not running on trusted environment, and therefor should not use this 121 grant. See the Security section for discussion on the various threat 122 and how this protocol mitigate them. Also refer to section 10.1 in 123 [RFC6749], which strongly advise against using this grant on native 124 applications. 126 1.2.2. Device grant 128 This grant is for Browserless and Input Constrained Devices. In this 129 grant the login is performed on a different device, which could 130 handle interactive login. Therefore, it still requires user 131 interaction, which this protocol aims to avoid. 133 1.2.3. JWT Client Assertion 135 This grant (as defined in [RFC7523]) could be used by mobile 136 application for seamless authentication. The grant used signed JWT 137 (see [RFC7519]) to authenticate the client. It has two disadvantages 138 when compared with this grant: 140 o Significant part of the security of the protocol is the expiration 141 date of the JWT. In case a hacker was able to obtain a JWT, she 142 will be able to perform authentication request until the JWT 143 expires. Therefore, it is advised to use as shorter expiration 144 time as possible. Time can be a challenge on mobile devices, 145 which are not always synchronized with the global time. Usage of 146 JWT would require the authorization server to allow very long JWT 147 expiration time. 149 o Detecting Compromised Signing Key. As discussed on the security 150 section, this protocol allows the authorization server to detect 151 compromised signing key. See the discussion there for reference. 152 This mitigation does not exist in JWT client assertion grant. 154 1.3. Terminology 156 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 157 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 158 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 160 The term "device" used in this document refer to the physical 161 appliance used by the user, which the application code is running on. 163 2. Note to Readers 165 *Note to the RFC Editor:* Please remove this section prior to 166 publication. 168 Development of this draft takes place on Github at: 169 https://github.com/Soluto/oauth-seamless-flow [1]. 171 3. HTTP Parameter Bindings for Transporting Assertions 173 The OAuth Assertion Framework [RFC7521] defines generic HTTP 174 parameters for transporting assertions (a.k.a. security tokens) 175 during interactions with a token endpoint. This section defines 176 specific parameters and treatments of those parameters for use with 177 JWS (as defined in [RFC7515]) Bearer Tokens. 179 3.1. Using OTP JWS for client authentication 181 To use a OTP JWS, the client first need to generate the OTP as 182 defined in section "JWS format and request processing". Than, the 183 client need to use the following parameter values and encodings. 185 The value of the "client_assertion_type" is 186 "urn:ietf:params:oauth:client-assertion-type:JWS-otp". 188 The value of the "client_assertion" parameter contains a single JWS, 189 as defined in [RFC7515]. It MUST NOT contain more than one JWS. 191 The following example demonstrates client authentication using a JWS 192 during the presentation of an authorization code grant in an access 193 token request (with extra line breaks for display purposes only): 195 POST /token.oauth2 HTTP/1.1 196 Host: as.example.com 197 Content-Type: application/x-www-form-urlencoded 199 grant_type=token id_token&& 200 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A 201 client-assertion-type%3AJWS-otp& 202 client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0. 203 eyJpc3Mi[...omitted for brevity...]. 204 cC4hiUPo[...omitted for brevity...] 206 4. JWS format and request processing 208 4.1. One Time Password generation 210 To generate one time password (OTP) as defined in [RFC2289], the 211 client use its state, created during the registration request, which 212 is not covered in this document. The state consist from 2 numbers: 213 "previous" and "next". Each of those numbers can hold signed int, up 214 to 64 bytes length. In order to generate a new JWS, the client has 215 to roll this payload. The rolling is done by setting the value of 216 "previous" to the value of "current", and setting new crypto random, 217 as defined in [RFC4086], value to "next". For example, assuming this 218 is the current state of the app: 220 previous: 1 221 next: 2 223 After rolling, this will be the payload: 225 previous: 2 226 next: 5 228 4.2. Creating the JWS 230 After rolling the payload, the client can create the JWS. This is 231 the format of the JWS payload: 233 { 234 previous: 2 235 next: 5 236 client-id: 89 237 } 238 Where "client-id" is the id used when this client first registered. 239 All the fields are required. Any other fields besides those will be 240 ignored. To sign the JWS, the client use its own key, which was 241 generated during the registration of this client. 243 4.3. Request processing 245 In order to issue an access token response as described in OAuth 2.0 246 [RFC6749], the authorization server MUST validate the JWS according 247 to the criteria below. Application of additional restrictions and 248 policy are at the discretion of the authorization server. After 249 decoding the JWS and extracting the "client-id", the server will 250 fetch: 252 o The key correspond to this client, received on the registration 253 request 255 o The current state of this client, from the last successful 256 request, or from the registration 258 The server verifies that the JWS is valid, by using the client's key. 259 If the signature is valid, the server can validate the payload: 261 o If the client's "previous" is equals to the server "new", the 262 request is valid. The server will issue a token, as specified in 263 OAuth 2.0 [RFC6749] 265 o If the client "previous" equals to the server "previous", and the 266 client "next" equals to the server "next", the server construct an 267 error response as defined in OAuth 2.0 [RFC6749] 269 o Any other case will be treated by the server as an indication of a 270 malicious attack, and should be reported accordingly. The server 271 construct an error response as defined in OAuth 2.0 [RFC6749] 273 5. Security Considerations 275 This protocol was designed for mobile application. The following 276 sections will discuss threats which are relevant for mobile 277 applications and are mitigated by this protocol. 279 5.1. Replay Attacks 281 Due to the usage of OTP, a replay attack is not feasible. If an 282 attacker will try to replay authentication request, an error response 283 will return. Also, because of how the OTP is generated, guessing it 284 is almost impossible (see the OTP Generation section). Refer to the 285 Request processing section for more details. 287 5.2. Compromised Signing key 289 As the application is running on a mobile device, an attacker can 290 gain physical access to the device. In such a scenario, the attacker 291 will be able to compromise it and retrieve the state and the signing 292 key. This will allows the attacker to impersonate the device and 293 request an access token. The attacker will be able to authenticate 294 as until the first time the device will try to authenticate. When 295 the device will try to authenticate, the request will fail. It will 296 fail because the state on the authorization server will match the 297 attacker's state, not the one on the device. 299 The device authentication request will revoke the client (see Request 300 processing section). This will cause both the device and the 301 attacker to not be able to perform authentication request. In such 302 cases, an alternative flow is required in order to allow the device 303 to authenticate. Such a flow is not part of this standard. 305 In order for this mitigation to be effective, the device must to 306 perform an authentication request on a regular basis. The period 307 between authentication requests should be 24 hours or less, depend on 308 the client. 310 5.3. Man in the Middle 312 Performing Man in the Middle (MitM) attack on mobile application is 313 relatively simple. It is highly recommended to use TLS [RFC5246] for 314 all authentication requests. It is also recommended to implement 315 Certificate Pinning for all the requests. For more details, please 316 refer to this guide [2] by OWASP. 318 5.4. Reverse Engineering 320 The mobile application code is publicly available, which make reverse 321 engineering a simple task. This attack is irrelevant to this 322 protocol. No sensitive data should be embedded in the application 323 code. All that is required for the authentication request should be 324 generated on the device. 326 5.5. OTP Generation 328 The security of the OTP is as strong as the randomness used to 329 generate it. Only strong, secure random implementation (as described 330 in [RFC4086]) should be used. Usage of weak random protocol will 331 allow the attacker to guess the numbers generated by the client, and 332 by that generates the OTP herself. The state ("next" and "new") is 333 not considered a secret. Compromise of state only, without the 334 signing key, will not allows the attacker to perform authentication 335 request. It is still advised to store them securely, and follow the 336 operating system recommendation (iOS [3], Android [4]). 338 5.6. Signing Key Consideration 340 5.6.1. Generation and Storage 342 A fundamental part of the security of the protocol is the key used to 343 sign the JWS. The key should be generated and stored in a secure 344 wat, and if possible to use the tools provided by the OS. On iOS, 345 use Keychain [5] to generate and store the key. On Android, the best 346 option is the Keystore [6], but due to implementation limitations 347 (see this post [7] for example), it is advised to use OpenSSL. 349 5.6.2. Algorithm 351 Asymmetric encryption and signing algorithms are preferred over 352 symmetric ones. The main advantages of such protocol is that the 353 private key never leaves the device. Even if an attacker was able to 354 capture the public key (either in transit or by compromising the 355 authorization server), she will not be able to use it to perform 356 authentication request. For any algorithm that is chosen, a strong 357 key should be generated. In case of RSA, 2048 bytes is the minimum 358 key size. 360 6. IANA Considerations 362 TODO IANA 364 7. References 366 7.1. Normative References 368 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 369 Requirement Levels", BCP 14, RFC 2119, 370 DOI 10.17487/RFC2119, March 1997, 371 . 373 [RFC2289] Haller, N., Metz, C., Nesser, P., and M. Straw, "A One- 374 Time Password System", STD 61, RFC 2289, 375 DOI 10.17487/RFC2289, February 1998, 376 . 378 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 379 "Randomness Requirements for Security", BCP 106, RFC 4086, 380 DOI 10.17487/RFC4086, June 2005, 381 . 383 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 384 (TLS) Protocol Version 1.2", RFC 5246, 385 DOI 10.17487/RFC5246, August 2008, 386 . 388 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 389 RFC 6749, DOI 10.17487/RFC6749, October 2012, 390 . 392 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 393 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 394 2015, . 396 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 397 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 398 . 400 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 401 "Assertion Framework for OAuth 2.0 Client Authentication 402 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 403 May 2015, . 405 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 406 (JWT) Profile for OAuth 2.0 Client Authentication and 407 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 408 2015, . 410 7.2. URIs 412 [1] https://github.com/Soluto/oauth-seamless-flow 414 [2] https://www.owasp.org/index.php/ 415 Certificate_and_Public_Key_Pinning 417 [3] https://www.apple.com/business/docs/iOS_Security_Guide.pdf 419 [4] https://developer.android.com/training/articles/security- 420 tips.html#UserData 422 [5] https://developer.apple.com/documentation/security/ 423 keychain_services/keychains 425 [6] https://developer.android.com/training/articles/keystore.html 427 [7] https://doridori.github.io/android-security-the-forgetful- 428 keystore/#sthash.CgPjGF4h.dpbs 430 Author's Address 432 Omer Levi Hevroni 433 Soluto by Asurion 435 Email: omerlh@gmail.com