diff options
Diffstat (limited to 'doc/rfc/rfc8252.txt')
| -rw-r--r-- | doc/rfc/rfc8252.txt | 1179 |
1 files changed, 1179 insertions, 0 deletions
diff --git a/doc/rfc/rfc8252.txt b/doc/rfc/rfc8252.txt new file mode 100644 index 0000000..d3f7783 --- /dev/null +++ b/doc/rfc/rfc8252.txt @@ -0,0 +1,1179 @@ + + + + + + +Internet Engineering Task Force (IETF) W. Denniss +Request for Comments: 8252 Google +BCP: 212 J. Bradley +Updates: 6749 Ping Identity +Category: Best Current Practice October 2017 +ISSN: 2070-1721 + + + OAuth 2.0 for Native Apps + +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. + + + + + +Denniss & Bradley Best Current Practice [Page 1] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +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 + + + + + + + + + + + + +Denniss & Bradley Best Current Practice [Page 2] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +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. + + + +Denniss & Bradley Best Current Practice [Page 3] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + "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 + + + +Denniss & Bradley Best Current Practice [Page 4] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + 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 | + | | |<----------------------| Endpoint | + | +--------------------------+ | (6) Access Token, | | + | | ^ | Refresh Token +---------------+ + | | | | + | | | | + | | (1) | (4) | + | | Authorizat- | Authoriza- | + | | ion Request | tion Code | + | | | | + | | | | + | v | | + | +---------------------------+ | (2) Authorization +---------------+ + | | | | Request | | + | | Browser |--------------------->| Authorization | + | | |<---------------------| Endpoint | + | +---------------------------+ | (3) Authorization | | + | | Code +---------------+ + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ + + Figure 1: Native App Authorization via an External User-Agent + + + + +Denniss & Bradley Best Current Practice [Page 5] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + Figure 1 illustrates the interaction between a native app and the + browser to authorize the user. + + (1) Client app opens a browser tab with the authorization request. + + (2) Authorization endpoint receives the authorization request, + authenticates the user, and obtains authorization. + Authenticating the user may involve chaining to other + authentication systems. + + (3) Authorization server issues an authorization code to the + redirect URI. + + (4) Client receives the authorization code from the redirect URI. + + (5) Client app presents the authorization code at the token + endpoint. + + (6) Token endpoint validates the authorization code and issues the + tokens requested. + +5. Using Inter-App URI Communication for OAuth + + Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate + the authorization request and return the authorization response to + the requesting website, URIs can be used by native apps to initiate + the authorization request in the device's browser and return the + response to the requesting native app. + + By adopting the same methods used on the web for OAuth, benefits seen + in the web context like the usability of a single sign-on session and + the security of a separate authentication context are likewise gained + in the native app context. Reusing the same approach also reduces + the implementation complexity and increases interoperability by + relying on standards-based web flows that are not specific to a + particular platform. + + To conform to this best practice, native apps MUST use an external + user-agent to perform OAuth authorization requests. This is achieved + by opening the authorization request in the browser (detailed in + Section 6) and using a redirect URI that will return the + authorization response back to the native app (defined in Section 7). + + + + + + + + + +Denniss & Bradley Best Current Practice [Page 6] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +6. Initiating the Authorization Request from a Native App + + Native apps needing user authorization create an authorization + request URI with the authorization code grant type per Section 4.1 of + OAuth 2.0 [RFC6749], using a redirect URI capable of being received + by the native app. + + The function of the redirect URI for a native app authorization + request is similar to that of a web-based authorization request. + Rather than returning the authorization response to the OAuth + client's server, the redirect URI used by a native app returns the + response to the app. Several options for a redirect URI that will + return the authorization response to the native app in different + platforms are documented in Section 7. Any redirect URI that allows + the app to receive the URI and inspect its parameters is viable. + + Public native app clients MUST implement the Proof Key for Code + Exchange (PKCE [RFC7636]) extension to OAuth, and authorization + servers MUST support PKCE for such clients, for the reasons detailed + in Section 8.1. + + After constructing the authorization request URI, the app uses + platform-specific APIs to open the URI in an external user-agent. + Typically, the external user-agent used is the default browser, that + is, the application configured for handling "http" and "https" scheme + URIs on the system; however, different browser selection criteria and + other categories of external user-agents MAY be used. + + This best practice focuses on the browser as the RECOMMENDED external + user-agent for native apps. An external user-agent designed + specifically for user authorization and capable of processing + authorization requests and responses like a browser MAY also be used. + Other external user-agents, such as a native app provided by the + authorization server may meet the criteria set out in this best + practice, including using the same redirection URI properties, but + their use is out of scope for this specification. + + Some platforms support a browser feature known as "in-app browser + tabs", where an app can present a tab of the browser within the app + context without switching apps, but still retain key benefits of the + browser such as a shared authentication state and security context. + On platforms where they are supported, it is RECOMMENDED, for + usability reasons, that apps use in-app browser tabs for the + authorization request. + + + + + + + +Denniss & Bradley Best Current Practice [Page 7] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +7. Receiving the Authorization Response in a Native App + + There are several redirect URI options available to native apps for + receiving the authorization response from the browser, the + availability and user experience of which varies by platform. + + To fully support this best practice, authorization servers MUST offer + at least the three redirect URI options described in the following + subsections to native apps. Native apps MAY use whichever redirect + option suits their needs best, taking into account platform-specific + implementation details. + +7.1. Private-Use URI Scheme Redirection + + Many mobile and desktop computing platforms support inter-app + communication via URIs by allowing apps to register private-use URI + schemes (sometimes colloquially referred to as "custom URL schemes") + like "com.example.app". When the browser or another app attempts to + load a URI with a private-use URI scheme, the app that registered it + is launched to handle the request. + + To perform an OAuth 2.0 authorization request with a private-use URI + scheme redirect, the native app launches the browser with a standard + authorization request, but one where the redirection URI utilizes a + private-use URI scheme it registered with the operating system. + + When choosing a URI scheme to associate with the app, apps MUST use a + URI scheme based on a domain name under their control, expressed in + reverse order, as recommended by Section 3.8 of [RFC7595] for + private-use URI schemes. + + For example, an app that controls the domain name "app.example.com" + can use "com.example.app" as their scheme. Some authorization + servers assign client identifiers based on domain names, for example, + "client1234.usercontent.example.net", which can also be used as the + domain name for the scheme when reversed in the same manner. A + scheme such as "myapp", however, would not meet this requirement, as + it is not based on a domain name. + + When there are multiple apps by the same publisher, care must be + taken so that each scheme is unique within that group. On platforms + that use app identifiers based on reverse-order domain names, those + identifiers can be reused as the private-use URI scheme for the OAuth + redirect to help avoid this problem. + + + + + + + +Denniss & Bradley Best Current Practice [Page 8] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + Following the requirements of Section 3.2 of [RFC3986], as there is + no naming authority for private-use URI scheme redirects, only a + single slash ("/") appears after the scheme component. A complete + example of a redirect URI utilizing a private-use URI scheme is: + + com.example.app:/oauth2redirect/example-provider + + When the authorization server completes the request, it redirects to + the client's redirection URI as it would normally. As the + redirection URI uses a private-use URI scheme, it results in the + operating system launching the native app, passing in the URI as a + launch parameter. Then, the native app uses normal processing for + the authorization response. + +7.2. Claimed "https" Scheme URI Redirection + + Some operating systems allow apps to claim "https" scheme [RFC7230] + URIs in the domains they control. When the browser encounters a + claimed URI, instead of the page being loaded in the browser, the + native app is launched with the URI supplied as a launch parameter. + + Such URIs can be used as redirect URIs by native apps. They are + indistinguishable to the authorization server from a regular web- + based client redirect URI. An example is: + + https://app.example.com/oauth2redirect/example-provider + + As the redirect URI alone is not enough to distinguish public native + app clients from confidential web clients, it is REQUIRED in + Section 8.4 that the client type be recorded during client + registration to enable the server to determine the client type and + act accordingly. + + App-claimed "https" scheme redirect URIs have some advantages + compared to other native app redirect options in that the identity of + the destination app is guaranteed to the authorization server by the + operating system. For this reason, native apps SHOULD use them over + the other options where possible. + +7.3. Loopback Interface Redirection + + Native apps that are able to open a port on the loopback network + interface without needing special permissions (typically, those on + desktop operating systems) can use the loopback interface to receive + the OAuth redirect. + + Loopback redirect URIs use the "http" scheme and are constructed with + the loopback IP literal and whatever port the client is listening on. + + + +Denniss & Bradley Best Current Practice [Page 9] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + That is, "http://127.0.0.1:{port}/{path}" for IPv4, and + "http://[::1]:{port}/{path}" for IPv6. An example redirect using the + IPv4 loopback interface with a randomly assigned port: + + http://127.0.0.1:51004/oauth2redirect/example-provider + + An example redirect using the IPv6 loopback interface with a randomly + assigned port: + + http://[::1]:61023/oauth2redirect/example-provider + + The authorization server MUST allow any port to be specified at the + time of the request for loopback IP redirect URIs, to accommodate + clients that obtain an available ephemeral port from the operating + system at the time of the request. + + Clients SHOULD NOT assume that the device supports a particular + version of the Internet Protocol. It is RECOMMENDED that clients + attempt to bind to the loopback interface using both IPv4 and IPv6 + and use whichever is available. + +8. Security Considerations + +8.1. Protecting the Authorization Code + + The redirect URI options documented in Section 7 share the benefit + that only a native app on the same device or the app's own website + can receive the authorization code, which limits the attack surface. + However, code interception by a different native app running on the + same device may be possible. + + A limitation of using private-use URI schemes for redirect URIs is + that multiple apps can typically register the same scheme, which + makes it indeterminate as to which app will receive the authorization + code. Section 1 of PKCE [RFC7636] details how this limitation can be + used to execute a code interception attack. + + Loopback IP-based redirect URIs may be susceptible to interception by + other apps accessing the same loopback interface on some operating + systems. + + App-claimed "https" scheme redirects are less susceptible to URI + interception due to the presence of the URI authority, but the app is + still a public client; further, the URI is sent using the operating + system's URI dispatch handler with unknown security properties. + + + + + + +Denniss & Bradley Best Current Practice [Page 10] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + The PKCE [RFC7636] protocol was created specifically to mitigate this + attack. It is a proof-of-possession extension to OAuth 2.0 that + protects the authorization code from being used if it is intercepted. + To provide protection, this extension has the client generate a + secret verifier; it passes a hash of this verifier in the initial + authorization request, and must present the unhashed verifier when + redeeming the authorization code. An app that intercepted the + authorization code would not be in possession of this secret, + rendering the code useless. + + Section 6 requires that both clients and servers use PKCE for public + native app clients. Authorization servers SHOULD reject + authorization requests from native apps that don't use PKCE by + returning an error message, as defined in Section 4.4.1 of PKCE + [RFC7636]. + +8.2. OAuth Implicit Grant Authorization Flow + + The OAuth 2.0 implicit grant authorization flow (defined in + Section 4.2 of OAuth 2.0 [RFC6749]) generally works with the practice + of performing the authorization request in the browser and receiving + the authorization response via URI-based inter-app communication. + However, as the implicit flow cannot be protected by PKCE [RFC7636] + (which is required in Section 8.1), the use of the Implicit Flow with + native apps is NOT RECOMMENDED. + + Access tokens granted via the implicit flow also cannot be refreshed + without user interaction, making the authorization code grant flow -- + which can issue refresh tokens -- the more practical option for + native app authorizations that require refreshing of access tokens. + +8.3. Loopback Redirect Considerations + + Loopback interface redirect URIs use the "http" scheme (i.e., without + Transport Layer Security (TLS)). This is acceptable for loopback + interface redirect URIs as the HTTP request never leaves the device. + + Clients should open the network port only when starting the + authorization request and close it once the response is returned. + + Clients should listen on the loopback network interface only, in + order to avoid interference by other network actors. + + While redirect URIs using localhost (i.e., + "http://localhost:{port}/{path}") function similarly to loopback IP + redirects described in Section 7.3, the use of localhost is NOT + RECOMMENDED. Specifying a redirect URI with the loopback IP literal + rather than localhost avoids inadvertently listening on network + + + +Denniss & Bradley Best Current Practice [Page 11] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + interfaces other than the loopback interface. It is also less + susceptible to client-side firewalls and misconfigured host name + resolution on the user's device. + +8.4. Registration of Native App Clients + + Except when using a mechanism like Dynamic Client Registration + [RFC7591] to provision per-instance secrets, native apps are + classified as public clients, as defined by Section 2.1 of OAuth 2.0 + [RFC6749]; they MUST be registered with the authorization server as + such. Authorization servers MUST record the client type in the + client registration details in order to identify and process requests + accordingly. + + Authorization servers MUST require clients to register their complete + redirect URI (including the path component) and reject authorization + requests that specify a redirect URI that doesn't exactly match the + one that was registered; the exception is loopback redirects, where + an exact match is required except for the port URI component. + + For private-use URI scheme-based redirects, authorization servers + SHOULD enforce the requirement in Section 7.1 that clients use + schemes that are reverse domain name based. At a minimum, any + private-use URI scheme that doesn't contain a period character (".") + SHOULD be rejected. + + In addition to the collision-resistant properties, requiring a URI + scheme based on a domain name that is under the control of the app + can help to prove ownership in the event of a dispute where two apps + claim the same private-use URI scheme (where one app is acting + maliciously). For example, if two apps claimed "com.example.app", + the owner of "example.com" could petition the app store operator to + remove the counterfeit app. Such a petition is harder to prove if a + generic URI scheme was used. + + Authorization servers MAY request the inclusion of other platform- + specific information, such as the app package or bundle name, or + other information that may be useful for verifying the calling app's + identity on operating systems that support such functions. + +8.5. Client Authentication + + Secrets that are statically included as part of an app distributed to + multiple users should not be treated as confidential secrets, as one + user may inspect their copy and learn the shared secret. For this + reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT + RECOMMENDED for authorization servers to require client + + + + +Denniss & Bradley Best Current Practice [Page 12] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + authentication of public native apps clients using a shared secret, + as this serves little value beyond client identification which is + already provided by the "client_id" request parameter. + + Authorization servers that still require a statically included shared + secret for native app clients MUST treat the client as a public + client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not + accept the secret as proof of the client's identity. Without + additional measures, such clients are subject to client impersonation + (see Section 8.6). + +8.6. Client Impersonation + + As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization + server SHOULD NOT process authorization requests automatically + without user consent or interaction, except when the identity of the + client can be assured. This includes the case where the user has + previously approved an authorization request for a given client id -- + unless the identity of the client can be proven, the request SHOULD + be processed as if no previous request had been approved. + + Measures such as claimed "https" scheme redirects MAY be accepted by + authorization servers as identity proof. Some operating systems may + offer alternative platform-specific identity features that MAY be + accepted, as appropriate. + +8.7. Fake External User-Agents + + The native app that is initiating the authorization request has a + large degree of control over the user interface and can potentially + present a fake external user-agent, that is, an embedded user-agent + made to appear as an external user-agent. + + When all good actors are using external user-agents, the advantage is + that it is possible for security experts to detect bad actors, as + anyone faking an external user-agent is provably bad. On the other + hand, if good and bad actors alike are using embedded user-agents, + bad actors don't need to fake anything, making them harder to detect. + Once a malicious app is detected, it may be possible to use this + knowledge to blacklist the app's signature in malware scanning + software, take removal action (in the case of apps distributed by app + stores) and other steps to reduce the impact and spread of the + malicious app. + + Authorization servers can also directly protect against fake external + user-agents by requiring an authentication factor only available to + true external user-agents. + + + + +Denniss & Bradley Best Current Practice [Page 13] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + Users who are particularly concerned about their security when using + in-app browser tabs may also take the additional step of opening the + request in the full browser from the in-app browser tab and complete + the authorization there, as most implementations of the in-app + browser tab pattern offer such functionality. + +8.8. Malicious External User-Agents + + If a malicious app is able to configure itself as the default handler + for "https" scheme URIs in the operating system, it will be able to + intercept authorization requests that use the default browser and + abuse this position of trust for malicious ends such as phishing the + user. + + This attack is not confined to OAuth; a malicious app configured in + this way would present a general and ongoing risk to the user beyond + OAuth usage by native apps. Many operating systems mitigate this + issue by requiring an explicit user action to change the default + handler for "http" and "https" scheme URIs. + +8.9. Cross-App Request Forgery Protections + + Section 5.3.5 of [RFC6819] recommends using the "state" parameter to + link client requests and responses to prevent CSRF (Cross-Site + Request Forgery) attacks. + + To mitigate CSRF-style attacks over inter-app URI communication + channels (so called "cross-app request forgery"), it is similarly + RECOMMENDED that native apps include a high-entropy secure random + number in the "state" parameter of the authorization request and + reject any incoming authorization responses without a state value + that matches a pending outgoing authorization request. + +8.10. Authorization Server Mix-Up Mitigation + + To protect against a compromised or malicious authorization server + attacking another authorization server used by the same app, it is + REQUIRED that a unique redirect URI is used for each authorization + server used by the app (for example, by varying the path component), + and that authorization responses are rejected if the redirect URI + they were received on doesn't match the redirect URI in an outgoing + authorization request. + + The native app MUST store the redirect URI used in the authorization + request with the authorization session data (i.e., along with "state" + and other related data) and MUST verify that the URI on which the + authorization response was received exactly matches it. + + + + +Denniss & Bradley Best Current Practice [Page 14] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + The requirement of Section 8.4, specifically that authorization + servers reject requests with URIs that don't match what was + registered, is also required to prevent such attacks. + +8.11. Non-Browser External User-Agents + + This best practice recommends a particular type of external user- + agent: the user's browser. Other external user-agent patterns may + also be viable for secure and usable OAuth. This document makes no + comment on those patterns. + +8.12. Embedded User-Agents + + Section 9 of OAuth 2.0 [RFC6749] documents two approaches for native + apps to interact with the authorization endpoint. This best current + practice requires that native apps MUST NOT use embedded user-agents + to perform authorization requests and allows that authorization + endpoints MAY take steps to detect and block authorization requests + in embedded user-agents. The security considerations for these + requirements are detailed herein. + + Embedded user-agents are an alternative method for authorizing native + apps. These embedded user-agents are unsafe for use by third parties + to the authorization server by definition, as the app that hosts the + embedded user-agent can access the user's full authentication + credential, not just the OAuth authorization grant that was intended + for the app. + + In typical web-view-based implementations of embedded user-agents, + the host application can record every keystroke entered in the login + form to capture usernames and passwords, automatically submit forms + to bypass user consent, and copy session cookies and use them to + perform authenticated actions as the user. + + Even when used by trusted apps belonging to the same party as the + authorization server, embedded user-agents violate the principle of + least privilege by having access to more powerful credentials than + they need, potentially increasing the attack surface. + + Encouraging users to enter credentials in an embedded user-agent + without the usual address bar and visible certificate validation + features that browsers have makes it impossible for the user to know + if they are signing in to the legitimate site; even when they are, it + trains them that it's OK to enter credentials without validating the + site first. + + + + + + +Denniss & Bradley Best Current Practice [Page 15] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + Aside from the security concerns, embedded user-agents do not share + the authentication state with other apps or the browser, requiring + the user to log in for every authorization request, which is often + considered an inferior user experience. + +9. IANA Considerations + + This document does not require any IANA actions. + + Section 7.1 specifies how private-use URI schemes are used for inter- + app communication in OAuth protocol flows. This document requires in + Section 7.1 that such schemes are based on domain names owned or + assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per + Section 6 of [RFC7595], registration of domain-based URI schemes with + IANA is not required. + +10. References + +10.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, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + <https://www.rfc-editor.org/info/rfc3986>. + + [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", + RFC 6749, DOI 10.17487/RFC6749, October 2012, + <https://www.rfc-editor.org/info/rfc6749>. + + [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Message Syntax and Routing", + RFC 7230, DOI 10.17487/RFC7230, June 2014, + <https://www.rfc-editor.org/info/rfc7230>. + + [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines + and Registration Procedures for URI Schemes", BCP 35, + RFC 7595, DOI 10.17487/RFC7595, June 2015, + <https://www.rfc-editor.org/info/rfc7595>. + + [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, + <https://www.rfc-editor.org/info/rfc7636>. + + + +Denniss & Bradley Best Current Practice [Page 16] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + +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, + <https://www.rfc-editor.org/info/rfc6819>. + + [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and + P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", + RFC 7591, DOI 10.17487/RFC7591, July 2015, + <https://www.rfc-editor.org/info/rfc7591>. + + [AppAuth] OpenID Connect Working Group, "AppAuth", September 2017, + <https://openid.net/code/AppAuth>. + + [AppAuth.iOSmacOS] + Wright, S., Denniss, W., et al., "AppAuth for iOS and + macOS", February 2016, + <https://openid.net/code/AppAuth-iOS>. + + [AppAuth.Android] + McGinniss, I., Denniss, W., et al., "AppAuth for Android", + February 2016, <https://openid.net/code/AppAuth-Android>. + + [SamplesForWindows] + Denniss, W., "OAuth for Apps: Samples for Windows", July + 2016, + <https://openid.net/code/sample-oauth-apps-for-windows>. + + + + + + + + + + + + + + + + + + + +Denniss & Bradley Best Current Practice [Page 17] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +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 + + + +Denniss & Bradley Best Current Practice [Page 18] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + 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 + + + + + +Denniss & Bradley Best Current Practice [Page 19] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + + 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. + + + + + + + +Denniss & Bradley Best Current Practice [Page 20] + +RFC 8252 OAuth 2.0 for Native Apps October 2017 + + +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 + + + + + + +Denniss & Bradley Best Current Practice [Page 21] + |