draft-ietf-oauth-native-apps-11.txt   draft-ietf-oauth-native-apps-12.txt 
OAuth Working Group W. Denniss OAuth Working Group W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Best Current Practice J. Bradley Updates: 6749 (if approved) J. Bradley
Expires: November 20, 2017 Ping Identity Intended status: Best Current Practice Ping Identity
May 19, 2017 Expires: December 11, 2017 June 9, 2017
OAuth 2.0 for Native Apps OAuth 2.0 for Native Apps
draft-ietf-oauth-native-apps-11 draft-ietf-oauth-native-apps-12
Abstract Abstract
OAuth 2.0 authorization requests from native apps should only be made OAuth 2.0 authorization requests from native apps should only be made
through external user-agents, primarily the user's browser. This through external user-agents, primarily the user's browser. This
specification details the security and usability reasons why this is specification details the security and usability reasons why this is
the case, and how native apps and authorization servers can implement the case, and how native apps and authorization servers can implement
this best practice. this best practice.
Status of This Memo Status of This Memo
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 20, 2017. This Internet-Draft will expire on December 11, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 27
7.1. Private-use URI Scheme Redirection . . . . . . . . . . . 8 7.1. Private-use URI Scheme Redirection . . . . . . . . . . . 8
7.2. Claimed HTTPS URI Redirection . . . . . . . . . . . . . . 9 7.2. Claimed HTTPS URI Redirection . . . . . . . . . . . . . . 9
7.3. Loopback Interface Redirection . . . . . . . . . . . . . 9 7.3. Loopback Interface Redirection . . . . . . . . . . . . . 9
8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10
8.1. Protecting the Authorization Code . . . . . . . . . . . . 10 8.1. Protecting the Authorization Code . . . . . . . . . . . . 10
8.2. OAuth Implicit Grant Authorization Flow . . . . . . . . . 11 8.2. OAuth Implicit Grant Authorization Flow . . . . . . . . . 11
8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11
8.4. Registration of Native App Clients . . . . . . . . . . . 11 8.4. Registration of Native App Clients . . . . . . . . . . . 11
8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12 8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12
8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 12 8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 12
8.7. Phishability of In-App Browser Tabs . . . . . . . . . . . 13 8.7. Fake External User-Agent . . . . . . . . . . . . . . . . 13
8.8. Cross-App Request Forgery Protections . . . . . . . . . . 13 8.8. Malicious External User-Agent . . . . . . . . . . . . . . 13
8.9. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 8.9. Cross-App Request Forgery Protections . . . . . . . . . . 14
8.10. Non-Browser External User-Agents . . . . . . . . . . . . 14 8.10. Authorization Server Mix-Up Mitigation . . . . . . . . . 14
8.11. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14 8.11. Non-Browser External User-Agents . . . . . . . . . . . . 14
8.12. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.1. Normative References . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 16
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 17
Appendix B. Operating System Specific Implementation Details . . 17 Appendix B. Operating System Specific Implementation Details . . 17
B.1. iOS Implementation Details . . . . . . . . . . . . . . . 17 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 18
B.2. Android Implementation Details . . . . . . . . . . . . . 18 B.2. Android Implementation Details . . . . . . . . . . . . . 18
B.3. Windows Implementation Details . . . . . . . . . . . . . 18 B.3. Windows Implementation Details . . . . . . . . . . . . . 19
B.4. macOS Implementation Details . . . . . . . . . . . . . . 19 B.4. macOS Implementation Details . . . . . . . . . . . . . . 19
B.5. Linux Implementation Details . . . . . . . . . . . . . . 19 B.5. Linux Implementation Details . . . . . . . . . . . . . . 20
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction 1. Introduction
The OAuth 2.0 [RFC6749] authorization framework documents two The OAuth 2.0 [RFC6749] authorization framework documents two
approaches in Section 9 for native apps to interact with the approaches in Section 9 for native apps to interact with the
authorization endpoint: an embedded user-agent, and an external user- authorization endpoint: an embedded user-agent, and an external user-
agent. agent.
This best current practice requires that only external user-agents This best current practice requires that only external user-agents
like the browser are used for OAuth by native apps. It documents how like the browser are used for OAuth by native apps. It documents how
native apps can implement authorization flows using the browser as native apps can implement authorization flows using the browser as
the preferred external user-agent, and the requirements for the preferred external user-agent, and the requirements for
authorization servers to support such usage. authorization servers to support such usage.
This practice is also known as the AppAuth pattern, in reference to This practice is also known as the AppAuth pattern, in reference to
open source libraries that implement it. open source libraries [AppAuth] that implement it.
2. Notational Conventions 2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in Key "OPTIONAL" in this document are to be interpreted as described in Key
words for use in RFCs to Indicate Requirement Levels [RFC2119]. If words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
these words are used without being spelled in uppercase then they are these words are used without being spelled in uppercase then they are
to be interpreted with their normal natural language meanings. to be interpreted with their normal natural language meanings.
skipping to change at page 3, line 40 skipping to change at page 3, line 42
context only. Apps implemented using web-based technology but context only. Apps implemented using web-based technology but
distributed as a native app, so-called hybrid apps, are considered distributed as a native app, so-called hybrid apps, are considered
equivalent to native apps for the purpose of this specification. equivalent to native apps for the purpose of this specification.
"app" In this document, "app" means a "native app" unless further "app" In this document, "app" means a "native app" unless further
specified. specified.
"app store" An ecommerce store where users can download and purchase "app store" An ecommerce store where users can download and purchase
apps. apps.
"OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. "OAuth" In this document, OAuth refers to the OAuth 2.0
Authorization Framework [RFC6749].
"external user-agent" A user-agent capable of handling the "external user-agent" A user-agent capable of handling the
authorization request that is a separate entity or security domain authorization request that is a separate entity or security domain
to the native app making the request (such as a browser), such to the native app making the request (such as a browser), such
that the app cannot access the cookie storage, nor inspect or that the app cannot access the cookie storage, nor inspect or
modify page content. modify page content.
"embedded user-agent" A user-agent hosted inside the native app "embedded user-agent" A user-agent hosted inside the native app
itself (such as via a web-view), with which the app has control itself (such as via a web-view), with which the app has control
over to the extent it is capable of accessing the cookie storage over to the extent it is capable of accessing the cookie storage
skipping to change at page 4, line 27 skipping to change at page 4, line 32
"claimed HTTPS URI" Some platforms allow apps to claim a HTTPS "claimed HTTPS URI" Some platforms allow apps to claim a HTTPS
scheme URI after proving ownership of the domain name. URIs scheme URI after proving ownership of the domain name. URIs
claimed in such a way are then opened in the app instead of the claimed in such a way are then opened in the app instead of the
browser. browser.
"private-use URI scheme" A private-use URI scheme defined by the app "private-use URI scheme" A private-use URI scheme defined by the app
and registered with the operating system. URI requests to such and registered with the operating system. URI requests to such
schemes trigger the app which registered it to be launched to schemes trigger the app which registered it to be launched to
handle the request. handle the request.
"web-view" A web browser UI component that can be embedded in apps "web-view" A web browser UI (user interface) component that can be
to render web pages, used to create embedded user-agents. embedded in apps to render web pages, used to create embedded
user-agents.
"reverse domain name notation" A naming convention based on the "reverse domain name notation" A naming convention based on the
domain name system, but where the domain components are reversed, domain name system, but where the domain components are reversed,
for example "app.example.com" becomes "com.example.app". for example "app.example.com" becomes "com.example.app".
4. Overview 4. Overview
The best current practice for authorizing users in native apps is to The best current practice for authorizing users in native apps is to
perform the OAuth authorization request in an external user-agent perform the OAuth authorization request in an external user-agent
(typically the browser), rather than an embedded user-agent (such as (typically the browser), rather than an embedded user-agent (such as
one implemented with web-views). one implemented with web-views).
Previously it was common for native apps to use embedded user-agents Previously it was common for native apps to use embedded user-agents
(commonly implemented with web-views) for OAuth authorization (commonly implemented with web-views) for OAuth authorization
requests. That approach has many drawbacks, including the host app requests. That approach has many drawbacks, including the host app
being able to copy user credentials and cookies, and the user needing being able to copy user credentials and cookies, and the user needing
to authenticate from scratch in each app. See Section 8.11 for a to authenticate from scratch in each app. See Section 8.12 for a
deeper analysis of using embedded user-agents for OAuth. deeper analysis of using embedded user-agents for OAuth.
Native app authorization requests that use the browser are more Native app authorization requests that use the browser are more
secure and can take advantage of the user's authentication state. secure and can take advantage of the user's authentication state.
Being able to use the existing authentication session in the browser Being able to use the existing authentication session in the browser
enables single sign-on, as users don't need to authenticate to the 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 authorization server each time they use a new app (unless required by
authorization server policy). authorization server policy).
Supporting authorization flows between a native app and the browser Supporting authorization flows between a native app and the browser
is possible without changing the OAuth protocol itself, as the is possible without changing the OAuth protocol itself, as the
authorization request and response are already defined in terms of authorization request and response are already defined in terms of
URIs, which encompasses URIs that can be used for inter-app URIs, which encompasses URIs that can be used for inter-app
communication. Some OAuth server implementations that assume all communication. Some OAuth server implementations that assume all
clients are confidential web-clients will need to add an clients are confidential web-clients will need to add an
understanding of public native app clients and the types of redirect understanding of public native app clients and the types of redirect
URIs they use to support this best practice. URIs they use to support this best practice.
4.1. Authorization Flow for Native Apps Using the Browser 4.1. Authorization Flow for Native Apps Using the Browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
| User Device | | User Device |
| | | |
| +---------------------------+ | +-----------+ | +--------------------------+ | (5) Authorization +---------------+
| | | | (5) Authz Code | | | | | | Code | |
| | Client App |----------------------->| Token | | | Client App |---------------------->| Token |
| | |<-----------------------| Endpoint | | | |<----------------------| Endpoint |
| +---------------------------+ | (6) Access Token, | | | +--------------------------+ | (6) Access Token, | |
| | ^ | Refresh Token +-----------+ | | ^ | Refresh Token +---------------+
| | | | | | | |
| | | | | | | |
| | (1) | (4) | | | (1) | (4) |
| | Authz | Authz | | | Authorizat- | Authoriza- |
| | Request | Code | | | ion Request | tion Code |
| | | | | | | |
| | | | | | | |
| v | | | v | |
| +---------------------------+ | +---------------+ | +---------------------------+ | (2) Authorization +---------------+
| | | | (2) Authz Request | | | | | | Request | |
| | Browser |--------------------->| Authorization | | | Browser |--------------------->| Authorization |
| | |<---------------------| Endpoint | | | |<---------------------| Endpoint |
| +---------------------------+ | (3) Authz Code | | | +---------------------------+ | (3) Authorization | |
| | +---------------+ | | Code +---------------+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
Figure 1: Native App Authorization via External User-agent Figure 1: Native App Authorization via External User-agent
Figure 1 illustrates the interaction of the native app with a browser Figure 1 illustrates the interaction of the native app with a browser
external user-agent to authorize the user. external user-agent to authorize the user.
(1) The client app opens a browser tab with the authorization (1) The client app opens a browser tab with the authorization
request. request.
(2) Authorization endpoint receives the authorization request, (2) Authorization endpoint receives the authorization request,
skipping to change at page 7, line 47 skipping to change at page 7, line 49
On platforms where they are supported, it is RECOMMENDED for On platforms where they are supported, it is RECOMMENDED for
usability reasons that apps use in-app browser tabs for the usability reasons that apps use in-app browser tabs for the
authorization request. authorization request.
7. Receiving the Authorization Response in a Native App 7. Receiving the Authorization Response in a Native App
There are several redirect URI options available to native apps for There are several redirect URI options available to native apps for
receiving the authorization response from the browser, the receiving the authorization response from the browser, the
availability and user experience of which varies by platform. availability and user experience of which varies by platform.
To fully support this best practice, authorization servers MUST To fully support this best practice, authorization servers MUST offer
support the following three redirect URI options. Native apps MAY at least the following three redirect URI options to native apps.
use whichever redirect option suits their needs best, taking into Native apps MAY use whichever redirect option suits their needs best,
account platform specific implementation details. taking into account platform specific implementation details.
7.1. Private-use URI Scheme Redirection 7.1. Private-use URI Scheme Redirection
Many mobile and desktop computing platforms support inter-app Many mobile and desktop computing platforms support inter-app
communication via URIs by allowing apps to register private-use URI communication via URIs by allowing apps to register private-use URI
schemes (sometimes colloquially referred to as custom URL schemes) schemes (sometimes colloquially referred to as custom URL schemes)
like "com.example.app". When the browser or another app attempts to like "com.example.app". When the browser or another app attempts to
load a URI with a custom scheme, the app that registered it is load a URI with a custom scheme, the app that registered it is
launched to handle the request. launched to handle the request.
skipping to change at page 9, line 7 skipping to change at page 9, line 7
When the authentication server completes the request, it redirects to When the authentication server completes the request, it redirects to
the client's redirection URI as it would normally. As the the client's redirection URI as it would normally. As the
redirection URI uses a custom scheme it results in the operating redirection URI uses a custom scheme it results in the operating
system launching the native app, passing in the URI as a launch system launching the native app, passing in the URI as a launch
parameter. The native app then processes the authorization response parameter. The native app then processes the authorization response
like normal. like normal.
7.2. Claimed HTTPS URI Redirection 7.2. Claimed HTTPS URI Redirection
Some operating systems allow apps to claim HTTPS scheme URIs in Some operating systems allow apps to claim HTTPS scheme [RFC7230]
domains they control. When the browser encounters a claimed URI, URIs in domains they control. When the browser encounters a claimed
instead of the page being loaded in the browser, the native app is URI, instead of the page being loaded in the browser, the native app
launched with the URI supplied as a launch parameter. is launched with the URI supplied as a launch parameter.
Such URIs can be used as OAuth redirect URIs. They are Such URIs can be used as redirect URIs by native apps. They are
indistinguishable from OAuth redirects of web-based clients. An indistinguishable to the authorization server from a regular web-
example is: based client redirect URI. An example is:
https://app.example.com/oauth2redirect/example-provider https://app.example.com/oauth2redirect/example-provider
App-claimed HTTPS redirect URIs have some advantages in that the As the redirect URI alone is not enough to distinguish public native
identity of the destination app is guaranteed by the operating app clients from confidential web clients, it is REQUIRED in
system. For this reason, they SHOULD be used in preference to the Section 8.4 that the client type be recorded during client
other redirect options for native apps where possible. registration to enable the server to determine the client type and
act accordingly.
Claimed HTTPS redirect URIs function as normal HTTPS redirects from App-claimed HTTPS redirect URIs have some advantages compared to
the perspective of the authorization server, though as stated in other native app redirect options in that the identity of the
Section 8.4, it is REQUIRED that the authorization server is able to destination app is guaranteed to the authorization server by the
distinguish between public native app clients that use app-claimed operating system. For this reason, native apps SHOULD use them over
HTTPS redirect URIs and confidential web clients. the other options where possible.
7.3. Loopback Interface Redirection 7.3. Loopback Interface Redirection
Native apps that are able to open a port on the loopback network Native apps that are able to open a port on the loopback network
interface without needing special permissions (typically, those on interface without needing special permissions (typically, those on
desktop operating systems) can use the loopback interface to receive desktop operating systems) can use the loopback interface to receive
the OAuth redirect. the OAuth redirect.
Loopback redirect URIs use the HTTP scheme and are constructed with Loopback redirect URIs use the HTTP scheme and are constructed with
the loopback IP literal and whatever port the client is listening on. the loopback IP literal and whatever port the client is listening on.
skipping to change at page 10, line 17 skipping to change at page 10, line 19
bind to the loopback interface using both IPv4 and IPv6, and use bind to the loopback interface using both IPv4 and IPv6, and use
whichever is available. whichever is available.
8. Security Considerations 8. Security Considerations
8.1. Protecting the Authorization Code 8.1. Protecting the Authorization Code
The redirect URI options documented in Section 7 share the benefit The redirect URI options documented in Section 7 share the benefit
that only a native app on the same device can receive the that only a native app on the same device can receive the
authorization code which limits the attack surface, however code authorization code which limits the attack surface, however code
interception by a native app other than the intended app may still be interception by a different native app running on the same device may
possible. be possible.
A limitation of using private-use URI schemes for redirect URIs is A limitation of using private-use URI schemes for redirect URIs is
that multiple apps can typically register the same scheme, which that multiple apps can typically register the same scheme, which
makes it indeterminate as to which app will receive the Authorization makes it indeterminate as to which app will receive the Authorization
Code. PKCE [RFC7636] details how this limitation can be used to Code. Section 1 of PKCE [RFC7636] details how this limitation can be
execute a code interception attack (see Figure 1). used to execute a code interception attack.
Loopback IP based redirect URIs may be susceptible to interception by Loopback IP based redirect URIs may be susceptible to interception by
other apps listening on the same loopback interface. other apps accessing the same loopback interface on some operating
systems.
As most forms of inter-app URI-based communication send data over App-claimed HTTPS redirects are less susceptible to URI interception
insecure local channels, eavesdropping and interception of the due to the presence of the URI authority, but they are still public
authorization response is a risk for native apps. App-claimed HTTPS clients and the URI is sent using the operating system's URI dispatch
redirects are hardened against this type of attack due to the handler with unknown security properties.
presence of the URI authority, but they are still public clients and
the URI is still transmitted over local channels with unknown
security properties.
The Proof Key for Code Exchange by OAuth Public Clients (PKCE The Proof Key for Code Exchange by OAuth Public Clients (PKCE
[RFC7636]) standard was created specifically to mitigate against this [RFC7636]) standard was created specifically to mitigate against this
attack. It is a Proof of Possession extension to OAuth 2.0 that attack. It is a proof of possession extension to OAuth 2.0 that
protects the code grant from being used if it is intercepted. It protects the code grant from being used if it is intercepted. It
achieves this by having the client generate a secret verifier, a hash achieves this by having the client generate a secret verifier, a hash
of which it passes in the initial authorization request, and which it of which it passes in the initial authorization request, and which it
must present in full when redeeming the authorization code grant. An must present in full when redeeming the authorization code grant. An
app that intercepted the authorization code would not be in app that intercepted the authorization code would not be in
possession of this secret, rendering the code useless. possession of this secret, rendering the code useless.
Section 8.1 requires that both clients and servers use PKCE for Section 6 requires that both clients and servers use PKCE for public
public native app clients. Authorization servers SHOULD reject native app clients. Authorization servers SHOULD reject
authorization requests from native apps that don't use PKCE by authorization requests from native apps that don't use PKCE by
returning an error message as defined in Section 4.4.1 of PKCE returning an error message as defined in Section 4.4.1 of PKCE
[RFC7636]. [RFC7636].
8.2. OAuth Implicit Grant Authorization Flow 8.2. OAuth Implicit Grant Authorization Flow
The OAuth 2.0 implicit grant authorization flow as defined in The OAuth 2.0 implicit grant authorization flow as defined in
Section 4.2 of OAuth 2.0 [RFC6749] generally works with the practice Section 4.2 of OAuth 2.0 [RFC6749] generally works with the practice
of performing the authorization request in the browser, and receiving of performing the authorization request in the browser, and receiving
the authorization response via URI-based inter-app communication. the authorization response via URI-based inter-app communication.
However, as the Implicit Flow cannot be protected by PKCE (which is a However, as the implicit flow cannot be protected by PKCE [RFC7636]
required in Section 8.1), the use of the Implicit Flow with native (which is a required in Section 8.1), the use of the Implicit Flow
apps is NOT RECOMMENDED. with native apps is NOT RECOMMENDED.
Tokens granted via the implicit flow also cannot be refreshed without Tokens granted via the implicit flow also cannot be refreshed without
user interaction, making the authorization code grant flow - which user interaction, making the authorization code grant flow - which
can issue refresh tokens - the more practical option for native app can issue refresh tokens - the more practical option for native app
authorizations that require refreshing. authorizations that require refreshing.
8.3. Loopback Redirect Considerations 8.3. Loopback Redirect Considerations
Loopback interface redirect URIs use the "http" scheme (i.e., without Loopback interface redirect URIs use the "http" scheme (i.e., without
TLS). This is acceptable for loopback interface redirect URIs as the TLS). This is acceptable for loopback interface redirect URIs as the
skipping to change at page 13, line 13 skipping to change at page 13, line 13
client can be assured. This includes the case where the user has client can be assured. This includes the case where the user has
previously approved an authorization request for a given client id - previously approved an authorization request for a given client id -
unless the identity of the client can be proven, the request SHOULD unless the identity of the client can be proven, the request SHOULD
be processed as if no previous request had been approved. be processed as if no previous request had been approved.
Measures such as claimed HTTPS redirects MAY be accepted by Measures such as claimed HTTPS redirects MAY be accepted by
authorization servers as identity proof. Some operating systems may authorization servers as identity proof. Some operating systems may
offer alternative platform-specific identity features which MAY be offer alternative platform-specific identity features which MAY be
accepted, as appropriate. accepted, as appropriate.
8.7. Phishability of In-App Browser Tabs 8.7. Fake External User-Agent
While in-app browser tabs provide a secure authentication context, as The native app which is initiating the authorization request has a
the user initiates the flow from a native app, it is possible for large degree of control over the user interface and can potentially
that native app to completely fake an in-app browser tab. present a fake external user-agent, that is, an embedded user-agent
made to appear as an external user agent.
This can't be prevented directly - once the user is in the native The advantage when all good actors are using external user-agents is
app, that app is fully in control of what it can render - however that it is possible for security experts to detect bad actors, as
there are several mitigating factors. anyone faking an external user-agent is provably bad. 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 malicious
apps are detected, it may be possible to use this knowledge to
blacklist the apps signatures 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.
Importantly, such an attack that uses a web-view to fake an in-app Authorization servers can also directly protect against fake external
browser tab will always start with no authentication state. If all user-agents by requiring an authentication factor only available to
native apps use the techniques described in this best practice, users true external user-agents.
will not need to sign-in frequently and thus should be suspicious of
any sign-in request when they should have already been signed-in.
This is the case even for authorization servers that require Users who are particularly concerned about their security when using
occasional or frequent re-authentication, as such servers can in-app browser tabs may also take the additional step of opening the
preserve some user identifiable information from the old session, request in the full browser from the in-app browser tab, and complete
such as the email address or profile picture and display that the authorization there, as most implementations of the in-app
information during re-authentication. browser tab pattern offer such functionality.
Users who are particularly concerned about their security may also 8.8. Malicious External User-Agent
take the additional step of opening the request in the browser from
the in-app browser tab, and completing the authorization there, as
most implementations of the in-app browser tab pattern offer such
functionality.
8.8. Cross-App Request Forgery Protections 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.
Many operating systems mitigate this issue by requiring an explicit
user action to change the default handler for HTTP URIs. This attack
is not confined to OAuth for Native Apps, a malicious app configured
in this way would present a general and ongoing risk to the user
beyond OAuth usage.
8.9. Cross-App Request Forgery Protections
Section 5.3.5 of [RFC6819] recommends using the "state" parameter to Section 5.3.5 of [RFC6819] recommends using the "state" parameter to
link client requests and responses to prevent CSRF (Cross Site link client requests and responses to prevent CSRF (Cross Site
Request Forgery) attacks. Request Forgery) attacks.
To mitigate CSRF style attacks using inter-app URI communication, it To mitigate CSRF style attacks using inter-app URI communication, it
is similarly RECOMMENDED for native apps to include a high entropy is similarly RECOMMENDED that native apps include a high entropy
secure random number in the "state" parameter of the authorization secure random number in the "state" parameter of the authorization
request, and reject any incoming authorization responses without a request, and reject any incoming authorization responses without a
state value that matches a pending outgoing authorization request. state value that matches a pending outgoing authorization request.
8.9. Authorization Server Mix-Up Mitigation 8.10. Authorization Server Mix-Up Mitigation
To protect against a compromised or malicious authorization server To protect against a compromised or malicious authorization server
attacking another authorization server used by the same app, it is attacking another authorization server used by the same app, it is
REQUIRED that a unique redirect URI is used for each authorization REQUIRED that a unique redirect URI is used for each authorization
server used by the app (for example, by varying the path component), server used by the app (for example, by varying the path component),
and that authorization responses are rejected if the redirect URI and that authorization responses are rejected if the redirect URI
they were received on doesn't match the redirect URI in a outgoing they were received on doesn't match the redirect URI in a outgoing
authorization request. authorization request.
The native app MUST store the redirect URI used in the authorization The native app MUST store the redirect URI used in the authorization
request with the authorization session data (i.e., along with "state" request with the authorization session data (i.e., along with "state"
and other related data), and MUST verify that the URI on which the and other related data), and MUST verify that the URI on which the
authorization response was received exactly matches it. authorization response was received exactly matches it.
The requirements of Section 8.4 that authorization servers reject The requirements of Section 8.4 that authorization servers reject
requests with URIs that don't match what was registered are also requests with URIs that don't match what was registered are also
required to prevent such attacks. required to prevent such attacks.
8.10. Non-Browser External User-Agents 8.11. Non-Browser External User-Agents
This best practice recommends a particular type of external user- This best practice recommends a particular type of external user-
agent, the user's browser. Other external user-agent patterns may agent, the user's browser. Other external user-agent patterns may
also be viable for secure and usable OAuth. This document makes no also be viable for secure and usable OAuth. This document makes no
comment on those patterns. comment on those patterns.
8.11. Embedded User-Agents 8.12. Embedded User-Agents
OAuth 2.0 [RFC6749] Section 9 documents two approaches for native OAuth 2.0 [RFC6749] Section 9 documents two approaches for native
apps to interact with the authorization endpoint. This best current apps to interact with the authorization endpoint. This best current
practice requires that native apps MUST NOT use embedded user-agents practice requires that native apps MUST NOT use embedded user-agents
to perform authorization requests, and allows that authorization to perform authorization requests, and allows that authorization
endpoints MAY take steps to detect and block authorization requests endpoints MAY take steps to detect and block authorization requests
in embedded user-agents. The security considerations for these in embedded user-agents. The security considerations for these
requirements are detailed herein. requirements are detailed herein.
Embedded user-agents are an alternative method for authorizing native Embedded user-agents are an alternative method for authorizing native
skipping to change at page 16, line 5 skipping to change at page 16, line 23
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. <http://www.rfc-editor.org/info/rfc3986>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<http://www.rfc-editor.org/info/rfc6749>. <http://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,
<http://www.rfc-editor.org/info/rfc7230>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35, and Registration Procedures for URI Schemes", BCP 35,
RFC 7595, DOI 10.17487/RFC7595, June 2015, RFC 7595, DOI 10.17487/RFC7595, June 2015,
<http://www.rfc-editor.org/info/rfc7595>. <http://www.rfc-editor.org/info/rfc7595>.
[RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
for Code Exchange by OAuth Public Clients", RFC 7636, for Code Exchange by OAuth Public Clients", RFC 7636,
DOI 10.17487/RFC7636, September 2015, DOI 10.17487/RFC7636, September 2015,
<http://www.rfc-editor.org/info/rfc7636>. <http://www.rfc-editor.org/info/rfc7636>.
skipping to change at page 16, line 27 skipping to change at page 16, line 50
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>. <http://www.rfc-editor.org/info/rfc6819>.
[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
RFC 7591, DOI 10.17487/RFC7591, July 2015, RFC 7591, DOI 10.17487/RFC7591, July 2015,
<http://www.rfc-editor.org/info/rfc7591>. <http://www.rfc-editor.org/info/rfc7591>.
[AppAuth] Denniss, W., Wright, S., McGinniss, I., Ravikumar, R., and
others, "AppAuth", May 22, <https://appauth.io>.
[AppAuth.iOSmacOS] [AppAuth.iOSmacOS]
Wright, S., Denniss, W., and others, "AppAuth for iOS and Wright, S., Denniss, W., and others, "AppAuth for iOS and
macOS", February 2016, <https://github.com/openid/AppAuth- macOS", February 2016, <https://github.com/openid/AppAuth-
iOS>. iOS>.
[AppAuth.Android] [AppAuth.Android]
McGinniss, I., Denniss, W., and others, "AppAuth for McGinniss, I., Denniss, W., and others, "AppAuth for
Android", February 2016, <https://github.com/openid/ Android", February 2016, <https://github.com/openid/
AppAuth-Android>. AppAuth-Android>.
skipping to change at page 17, line 18 skipping to change at page 17, line 44
4. Not assume native app clients can keep a secret. If secrets are 4. Not assume native app clients can keep a secret. If secrets are
distributed to multiple installs of the same native app, they distributed to multiple installs of the same native app, they
should not be treated as confidential. See Section 8.5. should not be treated as confidential. See Section 8.5.
5. Support PKCE [RFC7636]. Required to protect authorization code 5. Support PKCE [RFC7636]. Required to protect authorization code
grants sent to public clients over inter-app communication grants sent to public clients over inter-app communication
channels. See Section 8.1 channels. See Section 8.1
Appendix B. Operating System Specific Implementation Details Appendix B. Operating System Specific Implementation Details
This document primarily defines best practices in an generic manner, This document primarily defines best practices in a generic manner,
referencing techniques commonly available in a variety of referencing techniques commonly available in a variety of
environments. This non-normative section documents operating system environments. This non-normative section documents operating system
specific implementation details of the best practice. specific implementation details of the best practice.
The implementation details herein are considered accurate at the time The implementation details herein are considered accurate at the time
of publishing but will likely change over time. It is hoped that of publishing but will likely change over time. It is hoped that
such change won't invalidate the generic principles in the rest of such change won't invalidate the generic principles in the rest of
the document, and those principles should take precedence in the the document, and those principles should take precedence in the
event of a conflict. event of a conflict.
skipping to change at page 18, line 19 skipping to change at page 18, line 44
implements the in-app browser tab pattern. The user's default implements the in-app browser tab pattern. The user's default
browser can be used to handle requests when no browser supports browser can be used to handle requests when no browser supports
Custom Tabs. Custom Tabs.
Android browser vendors should support the Custom Tabs protocol (by Android browser vendors should support the Custom Tabs protocol (by
providing an implementation of the "CustomTabsService" class), to providing an implementation of the "CustomTabsService" class), to
provide the in-app browser tab user experience optimization to their provide the in-app browser tab user experience optimization to their
users. Chrome is one such browser that implements Custom Tabs. users. Chrome is one such browser that implements Custom Tabs.
To receive the authorization response, private-use URI schemes are To receive the authorization response, private-use URI schemes are
broadly supported through Android Implicit Intends. Claimed HTTPS broadly supported through Android Implicit Intents. Claimed HTTPS
redirect URIs through Android App Links are available on Android 6.0 redirect URIs through Android App Links are available on Android 6.0
and above. Both types of redirect URIs are registered in the and above. Both types of redirect URIs are registered in the
application's manifest. application's manifest.
A complete open source sample is included in the AppAuth for Android A complete open source sample is included in the AppAuth for Android
[AppAuth.Android] library. [AppAuth.Android] library.
B.3. Windows Implementation Details B.3. Windows Implementation Details
Universal Windows Platform (UWP) apps can use the Web Authentication Both traditional and Universal Windows Platform (UWP) apps can
Broker API in SSO mode as an external user-agent for authorization perform authorization requests in the user's browser. Traditional
flows, and all app types can open an authorization request in the apps typically use a loopback redirect to receive the authorization
user's default browser using platform APIs for opening URIs in the response, and listening on the loopback interface is allowed by
browser. 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.
The Web Authentication Broker when used in SSO mode is an external UWP apps can use private-use URI scheme redirects to receive the
user-agent with an authentication context that is shared with all authorization response from the browser, which will bring the app to
invocations of the broker but not the user's browser. Note that if the foreground. Known on the platform as "URI Activation", the URI
not used in SSO mode, the broker is an embedded user-agent, hence scheme is limited to 39 characters in length, and may include the "."
only operation in SSO mode is RECOMMENDED. character, making short reverse domain name based schemes (as
recommended in Section 7.1) possible.
UWP apps can alternatively use the Web Authentication Broker API in
SSO (Single Sign-on) 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 sign-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. Personalisations
the user has made to their browser, such as configuring a password
manager may not 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 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 must be of the form "msapp://{appSID}" where "appSID" is the app's
SID, which can be found in the app's registration information. While SID, which can be found in the app's registration information. While
Windows enforces the URI authority on such redirects, ensuring only Windows enforces the URI authority on such redirects, ensuring only
the app with the matching SID can receive the response on Windows, 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 URI scheme could be claimed by apps on other platforms without
the same authority present, thus this redirect type should be treated the same authority present, thus this redirect type should be treated
similar to private-use URI scheme redirects for security purposes. similar to private-use URI scheme redirects for security purposes.
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. Universal Windows Platform (UWP) apps can
use private-use URI scheme redirects to receive the authorization
response, 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 may include the "." character, making short
reverse domain name based schemes (as recommended in Section 7.1)
possible.
An open source sample demonstrating these patterns is available An open source sample demonstrating these patterns is available
[SamplesForWindows]. [SamplesForWindows].
B.4. macOS Implementation Details B.4. macOS Implementation Details
Apps can initiate an authorization request in the user's default Apps can initiate an authorization request in the user's default
browser using platform APIs for opening URIs in the browser. browser using platform APIs for opening URIs in the browser.
To receive the authorization response, private-use URI schemes are To receive the authorization response, private-use URI schemes are a
are a good redirect URI choice on macOS, as the user is returned good redirect URI choice on macOS, as the user is returned right back
right back to the app they launched the request from. These are to the app they launched the request from. These are registered in
registered in the application's bundle information property list the application's bundle information property list using the
using the "CFBundleURLSchemes" key. Loopback IP redirects are "CFBundleURLSchemes" key. Loopback IP redirects are another viable
another viable option, and listening on the loopback interface is option, and listening on the loopback interface is allowed by default
allowed by default firewall rules. firewall rules.
A complete open source sample is included in the AppAuth for iOS and A complete open source sample is included in the AppAuth for iOS and
macOS [AppAuth.iOSmacOS] library. macOS [AppAuth.iOSmacOS] library.
B.5. Linux Implementation Details B.5. Linux Implementation Details
Opening the Authorization Request in the user's default browser Opening the Authorization Request in the user's default browser
requires a distro-specific command, "xdg-open" is one such tool. requires a distro-specific command, "xdg-open" is one such tool.
The loopback redirect is the recommended redirect choice for desktop The loopback redirect is the recommended redirect choice for desktop
apps on Linux to receive the authorization response. apps on Linux to receive the authorization response. Apps SHOULD NOT
set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options, to prevent
other apps binding to the same socket.
Appendix C. Acknowledgements Appendix C. Acknowledgements
The author would like to acknowledge the work of Marius Scurtescu, The author would like to acknowledge the work of Marius Scurtescu,
and Ben Wiley Sittler whose design for using private-use URI schemes and Ben Wiley Sittler whose design for using private-use URI schemes
in native OAuth 2.0 clients at Google formed the basis of in native OAuth 2.0 clients at Google formed the basis of
Section 7.1. Section 7.1.
The following individuals contributed ideas, feedback, and wording The following individuals contributed ideas, feedback, and wording
that shaped and formed the final specification: that shaped and formed the final specification:
 End of changes. 47 change blocks. 
142 lines changed or deleted 169 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/