< draft-ietf-oauth-native-apps-04.txt   draft-ietf-oauth-native-apps-05.txt >
OAuth Working Group W. Denniss OAuth Working Group W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Best Current Practice J. Bradley Intended status: Best Current Practice J. Bradley
Expires: April 15, 2017 Ping Identity Expires: April 24, 2017 Ping Identity
October 12, 2016 October 21, 2016
OAuth 2.0 for Native Apps OAuth 2.0 for Native Apps
draft-ietf-oauth-native-apps-04 draft-ietf-oauth-native-apps-05
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 April 15, 2017. This Internet-Draft will expire on April 24, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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 19 skipping to change at page 2, line 19
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Authorization Flow for Native Apps Using the Browser . . 5 4.1. Authorization Flow for Native Apps Using the Browser . . 5
5. Using Inter-app URI Communication for OAuth . . . . . . . . . 6 5. Using Inter-app URI Communication for OAuth . . . . . . . . . 6
6. Initiating the Authorization Request from a Native App . . . 6 6. Initiating the Authorization Request from a Native App . . . 6
7. Receiving the Authorization Response in a Native App . . . . 7 7. Receiving the Authorization Response in a Native App . . . . 7
7.1. App-declared Custom URI Scheme Redirection . . . . . . . 7 7.1. App-declared Custom URI Scheme Redirection . . . . . . . 7
7.2. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 8 7.2. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 8
7.3. Loopback URI Redirection . . . . . . . . . . . . . . . . 8 7.3. Loopback URI Redirection . . . . . . . . . . . . . . . . 9
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 9 8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 9
8.2. Protecting the Authorization Code . . . . . . . . . . . . 10 8.2. Protecting the Authorization Code . . . . . . . . . . . . 10
8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11
8.4. Registration of App Redirection URIs . . . . . . . . . . 11 8.4. Registration of Native App Clients . . . . . . . . . . . 11
8.5. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 11 8.5. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 12
8.6. Phishability of In-App Browser Tabs . . . . . . . . . . . 12 8.6. Phishability of In-App Browser Tabs . . . . . . . . . . . 12
8.7. Limitations of Non-verifiable Clients . . . . . . . . . . 12 8.7. Limitations of Non-verifiable Clients . . . . . . . . . . 12
8.8. Non-Browser External User Agents . . . . . . . . . . . . 12 8.8. Non-Browser External User-Agents . . . . . . . . . . . . 13
8.9. Client Authentication . . . . . . . . . . . . . . . . . . 13 8.9. Client Authentication . . . . . . . . . . . . . . . . . . 13
8.10. Cross-App Request Forgery Protections . . . . . . . . . . 13 8.10. Cross-App Request Forgery Protections . . . . . . . . . . 13
8.11. Authorization Server Mix-Up Mitigation . . . . . . . . . 13 8.11. Authorization Server Mix-Up Mitigation . . . . . . . . . 13
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 14
10.2. Informative References . . . . . . . . . . . . . . . . . 14 10.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 15 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 15
Appendix B. Operating System Specific Implementation Details . . 15 Appendix B. Operating System Specific Implementation Details . . 16
B.1. iOS Implementation Details . . . . . . . . . . . . . . . 16 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 16
B.2. Android Implementation Details . . . . . . . . . . . . . 16 B.2. Android Implementation Details . . . . . . . . . . . . . 16
B.3. Windows Implementation Details . . . . . . . . . . . . . 16 B.3. Windows Implementation Details . . . . . . . . . . . . . 17
B.4. macOS Implementation Details . . . . . . . . . . . . . . 17 B.4. macOS Implementation Details . . . . . . . . . . . . . . 17
B.5. Linux Implementation Details . . . . . . . . . . . . . . 17 B.5. Linux Implementation Details . . . . . . . . . . . . . . 17
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 17 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
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, or an external user- authorization endpoint: an embedded user-agent, or an external user-
agent. agent.
This best current practice recommends that only external user-agents This best current practice recommends that only external user-agents
skipping to change at page 3, line 36 skipping to change at page 3, line 36
document uses the following terms: document uses the following terms:
"native app" An application that is installed by the user to their "native app" An application that is installed by the user to their
device, as distinct from a web app that runs in the browser device, as distinct from a web app that runs in the browser
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.
"OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749].
"external user-agent" A user-agent capable of handling the
authorization request that is a separate entity to the native app
making the request (such as a browser), such that the app cannot
access the cookie storage or modify the page content.
"embedded user-agent" A user-agent hosted inside the native app
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
and/or modify the page content.
"app" Shorthand for "native app". "app" Shorthand for "native app".
"app store" An ecommerce store where users can download and purchase "app store" An ecommerce store where users can download and purchase
apps. apps.
"authz" Abbreviation of "authorization".
"browser" The operating system's default browser, pre-installed as "browser" The operating system's default browser, pre-installed as
part of the operating system, or installed and set as default by part of the operating system, or installed and set as default by
the user. the user.
"browser tab" An open page of the browser. Browser typically have "browser tab" An open page of the browser. Browser typically have
multiple "tabs" representing various open pages. multiple "tabs" representing various open pages.
"in-app browser tab" A full page browser with limited navigation "in-app browser tab" A full page browser with limited navigation
capabilities that is displayed inside a host app, but retains the capabilities that is displayed inside a host app, but retains the
full security properties and authentication state of the browser. full security properties and authentication state of the browser.
skipping to change at page 4, line 30 skipping to change at page 4, line 40
"web-view" A web browser UI component that can be embedded in apps "web-view" A web browser UI component that can be embedded in apps
to render web pages, used to create embedded user-agents. 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 where the domain components are domain name system, but where where the domain components are
reversed, for example "app.example.com" becomes "com.example.app". reversed, 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 a browser (an external perform the OAuth authorization request in an external user-agent
user-agent), rather than web-view (an embedded 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 web-views for OAuth Previously it was common for native apps to use embedded user-agents
authorization requests. That approach has many drawbacks, typically (commonly implemented with web-views) for OAuth authorization
including the host app being able to copy user credentials and requests. That approach has many drawbacks, including the host app
cookies, and the user needing to authenticate from scratch in each being able to copy user credentials and cookies, and the user needing
app. See Section 8.1 for a deeper analysis of using embedded user- to authenticate from scratch in each app. See Section 8.1 for a
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 emcompasses URIs that can be used for inter-process URIs, which emcompasses URIs that can be used for inter-process
communication. Some OAuth server implementations that assume all communication. Some OAuth server implementations that assume all
skipping to change at page 5, line 39 skipping to change at page 5, line 51
| | |<---------------------| Endpoint | | | |<---------------------| Endpoint |
| +---------------------------+ | (3) Authz Code | | | +---------------------------+ | (3) Authz 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 the Figure 1 illustrates the interaction of the native app with the
system browser to authorize the user via an external user-agent. system browser to authorize the user via an external user-agent.
1) The client app opens a browser tab with the authorization request. (1) The client app opens a browser tab with the authorization
request.
2) Authorization endpoint receives the authorization request, (2) Authorization endpoint receives the authorization request,
authenticates the user and obtains authorization. Authenticating authenticates the user and obtains authorization.
the user may involve chaining to other authentication systems. Authenticating the user may involve chaining to other
authentication systems.
3) Authorization server issues an authorization code to the redirect (3) Authorization server issues an authorization code to the
URI. redirect URI.
4) Client receives the authorization code from the redirect URI. (4) Client receives the authorization code from the redirect URI.
5) Client app presents the authorization code at the token endpoint. (5) Client app presents the authorization code at the token
endpoint.
6) Token endpoint validates the authorization code and issues the (6) Token endpoint validates the authorization code and issues the
tokens requested. tokens requested.
5. Using Inter-app URI Communication for OAuth 5. Using Inter-app URI Communication for OAuth
Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 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 authorization request and return the authorization response to
the requesting website, URIs can be used by native apps to initiate the requesting website, URIs can be used by native apps to initiate
the authorization request in the device's browser and return the the authorization request in the device's browser and return the
response to the requesting native app. response to the requesting native app.
By applying the same principles from the web to native apps, we gain By applying the same principles from the web to native apps, we gain
skipping to change at page 6, line 34 skipping to change at page 6, line 47
authentication requests. This is achieved by opening the authentication requests. This is achieved by opening the
authorization request in the browser (detailed in Section 6), and authorization request in the browser (detailed in Section 6), and
using a redirect URI that will return the authorization response back using a redirect URI that will return the authorization response back
to the native app, as defined in Section 7. to the native app, as defined in Section 7.
This best practice focuses on the browser as the RECOMMENDED external This best practice focuses on the browser as the RECOMMENDED external
user-agent for native apps. Other external user-agents, such as a user-agent for native apps. Other external user-agents, such as a
native app provided by the authorization server may meet the criteria native app provided by the authorization server may meet the criteria
set out in this best practice, including using the same redirection set out in this best practice, including using the same redirection
URI properties, but their use is out of scope for this specification. URI properties, but their use is out of scope for this specification.
options for inter-app communication, offering similar security
6. Initiating the Authorization Request from a Native App 6. Initiating the Authorization Request from a Native App
The authorization request is created as per OAuth 2.0 [RFC6749], and The authorization request is created as per OAuth 2.0 [RFC6749], and
opened in the user's browser using platform-specific APIs for that opened in the user's browser using platform-specific APIs for that
purpose. purpose.
The function of the redirect URI for a native app authorization The function of the redirect URI for a native app authorization
request is similar to that of a web-based authorization request. request is similar to that of a web-based authorization request.
Rather than returning the authorization response to the OAuth Rather than returning the authorization response to the OAuth
skipping to change at page 7, line 29 skipping to change at page 7, line 41
account platform specific implementation details. account platform specific implementation details.
7.1. App-declared Custom URI Scheme Redirection 7.1. App-declared Custom 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 custom URI communication via URIs by allowing apps to register custom URI
schemes, like "com.example.app:". When the browser or another app schemes, like "com.example.app:". When the browser or another app
attempts to load a URI with a custom scheme, the app that registered attempts to load a URI with a custom scheme, the app that registered
it is launched to handle the request. it is launched to handle the request.
To perform an OAuth 2.0 Authorization Request on a supported To perform an OAuth 2.0 Authorization Request with a custom URI
platform, the native app launches the browser with a normal OAuth 2.0 scheme-based redirect URI, the native app launches the browser with a
Authorization Request, but provides a redirection URI that utilizes a normal OAuth 2.0 Authorization Request, but provides a redirection
custom URI scheme registered with the operating system by the calling URI that utilizes a custom URI scheme registered with the operating
app. system by the calling app.
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 like it would any redirect URI, but as the client's redirection URI like it would any redirect URI, but as
the redirection URI uses a custom scheme, this results in the OS the redirection URI uses a custom scheme, this results in the OS
launching the native app passing in the URI. The native app then launching the native app passing in the URI. The native app then
processes the authorization response like any OAuth client. processes the authorization response like any OAuth client.
7.1.1. Custom URI Scheme Namespace Considerations 7.1.1. Custom URI Scheme Namespace Considerations
When choosing a URI scheme to associate with the app, apps MUST use a When choosing a URI scheme to associate with the app, apps MUST use a
skipping to change at page 8, line 31 skipping to change at page 8, line 43
maliciously). For example, if two apps claimed "com.example.app:", maliciously). For example, if two apps claimed "com.example.app:",
the owner of "example.com" could petition the app store operator to the owner of "example.com" could petition the app store operator to
remove the counterfeit app. This petition is harder to prove if a remove the counterfeit app. This petition is harder to prove if a
generic URI scheme was used. generic URI scheme was used.
7.2. App-claimed HTTPS URI Redirection 7.2. App-claimed HTTPS URI Redirection
Some operating systems allow apps to claim HTTPS URLs in their Some operating systems allow apps to claim HTTPS URLs in their
domains. When the browser encounters a claimed URL, instead of the domains. When the browser encounters a claimed URL, instead of the
page being loaded in the browser, the native app is launched instead page being loaded in the browser, the native app is launched instead
with the URL supplied as input. with the URL supplied as a launch parameter.
App-claimed HTTPS redirect URIs have some advantages in that the App-claimed HTTPS redirect URIs have some advantages in that the
identity of the destination app is guaranteed by the operating identity of the destination app is guaranteed by the operating
system. Due to this reason, they SHOULD be used over the other system. Due to this reason, they SHOULD be used over the other
redirect choices for native apps where possible. redirect choices for native apps where possible.
App-claimed HTTPS redirect URIs function exactly as normal HTTPS App-claimed HTTPS redirect URIs function as normal HTTPS redirects
redirects from the perspective of the authorization server, though it from the perspective of the authorization server, though it is
is RECOMMENDED that the authorization server is able to distinguish RECOMMENDED that the authorization server is able to distinguish
between public native app clients that use app-claimed HTTPS redirect between public native app clients that use app-claimed HTTPS redirect
URIs and confidential web clients. A flag in the client registration URIs and confidential web clients. A configuration option in the
information that indicates a public native app client is one such client registration (as documented in Section 8.4) is one method for
method for distinguishing client types. distinguishing client types.
7.3. Loopback URI Redirection 7.3. Loopback URI Redirection
Desktop operating systems allow native apps to listen on a local port Desktop operating systems allow native apps to listen on a local port
for HTTP redirects. This can be used by native apps to receive OAuth for HTTP redirects. This can be used by native apps to receive OAuth
authorization responses on compatible platforms. authorization responses on compatible platforms.
Loopback redirect URIs take the form of the loopback IP, any port Loopback redirect URIs take the form of the loopback IP, any port
(dynamically provided by the client), and a path component. (dynamically provided by the client), and a path component.
Specifically: "http://127.0.0.1:{port}/{path}", and Specifically: "http://127.0.0.1:{port}/{path}" for IPv4, and
"http://[::1]:{port}/{path}". "http://[::1]:{port}/{path}" for IPv6.
For loopback IP redirect URIs, the authorization server MUST allow For loopback IP redirect URIs, the authorization server MUST allow
any port to be specified at the time of the request, to accommodate any port to be specified at the time of the request, to accommodate
clients that obtain an available port from the operating system at clients that obtain an available port from the operating system at
the time of the request. Other than that, the redirect is be treated the time of the request. Other than that, the redirect is be treated
like any other. like any other.
8. Security Considerations 8. Security Considerations
8.1. Embedded User-Agents 8.1. Embedded User-Agents
Embedded user-agents, commonly implemented with web-views, are an Embedded user-agents are an alternative method for authorization
alternative method for authorizing native apps. They are however native apps. They are however unsafe for use by third-parties to the
unsafe for use by third-parties by definition. They involve the user authorization server by definition, as the app that hosts the
signing in with their full login credentials, only to have them embedded user-agent can access the user's full authentication
downscoped to less powerful OAuth credentials. credential, not just the OAuth authorization grant that was intended
for the app.
Even when used by trusted first-party apps, embedded user-agents
violate the principle of least privilege by obtaining more powerful
credentials than they need, potentially increasing the attack
surface.
In typical web-view based implementations of embedded user-agents, In typical web-view based implementations of embedded user-agents,
the host application can: log every keystroke entered in the form to the host application can: log every keystroke entered in the form to
capture usernames and passwords; automatically submit forms and capture usernames and passwords; automatically submit forms and
bypass user-consent; copy session cookies and use them to perform bypass user-consent; copy session cookies and use them to perform
authenticated actions as the user. authenticated actions as the user.
Encouraging users to enter credentials in an embedded web-view 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 without the usual address bar and visible certificate validation
features that browsers have makes it impossible for the user to know features that browsers have makes it impossible for the user to know
if they are signing in to the legitimate site, and even when they if they are signing in to the legitimate site, and even when they
are, it trains them that it's OK to enter credentials without are, it trains them that it's OK to enter credentials without
validating the site first. validating the site first.
Aside from the security concerns, web-views do not share the Aside from the security concerns, embedded user-agents do not share
authentication state with other apps or the browser, requiring the the authentication state with other apps or the browser, requiring
user to login for every authorization request and leading to a poor the user to login for every authorization request and leading to a
user experience. poor user experience.
Native apps MUST NOT use embedded user-agents for OAuth to third- Native apps MUST NOT use embedded user-agents to perform
parties. authorization requests.
Authorization servers MAY take steps to detect and block Authorization endpoints MAY take steps to detect and block
authorization requests in third-party embedded user-agents. authorization requests in embedded user-agents.
8.2. Protecting the Authorization Code 8.2. 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, however code interception by a native app other authorization code which limits the attack surface, however code
than the intended recipient may be possible. interception by a native app other than the intended app may still be
possible.
A limitation of using custom URI schemes for redirect URIs is that A limitation of using custom URI schemes for redirect URIs is that
multiple apps can typically register the same scheme, which makes it multiple apps can typically register the same scheme, which makes it
indeterminate as to which app will receive the Authorization Code indeterminate as to which app will receive the Authorization Code.
Grant. This is not an issue for HTTPS redirection URIs (i.e. PKCE [RFC7636] details how this limitation can be used to execute a
standard web URLs) due to the fact the HTTPS URI scheme is enforced code interception attack (see Figure 1). Loopback IP based redirect
by the authority (as defined by [RFC3986]), the domain name system, URIs may be susceptible to interception by other apps listening on
which does not allow multiple entities to own the same domain. the same loopback interface.
If multiple apps register the same scheme, it is possible that the
authorization code will be sent to the wrong app (generally the
operating system makes no guarantee of which app will handle the URI
when multiple register the same scheme). PKCE [RFC7636] details how
this limitation can be used to execute a code interception attack
(see Figure 1). This attack vector applies to public clients
(clients that are unable to maintain a client secret) which is
typical of most native apps.
While Section 7.1.1 details ways that this can be mitigated through As most forms of inter-app URI-based communication sends data over
policy enforcement (through being able to report and have removed any insecure local channels, eavesdropping and interception of the
offending apps), we can also protect the authorization code grant authorization response is a risk for native apps. App-claimed HTTPS
from being used in cases where it was intercepted. redirects are hardened against this type of attack due to the
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 which achieves this by having the client generate a secret verifier which
it passes in the initial authorization request, and which it must it passes in the initial authorization request, and which it must
present later when redeeming the authorization code grant. An app present later when redeeming the authorization code grant. An app
that intercepted the authorization code would not be in possession of that intercepted the authorization code would not be in possession of
this secret, rendering the code useless. this secret, rendering the code useless.
Both the client and the Authorization Server MUST support PKCE Public native app clients MUST protect the authorization request with
[RFC7636] to use custom URI schemes, or loopback IP redirects. PKCE [RFC7636]. Authorization servers MUST support PKCE [RFC7636]
Authorization Servers SHOULD reject authorization requests using a for public native app clients. Authorization servers SHOULD reject
custom scheme, or loopback IP as part of the redirection URI if the authorization requests from native apps that don't use PKCE by
required PKCE parameters are not present, returning the error message returning an error message as defined in Section 4.4.1 of PKCE
as defined in Section 4.4.1 of PKCE [RFC7636]. It is RECOMMENDED to [RFC7636].
use PKCE [RFC7636] for app-claimed HTTPS redirect URIs, even though
these are not generally subject to interception, to protect against
attacks on inter-app communication.
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
HTTP request never leaves the device. HTTP request never leaves the device.
Clients should open the loopback port only when starting the Clients should open the loopback port only when starting the
authorization request, and close it once the response is returned. authorization request, and close it once the response is returned.
While redirect URIs using localhost (i.e. "http://localhost:{port}/" While redirect URIs using localhost (i.e. "http://localhost:{port}/"
function similarly to loopback IP redirects described in Section 7.3, function similarly to loopback IP redirects described in Section 7.3,
the use of "localhost" is NOT RECOMMENDED. Opening a port on the the use of "localhost" is NOT RECOMMENDED. Opening a port on the
loopback interface is more secure as only apps on the local device loopback interface is more secure as only apps on the local device
can connect to it. It is also less susceptible to misconfigured can connect to it. It is also less susceptible to misconfigured
routing, and interference by client side firewalls. routing, and interference by client side firewalls.
8.4. Registration of App Redirection URIs 8.4. Registration of Native App Clients
Authorization Servers SHOULD have a way to distinguish public native
app clients from confidential web-clients, as the lack of client
authentication means they are often handled differently. A
configuration option to indicate a public native app client is one
such popular method for achieving this.
As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the
authorization server SHOULD require the client to pre-register the authorization server SHOULD require the client to pre-register the
complete redirection URI. This applies and is RECOMMENDED for all complete redirection URI. This applies and is RECOMMENDED for all
redirection URIs used by native apps. redirection URIs used by native apps.
For Custom URI scheme based redirects, authorization servers SHOULD For Custom URI scheme based redirects, authorization servers SHOULD
enforce the requirement in Section 7.1.1 that clients use reverse enforce the requirement in Section 7.1.1 that clients use reverse
domain name based schemes. domain name based schemes.
skipping to change at page 12, line 48 skipping to change at page 13, line 9
8.7. Limitations of Non-verifiable Clients 8.7. Limitations of Non-verifiable Clients
As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization
server SHOULD NOT process authorization requests automatically server SHOULD NOT process authorization requests automatically
without user consent or interaction, except when the identity of the without user consent or interaction, except when the identity of the
client can be assured. Measures such as claimed HTTPS redirects can client can be assured. Measures such as claimed HTTPS redirects can
be used by native apps to prove their identity to the authorization be used by native apps to prove their identity to the authorization
server, and some operating systems may offer alternative platform- server, and some operating systems may offer alternative platform-
specific identity features which may be used, as appropriate. specific identity features which may be used, as appropriate.
8.8. Non-Browser External User Agents 8.8. 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-agents 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.9. Client Authentication 8.9. Client Authentication
Secrets that are statically included as part of an app distributed to Secrets that are statically included as part of an app distributed to
multiple users should not be treated as confidential secrets, as one multiple users should not be treated as confidential secrets, as one
user may inspect their copy and learn the shared secret. For this 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 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT
RECOMMENDED for authorization servers to require client RECOMMENDED for authorization servers to require client
skipping to change at page 18, line 4 skipping to change at page 18, line 16
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 custom URI schemes in and Ben Wiley Sittler whose design for using custom URI schemes in
native OAuth 2.0 clients formed the basis of Section 7.1. native OAuth 2.0 clients formed the basis of 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:
Andy Zmolek, Steven E Wright, Brian Campbell, Paul Madsen, Nat Andy Zmolek, Steven E Wright, Brian Campbell, Paul Madsen, Nat
Sakimura, Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de Sakimura, Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de
Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill Medeiros, Adam Dawes, Naveen Agarwal, Hannes Tschofenig, Ashish Jain,
Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Paul Erik Wahlstrom, Bill Fisher, Sudhi Umarji, Michael B. Jones, Vittorio
Grassi, David Waite, Naveen Agarwal, and Adam Dawes. Bertocci, Dick Hardt, David Waite, and Ignacio Fiorentino.
Authors' Addresses Authors' Addresses
William Denniss William Denniss
Google Google
1600 Amphitheatre Pkwy 1600 Amphitheatre Pkwy
Mountain View, CA 94043 Mountain View, CA 94043
USA USA
Email: wdenniss@google.com Email: wdenniss@google.com
 End of changes. 40 change blocks. 
101 lines changed or deleted 112 lines changed or added

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