idnits 2.17.1 draft-hevroni-oauth-seamless-flow-01.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 (August 02, 2018) is 2093 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 423 -- Looks like a reference, but probably isn't: '2' on line 425 -- Looks like a reference, but probably isn't: '3' on line 428 -- Looks like a reference, but probably isn't: '4' on line 430 -- Looks like a reference, but probably isn't: '5' on line 433 -- Looks like a reference, but probably isn't: '6' on line 436 -- Looks like a reference, but probably isn't: '7' on line 438 ** 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 August 02, 2018 5 Expires: February 3, 2019 7 Seamless OAuth 2.0 Client Assertion Grant 8 draft-hevroni-oauth-seamless-flow-01 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 February 3, 2019. 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. Target Audience . . . . . . . . . . . . . . . . . . . . . 3 53 1.3. Existing Solutions . . . . . . . . . . . . . . . . . . . 3 54 1.3.1. Client Credentials grant . . . . . . . . . . . . . . 3 55 1.3.2. Device grant . . . . . . . . . . . . . . . . . . . . 3 56 1.3.3. JWT Client Assertion . . . . . . . . . . . . . . . . 4 57 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Note to Readers . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. HTTP Parameter Bindings for Transporting Assertions . . . . . 4 60 3.1. Using OTP JWS for client authentication . . . . . . . . . 5 61 4. JWS format and request processing . . . . . . . . . . . . . . 5 62 4.1. One Time Password generation . . . . . . . . . . . . . . 5 63 4.2. Creating the JWS . . . . . . . . . . . . . . . . . . . . 6 64 4.3. Request processing . . . . . . . . . . . . . . . . . . . 6 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 66 5.1. Replay Attacks . . . . . . . . . . . . . . . . . . . . . 7 67 5.2. Compromised Signing key . . . . . . . . . . . . . . . . . 7 68 5.3. Man in the Middle . . . . . . . . . . . . . . . . . . . . 7 69 5.4. Reverse Engineering . . . . . . . . . . . . . . . . . . . 8 70 5.5. OTP Generation . . . . . . . . . . . . . . . . . . . . . 8 71 5.6. Signing Key Consideration . . . . . . . . . . . . . . . . 8 72 5.6.1. Generation and Storage . . . . . . . . . . . . . . . 8 73 5.6.2. Algorithm . . . . . . . . . . . . . . . . . . . . . . 8 74 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 75 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 77 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 80 1. Introduction 82 1.1. Motivation 84 Authentication is a crucial part of modern application. There are 85 various authentication methods for client side applications, and all 86 those methods requires user interaction (e.g. login). This is due to 87 the fact that there is no secure way to embed credentials in the 88 application code. 90 While asking the user to login in order to authenticate the app is a 91 strong authentication solution, it has impact on the application 92 behavior. A login is just another step the user has to complete in 93 order to use the apps, which users don't always like to fulfill. 95 Also, there are cases for applications without any UI, for example - 96 Internet of Things applications. For those applications, adding a 97 login steps could be a challenge. 99 In this document, we propose an extension to OAuth 2.0 protocol that 100 provides a new authentication grant dedicated for those cases. This 101 grant will allow an application to use strong authentication solution 102 without user interaction. 104 This document defines how a One Time Password, encoded in a JWS, can 105 be used to authenticate the client. In order for the client to 106 perform an authentication request, an initial registration step is 107 required. This registration step is not part of this protocol, and 108 should be defined by the authorization server. 110 1.2. Target Audience 112 The protocol requires the app to be able to persist state in a 113 secure, sand-boxed, persisted storage. It is possible to use this 114 protocol for web application, although it is not recommended. This 115 protocol is targeted for mobile or IoT devices where it is possible 116 (although not always simple) to achieve such storage. See Security 117 Consideration section for more details. 119 1.3. Existing Solutions 121 There are alternatives to this protocol, this section will discuss 122 them. Interactive grants (authorization code, resource owner etc) 123 will not be discussed. 125 1.3.1. Client Credentials grant 127 This grant (as defined in [RFC6749]) allows applications to 128 authenticate without user interaction. It is intend to be used by 129 applications running on trusted environment. Mobile applications are 130 not running on trusted environment, and therefor should not use this 131 grant. See the Security section for discussion on the various threat 132 and how this protocol mitigate them. Also refer to section 10.1 in 133 [RFC6749], which strongly advise against using this grant on native 134 applications. 136 1.3.2. Device grant 138 This grant is for Browserless and Input Constrained Devices. In this 139 grant the login is performed on a different device, which could 140 handle interactive login. Therefore, it still requires user 141 interaction, which this protocol aims to avoid. 143 1.3.3. JWT Client Assertion 145 This grant (as defined in [RFC7523]) could be used by mobile 146 application for seamless authentication. The grant used signed JWT 147 (see [RFC7519]) to authenticate the client. It has two disadvantages 148 when compared with this grant: 150 o Significant part of the security of the protocol is the expiration 151 date of the JWT. In case a hacker was able to obtain a JWT, she 152 will be able to perform authentication request until the JWT 153 expires. Therefore, it is advised to use as shorter expiration 154 time as possible. Time can be a challenge on mobile devices, 155 which are not always synchronized with the global time. Usage of 156 JWT would require the authorization server to allow very long JWT 157 expiration time. 159 o Detecting Compromised Signing Key. As discussed on the security 160 section, this protocol allows the authorization server to detect 161 compromised signing key. See the discussion there for reference. 162 This mitigation does not exist in JWT client assertion grant. 164 1.4. Terminology 166 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 167 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 168 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 170 The term "device" used in this document refer to the physical 171 appliance used by the user, which the application code is running on. 173 2. Note to Readers 175 *Note to the RFC Editor:* Please remove this section prior to 176 publication. 178 Development of this draft takes place on Github at: 179 https://github.com/Soluto/oauth-seamless-flow [1]. 181 3. HTTP Parameter Bindings for Transporting Assertions 183 The OAuth Assertion Framework [RFC7521] defines generic HTTP 184 parameters for transporting assertions (a.k.a. security tokens) 185 during interactions with a token endpoint. This section defines 186 specific parameters and treatments of those parameters for use with 187 JWS (as defined in [RFC7515]) Bearer Tokens. 189 3.1. Using OTP JWS for client authentication 191 To use a OTP JWS, the client first need to generate the OTP as 192 defined in section "JWS format and request processing". Than, the 193 client need to use the following parameter values and encodings. 195 The value of the "client_assertion_type" is 196 "urn:ietf:params:oauth:client-assertion-type:JWS-otp". 198 The value of the "client_assertion" parameter contains a single JWS, 199 as defined in [RFC7515]. It MUST NOT contain more than one JWS. 201 The following example demonstrates client authentication using a JWS 202 during the presentation of an authorization code grant in an access 203 token request (with extra line breaks for display purposes only): 205 POST /token.oauth2 HTTP/1.1 206 Host: as.example.com 207 Content-Type: application/x-www-form-urlencoded 209 grant_type=token id_token&& 210 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A 211 client-assertion-type%3AJWS-otp& 212 client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0. 213 eyJpc3Mi[...omitted for brevity...]. 214 cC4hiUPo[...omitted for brevity...] 216 4. JWS format and request processing 218 4.1. One Time Password generation 220 To generate one time password (OTP) as defined in [RFC2289], the 221 client use its state, created during the registration request, which 222 is not covered in this document. The state consist from 2 numbers: 223 "previous" and "next". Each of those numbers can hold signed int, up 224 to 64 bytes length. In order to generate a new JWS, the client has 225 to roll this payload. The rolling is done by setting the value of 226 "previous" to the value of "current", and setting new crypto random, 227 as defined in [RFC4086], value to "next". For example, assuming this 228 is the current state of the app: 230 previous: 1 231 next: 2 233 After rolling, this will be the payload: 235 previous: 2 236 next: 5 238 4.2. Creating the JWS 240 After rolling the payload, the client can create the JWS. This is 241 the format of the JWS payload: 243 { 244 previous: 2 245 next: 5 246 client-id: 89 247 } 249 Where "client-id" is the id used when this client first registered. 250 All the fields are required. Any other fields besides those will be 251 ignored. To sign the JWS, the client use its own key, which was 252 generated during the registration of this client. 254 4.3. Request processing 256 In order to issue an access token response as described in OAuth 2.0 257 [RFC6749], the authorization server MUST validate the JWS according 258 to the criteria below. Application of additional restrictions and 259 policy are at the discretion of the authorization server. After 260 decoding the JWS and extracting the "client-id", the server will 261 fetch: 263 o The key correspond to this client, received on the registration 264 request 266 o The current state of this client, from the last successful 267 request, or from the registration 269 The server verifies that the JWS is valid, by using the client's key. 270 If the signature is valid, the server can validate the payload: 272 o If the client's "previous" is equals to the server "new", the 273 request is valid. The server will issue a token, as specified in 274 OAuth 2.0 [RFC6749] 276 o If the client "previous" equals to the server "previous", and the 277 client "next" equals to the server "next", the server construct an 278 error response as defined in OAuth 2.0 [RFC6749] 280 o Any other case will be treated by the server as an indication of a 281 malicious attack, and should be reported accordingly. The server 282 construct an error response as defined in OAuth 2.0 [RFC6749] 284 5. Security Considerations 286 This protocol was designed for mobile application. The following 287 sections will discuss threats which are relevant for mobile 288 applications and are mitigated by this protocol. 290 5.1. Replay Attacks 292 Due to the usage of OTP, a replay attack is not feasible. If an 293 attacker will try to replay authentication request, an error response 294 will return. Also, because of how the OTP is generated, guessing it 295 is almost impossible (see the OTP Generation section). Refer to the 296 Request processing section for more details. 298 5.2. Compromised Signing key 300 As the application is running on a mobile device, an attacker can 301 gain physical access to the device. In such a scenario, the attacker 302 will be able to compromise it and retrieve the state and the signing 303 key. This will allows the attacker to impersonate the device and 304 request an access token. The attacker will be able to authenticate 305 as until the first time the device will try to authenticate. When 306 the device will try to authenticate, the request will fail. It will 307 fail because the state on the authorization server will match the 308 attacker's state, not the one on the device. 310 The device authentication request will revoke the client (see Request 311 processing section). This will cause both the device and the 312 attacker to not be able to perform authentication request. In such 313 cases, an alternative flow is required in order to allow the device 314 to authenticate. Such a flow is not part of this standard. 316 In order for this mitigation to be effective, the device must to 317 perform an authentication request on a regular basis. The period 318 between authentication requests should be 24 hours or less, depend on 319 the client. 321 5.3. Man in the Middle 323 Performing Man in the Middle (MitM) attack on mobile application is 324 relatively simple. It is highly recommended to use TLS [RFC5246] for 325 all authentication requests. It is also recommended to implement 326 Certificate Pinning for all the requests. For more details, please 327 refer to this guide [2] by OWASP. 329 5.4. Reverse Engineering 331 The mobile application code is publicly available, which make reverse 332 engineering a simple task. This attack is irrelevant to this 333 protocol. No sensitive data should be embedded in the application 334 code. All that is required for the authentication request should be 335 generated on the device. 337 5.5. OTP Generation 339 The security of the OTP is as strong as the randomness used to 340 generate it. Only strong, secure random implementation (as described 341 in [RFC4086]) should be used. Usage of weak random protocol will 342 allow the attacker to guess the numbers generated by the client, and 343 by that generates the OTP herself. The state ("next" and "new") is 344 not considered a secret. Compromise of state only, without the 345 signing key, will not allows the attacker to perform authentication 346 request. It is still advised to store them securely, and follow the 347 operating system recommendation (iOS [3], Android [4]). 349 5.6. Signing Key Consideration 351 5.6.1. Generation and Storage 353 A fundamental part of the security of the protocol is the key used to 354 sign the JWS. The key should be generated and stored in a secure 355 wat, and if possible to use the tools provided by the OS. On iOS, 356 use Keychain [5] to generate and store the key. On Android, the best 357 option is the Keystore [6], but due to implementation limitations 358 (see this post [7] for example), it is advised to use OpenSSL. 360 5.6.2. Algorithm 362 Asymmetric encryption and signing algorithms are preferred over 363 symmetric ones. The main advantages of such protocol is that the 364 private key never leaves the device. Even if an attacker was able to 365 capture the public key (either in transit or by compromising the 366 authorization server), she will not be able to use it to perform 367 authentication request. For any algorithm that is chosen, a strong 368 key should be generated. In case of RSA, 2048 bytes is the minimum 369 key size. 371 6. IANA Considerations 373 TODO IANA 375 7. References 377 7.1. Normative References 379 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 380 Requirement Levels", BCP 14, RFC 2119, 381 DOI 10.17487/RFC2119, March 1997, 382 . 384 [RFC2289] Haller, N., Metz, C., Nesser, P., and M. Straw, "A One- 385 Time Password System", STD 61, RFC 2289, 386 DOI 10.17487/RFC2289, February 1998, 387 . 389 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 390 "Randomness Requirements for Security", BCP 106, RFC 4086, 391 DOI 10.17487/RFC4086, June 2005, 392 . 394 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 395 (TLS) Protocol Version 1.2", RFC 5246, 396 DOI 10.17487/RFC5246, August 2008, 397 . 399 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 400 RFC 6749, DOI 10.17487/RFC6749, October 2012, 401 . 403 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 404 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 405 2015, . 407 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 408 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 409 . 411 [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 412 "Assertion Framework for OAuth 2.0 Client Authentication 413 and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, 414 May 2015, . 416 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 417 (JWT) Profile for OAuth 2.0 Client Authentication and 418 Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 419 2015, . 421 7.2. URIs 423 [1] https://github.com/Soluto/oauth-seamless-flow 425 [2] https://www.owasp.org/index.php/ 426 Certificate_and_Public_Key_Pinning 428 [3] https://www.apple.com/business/docs/iOS_Security_Guide.pdf 430 [4] https://developer.android.com/training/articles/security- 431 tips.html#UserData 433 [5] https://developer.apple.com/documentation/security/ 434 keychain_services/keychains 436 [6] https://developer.android.com/training/articles/keystore.html 438 [7] https://doridori.github.io/android-security-the-forgetful- 439 keystore/#sthash.CgPjGF4h.dpbs 441 Author's Address 443 Omer Levi Hevroni 444 Soluto by Asurion 446 Email: omerlh@gmail.com