cid 58f0ba23f279b95d9a9e9f47487abe62369c77ee330e76c6781822fdb3c52b51 · original · open access · via rfc
Title: rfc:8252
Authors:
Venue: rfc
Year: 2017
Canonical: rfc:8252
URL: https://www.rfc-editor.org/rfc/rfc8252.txt
Collector: rfc
OA: true
ABSTRACT
Abstract OAuth 2.0 authorization requests from native apps should only be made through external user-agents, primarily the user's browser. This specification details the security and usability reasons why this is the case and how native apps and authorization servers can implement this best practice. Status of This Memo This memo documents an Internet Best Current Practice. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8252. Copyright Notice Copyright (c) 2017 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Authorization Flow for Native Apps Using the Browser . . 5 5. Using Inter-App URI Communication for OAuth . . . . . . . . . 6 6. Initiating the Authorization Request from a Native App . . . 6 7. Receiving the Authorization Response in a Native App . . . . 7 7.1. Private-Use URI Scheme Redirection . . . . . . . . . . . 8 7.2. Claimed "https" Scheme URI Redirection . . . . . . . . . 9 7.3. Loopback Interface Redirection . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 8.1. Protecting the Authorization Code . . . . . . . . . . . . 10 8.2. OAuth Implicit Grant Authorization Flow . . . . . . . . . 11 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11 8.4. Registration of Native App Clients . . . . . . . . . . . 12 8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12 8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 13 8.7. Fake External User-Agents . . . . . . . . . . . . . . . . 13 8.8. Malicious External User-Agents . . . . . . . . . . . . . 14 8.9. Cross-App Request Forgery Protections . . . . . . . . . . 14 8.10. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 8.11. Non-Browser External User-Agents . . . . . . . . . . . . 15 8.12. Embedded User-Agents . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 10.1. Normative References . . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 17 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 18 Appendix B. Platform-Specific Implementation Details . . . . . . 18 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 18 B.2. Android Implementation Details . . . . . . . . . . . . . 19 B.3. Windows Implementation Details . . . . . . . . . . . . . 19 B.4. macOS Implementation Details . . . . . . . . . . . . . . 20 B.5. Linux Implementation Details . . . . . . . . . . . . . . 21 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 1. Introduction Section 9 of the OAuth 2.0 authorization framework [RFC6749] documents two approaches for native apps to interact with the authorization endpoint: an embedded user-agent and an external user- agent. This best current practice requires that only external user-agents like the browser are used for OAuth by native apps. It documents how native apps can implement authorization flows using the browser as the preferred external user-agent as well as the requirements for authorization servers to support such usage. This practice is also known as the "AppAuth pattern", in reference to open-source libraries [AppAuth] that implement it. 2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Terminology In addition to the terms defined in referenced specifications, this document uses the following terms: "native app" An app or application that is installed by the user to their device, as distinct from a web app that runs in the browser context only. Apps implemented using web-based technology but distributed as a native app, so-called "hybrid apps", are considered equivalent to native apps for the purpose of this specification. "app" A "native app" unless further specified. "app store" An e-commerce store where users can download and purchase apps. "OAuth" Authorization protocol specified by the OAuth 2.0 Authorization Framework [RFC6749]. "external user-agent" A user-agent capable of handling the authorization request that is a separate entity or security domain to the native app making the request, such that the app cannot access the cookie storage, nor inspect or modify page content. "embedded user-agent" A user-agent hosted by the native app making the authorization request that forms a part of the app or shares the same security domain such that the app can access the cookie storage and/or inspect or modify page content. "browser" The default application launched by the operating system to handle "http" and "https" scheme URI content. "in-app browser tab" A programmatic instantiation of the browser that is displayed inside a host app but that retains the full security properties and authentication state of the browser. It has different platform-specific product names, several of which are detailed in Appendix B. "web-view" A web browser UI (user interface) component that is embedded in apps to render web pages under the control of the app. "inter-app communication" Communication between two apps on a device. "claimed "https" scheme URI" Some platforms allow apps to claim an "https" scheme URI after proving ownership of the domain name. URIs claimed in such a way are then opened in the app instead of the browser. "private-use URI scheme" As used by this document, a URI scheme defined by the app (following the requirements of Section 3.8 of [RFC7595]) and registered with the operating system. URI requests to such schemes launch the app that registered it to handle the request. "reverse domain name notation" A naming convention based on the domain name system, but one where the domain components are reversed, for example, "app.example.com" becomes "com.example.app". 4. Overview For authorizing users in native apps, the best current practice is to perform the OAuth authorization request in an external user-agent (typically the browser) rather than an embedded user-agent (such as one implemented with web-views). Previously, it was common for native apps to use embedded user-agents (commonly implemented with web-views) for OAuth authorization requests. That approach has many drawbacks, including the host app being able to copy user credentials and cookies as well as the user needing to authenticate from scratch in each app. See Section 8.12 for a deeper analysis of the drawbacks of using embedded user-agents for OAuth. Native app authorization requests that use the browser are more secure and can take advantage of the user's authentication state. Being able to use the existing authentication session in the browser enables single sign-on, as users don't need to authenticate to the authorization server each time they use a new app (unless required by the authorization server policy). Supporting authorization flows between a native app and the browser is possible without changing the OAuth protocol itself, as the OAuth authorization request and response are already defined in terms of URIs. This encompasses URIs that can be used for inter-app communication. Some OAuth server implementations that assume all clients are confidential web clients will need to add an understanding of public native app clients and the types of redirect URIs they use to support this best practice. 4.1. Authorization Flow for Native Apps Using the Browser +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ | User Device | | | | +--------------------------+ | (5) Authorization +---------------+ | | | | Code | | | | Client App |----------------------| Token | | | || Authorization | | | |. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", . [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", . [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, . [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 10.2. Informative References [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013, . [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", . [AppAuth] OpenID Connect Working Group, "AppAuth", September 2017, . [AppAuth.iOSmacOS] Wright, S., Denniss, W., et al., "AppAuth for iOS and macOS", February 2016, . [AppAuth.Android] McGinniss, I., Denniss, W., et al., "AppAuth for Android", February 2016, . [SamplesForWindows] Denniss, W., "OAuth for Apps: Samples for Windows", July 2016, . Appendix A. Server Support Checklist OAuth servers that support native apps must: 1. Support private-use URI scheme redirect URIs. This is required to support mobile operating systems. See Section 7.1. 2. Support "https" scheme redirect URIs for use with public native app clients. This is used by apps on advanced mobile operating systems that allow app-claimed "https" scheme URIs. See Section 7.2. 3. Support loopback IP redirect URIs. This is required to support desktop operating systems. See Section 7.3. 4. Not assume that native app clients can keep a secret. If secrets are distributed to multiple installs of the same native app, they should not be treated as confidential. See Section 8.5. 5. Support PKCE [RFC7636]. Required to protect authorization code grants sent to public clients over inter-app communication channels. See Section 8.1 Appendix B. Platform-Specific Implementation Details This document primarily defines best practices in a generic manner, referencing techniques commonly available in a variety of environments. This non-normative section documents implementation details of the best practice for various operating systems. The implementation details herein are considered accurate at the time of publishing but will likely change over time. It is hoped that such a change won't invalidate the generic principles in the rest of the document and that those principles should take precedence in the event of a conflict. B.1. iOS Implementation Details Apps can initiate an authorization request in the browser, without the user leaving the app, through the "SFSafariViewController" class or its successor "SFAuthenticationSession", which implement the in- app browser tab pattern. Safari can be used to handle requests on old versions of iOS without in-app browser tab functionality. To receive the authorization response, both private-use URI scheme (referred to as "custom URL scheme") redirects and claimed "https" scheme URIs (known as "Universal Links") are viable choices. Apps can claim private-use URI schemes with the "CFBundleURLTypes" key in the application's property list file, "Info.plist", and "https" scheme URIs using the Universal Links feature with an entitlement file in the app and an association file hosted on the domain. Claimed "https" scheme URIs are the preferred redirect choice on iOS 9 and above due to the ownership proof that is provided by the operating system. A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library. B.2. Android Implementation Details Apps can initiate an authorization request in the browser, without the user leaving the app, through the Android Custom Tab feature, which implements the in-app browser tab pattern. The user's default browser can be used to handle requests when no browser supports Custom Tabs. Android browser vendors should support the Custom Tabs protocol (by providing an implementation of the "CustomTabsService" class), to provide the in-app browser tab user-experience optimization to their users. Chrome is one such browser that implements Custom Tabs. To receive the authorization response, private-use URI schemes are broadly supported through Android Implicit Intents. Claimed "https" scheme redirect URIs through Android App Links are available on Android 6.0 and above. Both types of redirect URIs are registered in the application's manifest. A complete open-source sample is included in the AppAuth for Android [AppAuth.Android] library. B.3. Windows Implementation Details Both traditional and Universal Windows Platform (UWP) apps can perform authorization requests in the user's browser. Traditional apps typically use a loopback redirect to receive the authorization response, and listening on the loopback interface is allowed by default firewall rules. When creating the loopback network socket, apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent other apps binding to the same socket. UWP apps can use private-use URI scheme redirects to receive the authorization response from the browser, which will bring the app to the foreground. Known on the platform as "URI Activation", the URI scheme is limited to 39 characters in length, and it may include the "." character, making short reverse domain name based schemes (as required in Section 7.1) possible. UWP apps can alternatively use the Web Authentication Broker API in Single Sign-on (SSO) mode, which is an external user-agent designed for authorization flows. Cookies are shared between invocations of the broker but not the user's preferred browser, meaning the user will need to log in again, even if they have an active session in their browser; but the session created in the broker will be available to subsequent apps that use the broker. Personalizations the user has made to their browser, such as configuring a password manager, may not be available in the broker. To qualify as an external user-agent, the broker MUST be used in SSO mode. To use the Web Authentication Broker in SSO mode, the redirect URI must be of the form "msapp://{appSID}" where "{appSID}" is the app's security identifier (SID), which can be found in the app's registration information or by calling the "GetCurrentApplicationCallbackUri" method. While Windows enforces the URI authority on such redirects, ensuring that only the app with the matching SID can receive the response on Windows, the URI scheme could be claimed by apps on other platforms without the same authority present; thus, this redirect type should be treated similarly to private-use URI scheme redirects for security purposes. An open-source sample demonstrating these patterns is available [SamplesForWindows]. B.4. macOS Implementation Details Apps can initiate an authorization request in the user's default browser using platform APIs for opening URIs in the browser. To receive the authorization response, private-use URI schemes are a good redirect URI choice on macOS, as the user is returned right back to the app they launched the request from. These are registered in the application's bundle information property list using the "CFBundleURLSchemes" key. Loopback IP redirects are another viable option, and listening on the loopback interface is allowed by default firewall rules. A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library. B.5. Linux Implementation Details Opening the authorization request in the user's default browser requires a distro-specific command: "xdg-open" is one such tool. The loopback redirect is the recommended redirect choice for desktop apps on Linux to receive the authorization response. Apps SHOULD NOT set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options in order to prevent other apps binding to the same socket. Acknowledgements The authors would like to acknowledge the work of Marius Scurtescu and Ben Wiley Sittler, whose design for using private-use URI schemes in native app OAuth 2.0 clients at Google formed the basis of Section 7.1. The following individuals contributed ideas, feedback, and wording that shaped and formed the final specification: Andy Zmolek, Steven E. Wright, Brian Campbell, Nat Sakimura, Eric Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn Davies. Authors' Addresses William Denniss Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 United States of America Email: rfc8252@wdenniss.com URI: http://wdenniss.com/appauth John Bradley Ping Identity Phone: +1 202-630-5272 Email: rfc8252@ve7jtb.com URI: http://www.thread-safe.com/p/appauth.html