Network Working Group O. Levi Hevroni Internet-Draft Soluto by Asurion Intended status: Informational March 22, 2018 Expires: September 23, 2018 Seamless OAuth 2.0 Client Assertion Grant draft-seamless-flow-00 Abstract This specification defines the use of a One Time Password, encoded as JSON Web Token (JWS) Bearer Token, as a means for requesting an OAuth 2.0 access token as well as for client authentication. 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 https://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 September 23, 2018. Copyright Notice Copyright (c) 2018 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents 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. Levi Hevroni Expires September 23, 2018 [Page 1] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 2 1.2. Existing Solutions . . . . . . . . . . . . . . . . . . . 3 1.2.1. Client Credentials grant . . . . . . . . . . . . . . 3 1.2.2. Device grant . . . . . . . . . . . . . . . . . . . . 3 1.2.3. JWT Client Assertion . . . . . . . . . . . . . . . . 3 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. Note to Readers . . . . . . . . . . . . . . . . . . . . . . . 4 3. HTTP Parameter Bindings for Transporting Assertions . . . . . 4 3.1. Using OTP JWS for client authentication . . . . . . . . . 4 4. JWS format and request processing . . . . . . . . . . . . . . 5 4.1. One Time Password generation . . . . . . . . . . . . . . 5 4.2. Creating the JWS . . . . . . . . . . . . . . . . . . . . 5 4.3. Request processing . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5.1. Replay Attacks . . . . . . . . . . . . . . . . . . . . . 6 5.2. Compromised Signing key . . . . . . . . . . . . . . . . . 7 5.3. Man in the Middle . . . . . . . . . . . . . . . . . . . . 7 5.4. Reverse Engineering . . . . . . . . . . . . . . . . . . . 7 5.5. OTP Generation . . . . . . . . . . . . . . . . . . . . . 7 5.6. Signing Key Consideration . . . . . . . . . . . . . . . . 8 5.6.1. Generation and Storage . . . . . . . . . . . . . . . 8 5.6.2. Algorithm . . . . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction 1.1. Motivation Authentication is a crucial part of modern application. There are various authentication methods for client side applications, and all those methods requires user interaction (e.g. login). This is due to the fact that there is no secure way to embed credentials in the application code. While asking the user to login in order to authenticate the app is a strong authentication solution, it has impact on the application behavior. A login is just another step the user has to complete in order to use the apps, which users don't always like to fulfill. Levi Hevroni Expires September 23, 2018 [Page 2] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 Also, there are cases for applications without any UI, for example - Internet of Things applications. For those applications, adding a login steps could be a challenge. In this document, we propose an extension to OAuth 2.0 protocol that provides a new authentication grant dedicated for those cases. This grant will allow an application to use strong authentication solution without user interaction. This document defines how a One Time Password, encoded in a JWS, can be used to authenticate the client. In order for the client to perform an authentication request, an initial registration step is required. This registration step is not part of this protocol, and should be defined by the authorization server. 1.2. Existing Solutions There are alternatives to this protocol, this section will discuss them. Interactive grants (authorization code, resource owner etc) will not be discussed. 1.2.1. Client Credentials grant This grant (as defined in [RFC6749]) allows applications to authenticate without user interaction. It is intend to be used by applications running on trusted environment. Mobile applications are not running on trusted environment, and therefor should not use this grant. See the Security section for discussion on the various threat and how this protocol mitigate them. Also refer to section 10.1 in [RFC6749], which strongly advise against using this grant on native applications. 1.2.2. Device grant This grant is for Browserless and Input Constrained Devices. In this grant the login is performed on a different device, which could handle interactive login. Therefore, it still requires user interaction, which this protocol aims to avoid. 1.2.3. JWT Client Assertion This grant (as defined in [RFC7523]) could be used by mobile application for seamless authentication. The grant used signed JWT (see [RFC7519]) to authenticate the client. It has two disadvantages when compared with this grant: o Significant part of the security of the protocol is the expiration date of the JWT. In case a hacker was able to obtain a JWT, she Levi Hevroni Expires September 23, 2018 [Page 3] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 will be able to perform authentication request until the JWT expires. Therefore, it is advised to use as shorter expiration time as possible. Time can be a challenge on mobile devices, which are not always synchronized with the global time. Usage of JWT would require the authorization server to allow very long JWT expiration time. o Detecting Compromised Signing Key. As discussed on the security section, this protocol allows the authorization server to detect compromised signing key. See the discussion there for reference. This mitigation does not exist in JWT client assertion grant. 1.3. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119]. The term "device" used in this document refer to the physical appliance used by the user, which the application code is running on. 2. Note to Readers *Note to the RFC Editor:* Please remove this section prior to publication. Development of this draft takes place on Github at: https://github.com/Soluto/oauth-seamless-flow [1]. 3. HTTP Parameter Bindings for Transporting Assertions The OAuth Assertion Framework [RFC7521] defines generic HTTP parameters for transporting assertions (a.k.a. security tokens) during interactions with a token endpoint. This section defines specific parameters and treatments of those parameters for use with JWS (as defined in [RFC7515]) Bearer Tokens. 3.1. Using OTP JWS for client authentication To use a OTP JWS, the client first need to generate the OTP as defined in section "JWS format and request processing". Than, the client need to use the following parameter values and encodings. The value of the "client_assertion_type" is "urn:ietf:params:oauth:client-assertion-type:JWS-otp". The value of the "client_assertion" parameter contains a single JWS, as defined in [RFC7515]. It MUST NOT contain more than one JWS. Levi Hevroni Expires September 23, 2018 [Page 4] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 The following example demonstrates client authentication using a JWS during the presentation of an authorization code grant in an access token request (with extra line breaks for display purposes only): POST /token.oauth2 HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=token id_token&& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A client-assertion-type%3AJWS-otp& client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0. eyJpc3Mi[...omitted for brevity...]. cC4hiUPo[...omitted for brevity...] 4. JWS format and request processing 4.1. One Time Password generation To generate one time password (OTP) as defined in [RFC2289], the client use its state, created during the registration request, which is not covered in this document. The state consist from 2 numbers: "previous" and "next". Each of those numbers can hold signed int, up to 64 bytes length. In order to generate a new JWS, the client has to roll this payload. The rolling is done by setting the value of "previous" to the value of "current", and setting new crypto random, as defined in [RFC4086], value to "next". For example, assuming this is the current state of the app: previous: 1 next: 2 After rolling, this will be the payload: previous: 2 next: 5 4.2. Creating the JWS After rolling the payload, the client can create the JWS. This is the format of the JWS payload: { previous: 2 next: 5 client-id: 89 } Levi Hevroni Expires September 23, 2018 [Page 5] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 Where "client-id" is the id used when this client first registered. All the fields are required. Any other fields besides those will be ignored. To sign the JWS, the client use its own key, which was generated during the registration of this client. 4.3. Request processing In order to issue an access token response as described in OAuth 2.0 [RFC6749], the authorization server MUST validate the JWS according to the criteria below. Application of additional restrictions and policy are at the discretion of the authorization server. After decoding the JWS and extracting the "client-id", the server will fetch: o The key correspond to this client, received on the registration request o The current state of this client, from the last successful request, or from the registration The server verifies that the JWS is valid, by using the client's key. If the signature is valid, the server can validate the payload: o If the client's "previous" is equals to the server "new", the request is valid. The server will issue a token, as specified in OAuth 2.0 [RFC6749] o If the client "previous" equals to the server "previous", and the client "next" equals to the server "next", the server construct an error response as defined in OAuth 2.0 [RFC6749] o Any other case will be treated by the server as an indication of a malicious attack, and should be reported accordingly. The server construct an error response as defined in OAuth 2.0 [RFC6749] 5. Security Considerations This protocol was designed for mobile application. The following sections will discuss threats which are relevant for mobile applications and are mitigated by this protocol. 5.1. Replay Attacks Due to the usage of OTP, a replay attack is not feasible. If an attacker will try to replay authentication request, an error response will return. Also, because of how the OTP is generated, guessing it is almost impossible (see the OTP Generation section). Refer to the Request processing section for more details. Levi Hevroni Expires September 23, 2018 [Page 6] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 5.2. Compromised Signing key As the application is running on a mobile device, an attacker can gain physical access to the device. In such a scenario, the attacker will be able to compromise it and retrieve the state and the signing key. This will allows the attacker to impersonate the device and request an access token. The attacker will be able to authenticate as until the first time the device will try to authenticate. When the device will try to authenticate, the request will fail. It will fail because the state on the authorization server will match the attacker's state, not the one on the device. The device authentication request will revoke the client (see Request processing section). This will cause both the device and the attacker to not be able to perform authentication request. In such cases, an alternative flow is required in order to allow the device to authenticate. Such a flow is not part of this standard. In order for this mitigation to be effective, the device must to perform an authentication request on a regular basis. The period between authentication requests should be 24 hours or less, depend on the client. 5.3. Man in the Middle Performing Man in the Middle (MitM) attack on mobile application is relatively simple. It is highly recommended to use TLS [RFC5246] for all authentication requests. It is also recommended to implement Certificate Pinning for all the requests. For more details, please refer to this guide [2] by OWASP. 5.4. Reverse Engineering The mobile application code is publicly available, which make reverse engineering a simple task. This attack is irrelevant to this protocol. No sensitive data should be embedded in the application code. All that is required for the authentication request should be generated on the device. 5.5. OTP Generation The security of the OTP is as strong as the randomness used to generate it. Only strong, secure random implementation (as described in [RFC4086]) should be used. Usage of weak random protocol will allow the attacker to guess the numbers generated by the client, and by that generates the OTP herself. The state ("next" and "new") is not considered a secret. Compromise of state only, without the signing key, will not allows the attacker to perform authentication Levi Hevroni Expires September 23, 2018 [Page 7] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 request. It is still advised to store them securely, and follow the operating system recommendation (iOS [3], Android [4]). 5.6. Signing Key Consideration 5.6.1. Generation and Storage A fundamental part of the security of the protocol is the key used to sign the JWS. The key should be generated and stored in a secure wat, and if possible to use the tools provided by the OS. On iOS, use Keychain [5] to generate and store the key. On Android, the best option is the Keystore [6], but due to implementation limitations (see this post [7] for example), it is advised to use OpenSSL. 5.6.2. Algorithm Asymmetric encryption and signing algorithms are preferred over symmetric ones. The main advantages of such protocol is that the private key never leaves the device. Even if an attacker was able to capture the public key (either in transit or by compromising the authorization server), she will not be able to use it to perform authentication request. For any algorithm that is chosen, a strong key should be generated. In case of RSA, 2048 bytes is the minimum key size. 6. IANA Considerations TODO IANA 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2289] Haller, N., Metz, C., Nesser, P., and M. Straw, "A One- Time Password System", STD 61, RFC 2289, DOI 10.17487/RFC2289, February 1998, . [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, "Randomness Requirements for Security", BCP 106, RFC 4086, DOI 10.17487/RFC4086, June 2005, . Levi Hevroni Expires September 23, 2018 [Page 8] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC7521] Campbell, B., Mortimore, C., Jones, M., and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015, . 7.2. URIs [1] https://github.com/Soluto/oauth-seamless-flow [2] https://www.owasp.org/index.php/ Certificate_and_Public_Key_Pinning [3] https://www.apple.com/business/docs/iOS_Security_Guide.pdf [4] https://developer.android.com/training/articles/security- tips.html#UserData [5] https://developer.apple.com/documentation/security/ keychain_services/keychains [6] https://developer.android.com/training/articles/keystore.html [7] https://doridori.github.io/android-security-the-forgetful- keystore/#sthash.CgPjGF4h.dpbs Levi Hevroni Expires September 23, 2018 [Page 9] Internet-Draft Seamless OAuth 2.0 Client Assertion Grant March 2018 Author's Address Omer Levi Hevroni Soluto by Asurion Email: omerlh@gmail.com Levi Hevroni Expires September 23, 2018 [Page 10]