draft-ietf-oauth-native-apps-12.txt   rfc8252.txt 
OAuth Working Group W. Denniss Internet Engineering Task Force (IETF) W. Denniss
Internet-Draft Google Request for Comments: 8252 Google
Updates: 6749 (if approved) J. Bradley BCP: 212 J. Bradley
Intended status: Best Current Practice Ping Identity Updates: 6749 Ping Identity
Expires: December 11, 2017 June 9, 2017 Category: Best Current Practice October 2017
ISSN: 2070-1721
OAuth 2.0 for Native Apps OAuth 2.0 for Native Apps
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
This Internet-Draft is submitted in full conformance with the This memo documents an Internet Best Current Practice.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
BCPs is available in Section 2 of RFC 7841.
This Internet-Draft will expire on December 11, 2017. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc8252.
Copyright Notice Copyright 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 (https://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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
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. 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" Scheme 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 . . . . . . . . . . . 12
8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12 8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12
8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 12 8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 13
8.7. Fake External User-Agent . . . . . . . . . . . . . . . . 13 8.7. Fake External User-Agents . . . . . . . . . . . . . . . . 13
8.8. Malicious External User-Agent . . . . . . . . . . . . . . 13 8.8. Malicious External User-Agents . . . . . . . . . . . . . 14
8.9. Cross-App Request Forgery Protections . . . . . . . . . . 14 8.9. Cross-App Request Forgery Protections . . . . . . . . . . 14
8.10. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 8.10. Authorization Server Mix-Up Mitigation . . . . . . . . . 14
8.11. Non-Browser External User-Agents . . . . . . . . . . . . 14 8.11. Non-Browser External User-Agents . . . . . . . . . . . . 15
8.12. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14 8.12. Embedded User-Agents . . . . . . . . . . . . . . . . . . 15
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.1. Normative References . . . . . . . . . . . . . . . . . . 16 10.1. Normative References . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . 17
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 17 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 18
Appendix B. Operating System Specific Implementation Details . . 17 Appendix B. Platform-Specific Implementation Details . . . . . . 18
B.1. iOS Implementation Details . . . . . . . . . . . . . . . 18 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 18
B.2. Android Implementation Details . . . . . . . . . . . . . 18 B.2. Android Implementation Details . . . . . . . . . . . . . 19
B.3. Windows Implementation Details . . . . . . . . . . . . . 19 B.3. Windows Implementation Details . . . . . . . . . . . . . 19
B.4. macOS Implementation Details . . . . . . . . . . . . . . 19 B.4. macOS Implementation Details . . . . . . . . . . . . . . 20
B.5. Linux Implementation Details . . . . . . . . . . . . . . 20 B.5. Linux Implementation Details . . . . . . . . . . . . . . 21
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
1. Introduction 1. Introduction
The OAuth 2.0 [RFC6749] authorization framework documents two Section 9 of the OAuth 2.0 authorization framework [RFC6749]
approaches in Section 9 for native apps to interact with the documents two approaches 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 as well as 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 [AppAuth] 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
words for use in RFCs to Indicate Requirement Levels [RFC2119]. If BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
these words are used without being spelled in uppercase then they are capitals, as shown here.
to be interpreted with their normal natural language meanings.
3. Terminology 3. Terminology
In addition to the terms defined in referenced specifications, this In addition to the terms defined in referenced specifications, this
document uses the following terms: document uses the following terms:
"native app" An app or application that is installed by the user to "native app" An app or application that is installed by the user to
their device, as distinct from a web app that runs in the browser their 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
equivalent to native apps for the purpose of this specification. considered equivalent to native apps for the purpose of this
specification.
"app" In this document, "app" means a "native app" unless further "app" A "native app" unless further specified.
specified.
"app store" An ecommerce store where users can download and purchase "app store" An e-commerce store where users can download and
apps. purchase apps.
"OAuth" In this document, OAuth refers to the OAuth 2.0 "OAuth" Authorization protocol specified by the OAuth 2.0
Authorization Framework [RFC6749]. 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 that the app cannot
that the app cannot access the cookie storage, nor inspect or 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 by the native app making
itself (such as via a web-view), with which the app has control the authorization request that forms a part of the app or shares
over to the extent it is capable of accessing the cookie storage the same security domain such that the app can access the cookie
and/or modifying the page content. storage and/or inspect or modify page content.
"browser" The default application launched by the operating system "browser" The default application launched by the operating system
to handle "http" and "https" scheme URI content. to handle "http" and "https" scheme URI content.
"in-app browser tab" A programmatic instantiation of the browser "in-app browser tab" A programmatic instantiation of the browser
that is displayed inside a host app, but retains the full security that is displayed inside a host app but that retains the full
properties and authentication state of the browser. Has different security properties and authentication state of the browser. It
platform-specific product names, such as SFSafariViewController on has different platform-specific product names, several of which
iOS, and Custom Tabs on Android. are detailed in Appendix B.
"web-view" A web browser UI (user interface) component that is
embedded in apps to render web pages under the control of the app.
"inter-app communication" Communication between two apps on a "inter-app communication" Communication between two apps on a
device. device.
"claimed HTTPS URI" Some platforms allow apps to claim a HTTPS "claimed "https" scheme URI" Some platforms allow apps to claim an
scheme URI after proving ownership of the domain name. URIs "https" scheme URI after proving ownership of the domain name.
claimed in such a way are then opened in the app instead of the URIs claimed in such a way are then opened in the app instead of
browser. the browser.
"private-use URI scheme" A private-use URI scheme defined by the app
and registered with the operating system. URI requests to such
schemes trigger the app which registered it to be launched to
handle the request.
"web-view" A web browser UI (user interface) component that can be "private-use URI scheme" As used by this document, a URI scheme
embedded in apps to render web pages, used to create embedded defined by the app (following the requirements of Section 3.8 of
user-agents. [RFC7595]) and registered with the operating system. URI requests
to such schemes launch the app that registered it to handle the
request.
"reverse domain name notation" A naming convention based on the "reverse domain name notation" A naming convention based on the
domain name system, but where the domain components are reversed, domain name system, but one where the domain components are
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 For authorizing users in native apps, the best current practice 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 as well as the user
to authenticate from scratch in each app. See Section 8.12 for a needing to authenticate from scratch in each app. See Section 8.12
deeper analysis of using embedded user-agents for OAuth. for a deeper analysis of the drawbacks 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). the 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 OAuth
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. This 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) Authorization +---------------+
| | | | Code | | | | | | Code | |
skipping to change at page 5, line 48 skipping to change at page 5, line 50
| | | | | | | |
| v | | | v | |
| +---------------------------+ | (2) Authorization +---------------+ | +---------------------------+ | (2) Authorization +---------------+
| | | | Request | | | | | | Request | |
| | Browser |--------------------->| Authorization | | | Browser |--------------------->| Authorization |
| | |<---------------------| Endpoint | | | |<---------------------| Endpoint |
| +---------------------------+ | (3) Authorization | | | +---------------------------+ | (3) Authorization | |
| | Code +---------------+ | | Code +---------------+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
Figure 1: Native App Authorization via External User-agent Figure 1: Native App Authorization via an External User-Agent
Figure 1 illustrates the interaction of the native app with a browser Figure 1 illustrates the interaction between a native app and the
external user-agent to authorize the user. browser to authorize the user.
(1) The client app opens a browser tab with the authorization (1) 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,
authenticates the user and obtains authorization. authenticates the user, and obtains authorization.
Authenticating the user may involve chaining to other Authenticating the user may involve chaining to other
authentication systems. authentication systems.
(3) Authorization server issues an authorization code to the (3) Authorization server issues an authorization code to the
redirect 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 (5) Client app presents the authorization code at the token
endpoint. 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 adopting the same methods used on the web for OAuth, benefits seen By adopting the same methods used on the web for OAuth, benefits seen
in the web context like the usability of a single sign-on session and in the web context like the usability of a single sign-on session and
the security of a separate authentication context are likewise gained the security of a separate authentication context are likewise gained
in the native app context. Re-using the same approach also reduces in the native app context. Reusing the same approach also reduces
the implementation complexity and increases interoperability by the implementation complexity and increases interoperability by
relying on standards-based web flows that are not specific to a relying on standards-based web flows that are not specific to a
particular platform. particular platform.
To conform to this best practice, native apps MUST use an external To conform to this best practice, native apps MUST use an external
user-agent to perform OAuth authentication requests. This is user-agent to perform OAuth authorization requests. This is achieved
achieved by opening the authorization request in the browser by opening the authorization request in the browser (detailed in
(detailed in Section 6), and using a redirect URI that will return Section 6) and using a redirect URI that will return the
the authorization response back to the native app, as defined in authorization response back to the native app (defined in Section 7).
Section 7.
6. Initiating the Authorization Request from a Native App 6. Initiating the Authorization Request from a Native App
Native apps needing user authorization create an authorization Native apps needing user authorization create an authorization
request URI with the authorization code grant type per Section 4.1 of request URI with the authorization code grant type per Section 4.1 of
OAuth 2.0 [RFC6749], using a redirect URI capable of being received OAuth 2.0 [RFC6749], using a redirect URI capable of being received
by the native app. by the native app.
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.
skipping to change at page 7, line 21 skipping to change at page 7, line 28
platforms are documented in Section 7. Any redirect URI that allows platforms are documented in Section 7. Any redirect URI that allows
the app to receive the URI and inspect its parameters is viable. the app to receive the URI and inspect its parameters is viable.
Public native app clients MUST implement the Proof Key for Code Public native app clients MUST implement the Proof Key for Code
Exchange (PKCE [RFC7636]) extension to OAuth, and authorization Exchange (PKCE [RFC7636]) extension to OAuth, and authorization
servers MUST support PKCE for such clients, for the reasons detailed servers MUST support PKCE for such clients, for the reasons detailed
in Section 8.1. in Section 8.1.
After constructing the authorization request URI, the app uses After constructing the authorization request URI, the app uses
platform-specific APIs to open the URI in an external user-agent. platform-specific APIs to open the URI in an external user-agent.
Typically the external user-agent used is the default browser, that Typically, the external user-agent used is the default browser, that
is, the application configured for handling "http" and "https" scheme is, the application configured for handling "http" and "https" scheme
URIs on the system, but different browser selection criteria and URIs on the system; however, different browser selection criteria and
other categories of external user-agents MAY be used. other categories of external user-agents MAY be used.
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. An external user-agent designed user-agent for native apps. An external user-agent designed
specifically for processing authorization requests capable of specifically for user authorization and capable of processing
processing the request and redirect URIs in the same way MAY also be authorization requests and responses like a browser MAY also be used.
used. Other external user-agents, such as a native app provided by Other external user-agents, such as a native app provided by the
the authorization server may meet the criteria set out in this best authorization server may meet the criteria set out in this best
practice, including using the same redirection URI properties, but practice, including using the same redirection URI properties, but
their use is out of scope for this specification. their use is out of scope for this specification.
Some platforms support a browser feature known as in-app browser Some platforms support a browser feature known as "in-app browser
tabs, where an app can present a tab of the browser within the app tabs", where an app can present a tab of the browser within the app
context without switching apps, but still retain key benefits of the context without switching apps, but still retain key benefits of the
browser such as a shared authentication state and security context. browser such as a shared authentication state and security context.
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 offer To fully support this best practice, authorization servers MUST offer
at least the following three redirect URI options to native apps. at least the three redirect URI options described in the following
Native apps MAY use whichever redirect option suits their needs best, subsections to native apps. Native apps MAY use whichever redirect
taking into account platform specific implementation details. option suits their needs best, 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 private-use URI scheme, the app that registered it
launched to handle the request. is launched to handle the request.
To perform an OAuth 2.0 authorization request with a private-use URI To perform an OAuth 2.0 authorization request with a private-use URI
scheme redirect, the native app launches the browser with a standard scheme redirect, the native app launches the browser with a standard
authorization request, but one where the redirection URI utilizes a authorization request, but one where the redirection URI utilizes a
custom URI scheme it registered with the operating system. private-use URI scheme it registered with the operating system.
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
URI scheme based on a domain name under their control, expressed in URI scheme based on a domain name under their control, expressed in
reverse order, as recommended by Section 3.8 of [RFC7595] for reverse order, as recommended by Section 3.8 of [RFC7595] for
private-use URI schemes. private-use URI schemes.
For example, an app that controls the domain name "app.example.com" For example, an app that controls the domain name "app.example.com"
can use "com.example.app" as their scheme. Some authorization can use "com.example.app" as their scheme. Some authorization
servers assign client identifiers based on domain names, for example servers assign client identifiers based on domain names, for example,
"client1234.usercontent.example.net", which can also be used as the "client1234.usercontent.example.net", which can also be used as the
domain name for the scheme when reversed in the same manner. A domain name for the scheme when reversed in the same manner. A
scheme such as "myapp" however would not meet this requirement, as it scheme such as "myapp", however, would not meet this requirement, as
is not based on a domain name. it is not based on a domain name.
Care must be taken when there are multiple apps by the same publisher When there are multiple apps by the same publisher, care must be
that each scheme is unique within that group. On platforms that use taken so that each scheme is unique within that group. On platforms
app identifiers that are also based on reverse order domain names, that use app identifiers based on reverse-order domain names, those
those can be reused as the private-use URI scheme for the OAuth identifiers can be reused as the private-use URI scheme for the OAuth
redirect to help avoid this problem. redirect to help avoid this problem.
Following the requirements of [RFC3986] Section 3.2, as there is no Following the requirements of Section 3.2 of [RFC3986], as there is
naming authority for private-use URI scheme redirects, only a single no naming authority for private-use URI scheme redirects, only a
slash ("/") appears after the scheme component. A complete example single slash ("/") appears after the scheme component. A complete
of a redirect URI utilizing a private-use URI scheme: example of a redirect URI utilizing a private-use URI scheme is:
com.example.app:/oauth2redirect/example-provider com.example.app:/oauth2redirect/example-provider
When the authentication server completes the request, it redirects to When the authorization 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 private-use URI scheme, it results in the
system launching the native app, passing in the URI as a launch operating system launching the native app, passing in the URI as a
parameter. The native app then processes the authorization response launch parameter. Then, the native app uses normal processing for
like normal. the authorization response.
7.2. Claimed HTTPS URI Redirection 7.2. Claimed "https" Scheme URI Redirection
Some operating systems allow apps to claim HTTPS scheme [RFC7230] Some operating systems allow apps to claim "https" scheme [RFC7230]
URIs in domains they control. When the browser encounters a claimed URIs in the domains they control. When the browser encounters a
URI, instead of the page being loaded in the browser, the native app claimed URI, instead of the page being loaded in the browser, the
is launched with the URI supplied as a launch parameter. native app is launched with the URI supplied as a launch parameter.
Such URIs can be used as redirect URIs by native apps. They are Such URIs can be used as redirect URIs by native apps. They are
indistinguishable to the authorization server from a regular web- indistinguishable to the authorization server from a regular web-
based client redirect URI. An example is: based client redirect URI. An example is:
https://app.example.com/oauth2redirect/example-provider https://app.example.com/oauth2redirect/example-provider
As the redirect URI alone is not enough to distinguish public native As the redirect URI alone is not enough to distinguish public native
app clients from confidential web clients, it is REQUIRED in app clients from confidential web clients, it is REQUIRED in
Section 8.4 that the client type be recorded during client Section 8.4 that the client type be recorded during client
registration to enable the server to determine the client type and registration to enable the server to determine the client type and
act accordingly. act accordingly.
App-claimed HTTPS redirect URIs have some advantages compared to App-claimed "https" scheme redirect URIs have some advantages
other native app redirect options in that the identity of the compared to other native app redirect options in that the identity of
destination app is guaranteed to the authorization server by the the destination app is guaranteed to the authorization server by the
operating system. For this reason, native apps SHOULD use them over operating system. For this reason, native apps SHOULD use them over
the other options where possible. 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.
That is, "http://127.0.0.1:{port}/{path}" for IPv4, and That is, "http://127.0.0.1:{port}/{path}" for IPv4, and
"http://[::1]:{port}/{path}" for IPv6. An example redirect using the "http://[::1]:{port}/{path}" for IPv6. An example redirect using the
IPv4 loopback interface with a randomly assigned port: IPv4 loopback interface with a randomly assigned port:
http://127.0.0.1:50719/oauth2redirect/example-provider http://127.0.0.1:51004/oauth2redirect/example-provider
An example redirect using the IPv6 loopback interface with a randomly An example redirect using the IPv6 loopback interface with a randomly
assigned port: assigned port:
http://[::1]:61023/oauth2redirect/example-provider http://[::1]:61023/oauth2redirect/example-provider
The authorization server MUST allow any port to be specified at the The authorization server MUST allow any port to be specified at the
time of the request for loopback IP redirect URIs, to accommodate time of the request for loopback IP redirect URIs, to accommodate
clients that obtain an available ephemeral port from the operating clients that obtain an available ephemeral port from the operating
system at the time of the request. system at the time of the request.
Clients SHOULD NOT assume the device supports a particular version of Clients SHOULD NOT assume that the device supports a particular
the Internet Protocol. It is RECOMMENDED that clients attempt to version of the Internet Protocol. It is RECOMMENDED that clients
bind to the loopback interface using both IPv4 and IPv6, and use attempt to bind to the loopback interface using both IPv4 and IPv6
whichever is available. and use 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 or the app's own website
authorization code which limits the attack surface, however code can receive the authorization code, which limits the attack surface.
interception by a different native app running on the same device may However, code interception by a different native app running on the
be possible. same device may 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. Section 1 of PKCE [RFC7636] details how this limitation can be code. Section 1 of PKCE [RFC7636] details how this limitation can be
used to execute a code interception attack. 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 accessing the same loopback interface on some operating other apps accessing the same loopback interface on some operating
systems. systems.
App-claimed HTTPS redirects are less susceptible to URI interception App-claimed "https" scheme redirects are less susceptible to URI
due to the presence of the URI authority, but they are still public interception due to the presence of the URI authority, but the app is
clients and the URI is sent using the operating system's URI dispatch still a public client; further, the URI is sent using the operating
handler with unknown security properties. system's URI dispatch handler with unknown security properties.
The Proof Key for Code Exchange by OAuth Public Clients (PKCE The PKCE [RFC7636] protocol was created specifically to mitigate 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 authorization code from being used if it is intercepted.
protects the code grant from being used if it is intercepted. It To provide protection, this extension has the client generate a
achieves this by having the client generate a secret verifier, a hash secret verifier; it passes a hash of this verifier in the initial
of which it passes in the initial authorization request, and which it authorization request, and must present the unhashed verifier when
must present in full when redeeming the authorization code grant. An redeeming the authorization code. An app that intercepted the
app that intercepted the authorization code would not be in authorization code would not be in possession of this secret,
possession of this secret, rendering the code useless. rendering the code useless.
Section 6 requires that both clients and servers use PKCE for public Section 6 requires that both clients and servers use PKCE for 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 (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 [RFC7636] However, as the implicit flow cannot be protected by PKCE [RFC7636]
(which is a required in Section 8.1), the use of the Implicit Flow (which is required in Section 8.1), the use of the Implicit Flow with
with native apps is NOT RECOMMENDED. native apps is NOT RECOMMENDED.
Tokens granted via the implicit flow also cannot be refreshed without Access tokens granted via the implicit flow also cannot be refreshed
user interaction, making the authorization code grant flow - which without user interaction, making the authorization code grant flow --
can issue refresh tokens - the more practical option for native app which can issue refresh tokens -- the more practical option for
authorizations that require refreshing. native app authorizations that require refreshing of access tokens.
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 Transport Layer Security (TLS)). This is acceptable for loopback
HTTP request never leaves the device. interface redirect URIs as the HTTP request never leaves the device.
Clients should open the network port only when starting the Clients should open the network 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.
Clients should listen on the loopback network interface only, to Clients should listen on the loopback network interface only, in
avoid interference by other network actors. order to avoid interference by other network actors.
While redirect URIs using localhost (i.e., While redirect URIs using localhost (i.e.,
"http://localhost:{port}/") function similarly to loopback IP "http://localhost:{port}/{path}") function similarly to loopback IP
redirects described in Section 7.3, the use of "localhost" is NOT redirects described in Section 7.3, the use of localhost is NOT
RECOMMENDED. Specifying a redirect URI with the loopback IP literal RECOMMENDED. Specifying a redirect URI with the loopback IP literal
rather than localhost avoids inadvertently listening on network rather than localhost avoids inadvertently listening on network
interfaces other than the loopback interface. It is also less interfaces other than the loopback interface. It is also less
susceptible to client side firewalls, and misconfigured host name susceptible to client-side firewalls and misconfigured host name
resolution on the user's device. resolution on the user's device.
8.4. Registration of Native App Clients 8.4. Registration of Native App Clients
Native apps, except when using a mechanism like Dynamic Client Except when using a mechanism like Dynamic Client Registration
Registration [RFC7591] to provision per-instance secrets, are [RFC7591] to provision per-instance secrets, native apps are
classified as public clients, as defined by Section 2.1 of OAuth 2.0 classified as public clients, as defined by Section 2.1 of OAuth 2.0
[RFC6749] and MUST be registered with the authorization server as [RFC6749]; they MUST be registered with the authorization server as
such. Authorization servers MUST record the client type in the such. Authorization servers MUST record the client type in the
client registration details in order to identify and process requests client registration details in order to identify and process requests
accordingly. accordingly.
Authorization servers MUST require clients to register their complete Authorization servers MUST require clients to register their complete
redirect URI (including the path component), and reject authorization redirect URI (including the path component) and reject authorization
requests that specify a redirect URI that doesn't exactly match the requests that specify a redirect URI that doesn't exactly match the
one that was registered, with the exception of loopback redirects, one that was registered; the exception is loopback redirects, where
where an exact match is required except for the port URI component. an exact match is required except for the port URI component.
For private-use URI scheme based redirects, authorization servers For private-use URI scheme-based redirects, authorization servers
SHOULD enforce the requirement in Section 7.1 that clients use SHOULD enforce the requirement in Section 7.1 that clients use
reverse domain name based schemes. At a minimum, any scheme that schemes that are reverse domain name based. At a minimum, any
doesn't contain a period character ("."), SHOULD be rejected. private-use URI scheme that doesn't contain a period character (".")
SHOULD be rejected.
In addition to the collision resistant properties, requiring a URI In addition to the collision-resistant properties, requiring a URI
scheme based on a domain name that is under the control of the app scheme based on a domain name that is under the control of the app
can help to prove ownership in the event of a dispute where two apps can help to prove ownership in the event of a dispute where two apps
claim the same private-use URI scheme (where one app is acting claim the same private-use URI scheme (where one app is acting
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. Such a petition is harder to prove if a remove the counterfeit app. Such a petition is harder to prove if a
generic URI scheme was used. generic URI scheme was used.
Authorization servers MAY request the inclusion of other platform- Authorization servers MAY request the inclusion of other platform-
specific information, such as the app package or bundle name, or specific information, such as the app package or bundle name, or
other information used to associate the app that may be useful for other information that may be useful for verifying the calling app's
verifying the calling app's identity, on operating systems that identity on operating systems that support such functions.
support such functions.
8.5. Client Authentication 8.5. 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
authentication of public native apps clients using a shared secret, authentication of public native apps clients using a shared secret,
as this serves little value beyond client identification which is as this serves little value beyond client identification which is
skipping to change at page 13, line 4 skipping to change at page 13, line 21
accept the secret as proof of the client's identity. Without accept the secret as proof of the client's identity. Without
additional measures, such clients are subject to client impersonation additional measures, such clients are subject to client impersonation
(see Section 8.6). (see Section 8.6).
8.6. Client Impersonation 8.6. Client Impersonation
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. 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" scheme 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 that MAY be
accepted, as appropriate. accepted, as appropriate.
8.7. Fake External User-Agent 8.7. Fake External User-Agents
The native app which is initiating the authorization request has a The native app that is initiating the authorization request has a
large degree of control over the user interface and can potentially large degree of control over the user interface and can potentially
present a fake external user-agent, that is, an embedded user-agent present a fake external user-agent, that is, an embedded user-agent
made to appear as an external user agent. made to appear as an external user-agent.
The advantage when all good actors are using external user-agents is When all good actors are using external user-agents, the advantage is
that it is possible for security experts to detect bad actors, as that it is possible for security experts to detect bad actors, as
anyone faking an external user-agent is provably bad. If good and anyone faking an external user-agent is provably bad. On the other
bad actors alike are using embedded user-agents, bad actors don't hand, if good and bad actors alike are using embedded user-agents,
need to fake anything, making them harder to detect. Once malicious bad actors don't need to fake anything, making them harder to detect.
apps are detected, it may be possible to use this knowledge to Once a malicious app is detected, it may be possible to use this
blacklist the apps signatures in malware scanning software, take knowledge to blacklist the app's signature in malware scanning
removal action in the case of apps distributed by app stores, and software, take removal action (in the case of apps distributed by app
other steps to reduce the impact and spread of the malicious app. stores) and other steps to reduce the impact and spread of the
malicious app.
Authorization servers can also directly protect against fake external Authorization servers can also directly protect against fake external
user-agents by requiring an authentication factor only available to user-agents by requiring an authentication factor only available to
true external user-agents. true external user-agents.
Users who are particularly concerned about their security when using Users who are particularly concerned about their security when using
in-app browser tabs may also take the additional step of opening the in-app browser tabs may also take the additional step of opening the
request in the full browser from the in-app browser tab, and complete request in the full browser from the in-app browser tab and complete
the authorization there, as most implementations of the in-app the authorization there, as most implementations of the in-app
browser tab pattern offer such functionality. browser tab pattern offer such functionality.
8.8. Malicious External User-Agent 8.8. Malicious External User-Agents
If a malicious app is able to configure itself as the default handler 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 for "https" scheme URIs in the operating system, it will be able to
intercept authorization requests that use the default browser and intercept authorization requests that use the default browser and
abuse this position of trust for malicious ends such as phishing the abuse this position of trust for malicious ends such as phishing the
user. user.
Many operating systems mitigate this issue by requiring an explicit This attack is not confined to OAuth; a malicious app configured in
user action to change the default handler for HTTP URIs. This attack this way would present a general and ongoing risk to the user beyond
is not confined to OAuth for Native Apps, a malicious app configured OAuth usage by native apps. Many operating systems mitigate this
in this way would present a general and ongoing risk to the user issue by requiring an explicit user action to change the default
beyond OAuth usage. handler for "http" and "https" scheme URIs.
8.9. Cross-App Request Forgery Protections 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 over inter-app URI communication
is similarly RECOMMENDED that native apps include a high entropy channels (so called "cross-app request forgery"), it is similarly
secure random number in the "state" parameter of the authorization RECOMMENDED that native apps include a high-entropy secure random
request, and reject any incoming authorization responses without a number in the "state" parameter of the authorization request and
state value that matches a pending outgoing authorization request. reject any incoming authorization responses without a state value
that matches a pending outgoing authorization request.
8.10. 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 an 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 requirement of Section 8.4, specifically that authorization
requests with URIs that don't match what was registered are also servers reject requests with URIs that don't match what was
required to prevent such attacks. registered, is also required to prevent such attacks.
8.11. 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.12. Embedded User-Agents 8.12. Embedded User-Agents
OAuth 2.0 [RFC6749] Section 9 documents two approaches for native Section 9 of OAuth 2.0 [RFC6749] 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
apps. These embedded user agents are unsafe for use by third-parties apps. These embedded user-agents are unsafe for use by third parties
to the authorization server by definition, as the app that hosts the to the authorization server by definition, as the app that hosts the
embedded user-agent can access the user's full authentication embedded user-agent can access the user's full authentication
credential, not just the OAuth authorization grant that was intended credential, not just the OAuth authorization grant that was intended
for the app. for the app.
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 record every keystroke entered in the login
capture usernames and passwords; automatically submit forms and form to capture usernames and passwords, automatically submit forms
bypass user-consent; copy session cookies and use them to perform to bypass user consent, and copy session cookies and use them to
authenticated actions as the user. perform authenticated actions as the user.
Even when used by trusted apps belonging to the same party as the Even when used by trusted apps belonging to the same party as the
authorization server, embedded user-agents violate the principle of authorization server, embedded user-agents violate the principle of
least privilege by having access to more powerful credentials than least privilege by having access to more powerful credentials than
they need, potentially increasing the attack surface. they need, potentially increasing the attack surface.
Encouraging users to enter credentials in an embedded user-agent 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; even when they are, it
are, it trains them that it's OK to enter credentials without trains them that it's OK to enter credentials without validating the
validating the site first. site first.
Aside from the security concerns, embedded user-agents do not share Aside from the security concerns, embedded user-agents do not share
the authentication state with other apps or the browser, requiring the authentication state with other apps or the browser, requiring
the user to login for every authorization request which is often the user to log in for every authorization request, which is often
considered an inferior user experience. considered an inferior user experience.
9. IANA Considerations 9. IANA Considerations
[RFC Editor: please do NOT remove this section.] This document does not require any IANA actions.
This document has no IANA actions.
Section 7.1 specifies how private-use URI schemes are used for inter- Section 7.1 specifies how private-use URI schemes are used for inter-
app communication in OAuth protocol flows. This document requires in app communication in OAuth protocol flows. This document requires in
Section 7.1 that such schemes are based on domain names owned or Section 7.1 that such schemes are based on domain names owned or
assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per
Section 6 of [RFC7595], registration of domain based URI schemes with Section 6 of [RFC7595], registration of domain-based URI schemes with
IANA is not required. IANA is not required.
10. References 10. References
10.1. Normative References 10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[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>. <https://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>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>. <https://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>. <https://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>. <https://www.rfc-editor.org/info/rfc7636>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
10.2. Informative References 10.2. Informative References
[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>. <https://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>. <https://www.rfc-editor.org/info/rfc7591>.
[AppAuth] Denniss, W., Wright, S., McGinniss, I., Ravikumar, R., and [AppAuth] OpenID Connect Working Group, "AppAuth", September 2017,
others, "AppAuth", May 22, <https://appauth.io>. <https://openid.net/code/AppAuth>.
[AppAuth.iOSmacOS] [AppAuth.iOSmacOS]
Wright, S., Denniss, W., and others, "AppAuth for iOS and Wright, S., Denniss, W., et al., "AppAuth for iOS and
macOS", February 2016, <https://github.com/openid/AppAuth- macOS", February 2016,
iOS>. <https://openid.net/code/AppAuth-iOS>.
[AppAuth.Android] [AppAuth.Android]
McGinniss, I., Denniss, W., and others, "AppAuth for McGinniss, I., Denniss, W., et al., "AppAuth for Android",
Android", February 2016, <https://github.com/openid/ February 2016, <https://openid.net/code/AppAuth-Android>.
AppAuth-Android>.
[SamplesForWindows] [SamplesForWindows]
Denniss, W., "OAuth for Apps: Samples for Windows", July Denniss, W., "OAuth for Apps: Samples for Windows", July
2016, <https://github.com/googlesamples/oauth-apps-for- 2016,
windows>. <https://openid.net/code/sample-oauth-apps-for-windows>.
Appendix A. Server Support Checklist Appendix A. Server Support Checklist
OAuth servers that support native apps must: OAuth servers that support native apps must:
1. Support private-use URI scheme redirect URIs. This is required 1. Support private-use URI scheme redirect URIs. This is required
to support mobile operating systems. See Section 7.1. to support mobile operating systems. See Section 7.1.
2. Support HTTPS scheme redirect URIs for use with public native app 2. Support "https" scheme redirect URIs for use with public native
clients. This is used by apps on advanced mobile operating app clients. This is used by apps on advanced mobile operating
systems that allow app-claimed URIs. See Section 7.2. systems that allow app-claimed "https" scheme URIs. See
Section 7.2.
3. Support loopback IP redirect URIs. This is required to support 3. Support loopback IP redirect URIs. This is required to support
desktop operating systems. See Section 7.3. desktop operating systems. See Section 7.3.
4. Not assume native app clients can keep a secret. If secrets are 4. Not assume that native app clients can keep a secret. If secrets
distributed to multiple installs of the same native app, they are 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. Platform-Specific Implementation Details
This document primarily defines best practices in a 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 implementation
specific implementation details of the best practice. details of the best practice for various operating systems.
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 a change won't invalidate the generic principles in the rest of
the document, and those principles should take precedence in the the document and that those principles should take precedence in the
event of a conflict. event of a conflict.
B.1. iOS Implementation Details B.1. iOS Implementation Details
Apps can initiate an authorization request in the browser without the Apps can initiate an authorization request in the browser, without
user leaving the app, through the SFSafariViewController class which the user leaving the app, through the "SFSafariViewController" class
implements the in-app browser tab pattern. Safari can be used to or its successor "SFAuthenticationSession", which implement the in-
handle requests on old versions of iOS without app browser tab pattern. Safari can be used to handle requests on
SFSafariViewController. old versions of iOS without in-app browser tab functionality.
To receive the authorization response, both private-use URI scheme To receive the authorization response, both private-use URI scheme
redirects (referred to as Custom URL Schemes) and claimed HTTPS links (referred to as "custom URL scheme") redirects and claimed "https"
(known as Universal Links) are viable choices, and function the same scheme URIs (known as "Universal Links") are viable choices. Apps
whether the request is loaded in SFSafariViewController or the Safari can claim private-use URI schemes with the "CFBundleURLTypes" key in
app. Apps can claim Custom URI schemes with the "CFBundleURLTypes" the application's property list file, "Info.plist", and "https"
key in the application's property list file "Info.plist", and HTTPS scheme URIs using the Universal Links feature with an entitlement
links using the Universal Links feature with an entitlement file and file in the app and an association file hosted on the domain.
an association file on the domain.
Universal Links are the preferred choice on iOS 9 and above due to Claimed "https" scheme URIs are the preferred redirect choice on iOS
the ownership proof that is provided by the operating system. 9 and above due to the ownership proof that is provided by the
operating system.
A complete open source sample is included in the AppAuth for iOS and A complete open-source sample is included in the AppAuth for iOS and
macOS [AppAuth.iOSmacOS] library. macOS [AppAuth.iOSmacOS] library.
B.2. Android Implementation Details B.2. Android Implementation Details
Apps can initiate an authorization request in the browser without the Apps can initiate an authorization request in the browser, without
user leaving the app, through the Android Custom Tab feature which the user leaving the app, through the Android Custom Tab feature,
implements the in-app browser tab pattern. The user's default which 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 Intents. Claimed HTTPS broadly supported through Android Implicit Intents. Claimed "https"
redirect URIs through Android App Links are available on Android 6.0 scheme redirect URIs through Android App Links are available on
and above. Both types of redirect URIs are registered in the Android 6.0 and above. Both types of redirect URIs are registered in
application's manifest. the 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
Both traditional and Universal Windows Platform (UWP) apps can Both traditional and Universal Windows Platform (UWP) apps can
perform authorization requests in the user's browser. Traditional perform authorization requests in the user's browser. Traditional
apps typically use a loopback redirect to receive the authorization apps typically use a loopback redirect to receive the authorization
response, and listening on the loopback interface is allowed by response, and listening on the loopback interface is allowed by
default firewall rules. When creating the loopback network socket, default firewall rules. When creating the loopback network socket,
apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent
other apps binding to the same socket. other apps binding to the same socket.
UWP apps can use private-use URI scheme redirects to receive the UWP apps can use private-use URI scheme redirects to receive the
authorization response from the browser, which will bring the app to authorization response from the browser, which will bring the app to
the foreground. Known on the platform as "URI Activation", the URI the foreground. Known on the platform as "URI Activation", the URI
scheme is limited to 39 characters in length, and may include the "." scheme is limited to 39 characters in length, and it may include the
character, making short reverse domain name based schemes (as "." character, making short reverse domain name based schemes (as
recommended in Section 7.1) possible. required in Section 7.1) possible.
UWP apps can alternatively use the Web Authentication Broker API in UWP apps can alternatively use the Web Authentication Broker API in
SSO (Single Sign-on) mode, which is an external user agent designed Single Sign-on (SSO) mode, which is an external user-agent designed
for authorization flows. Cookies are shared between invocations of for authorization flows. Cookies are shared between invocations of
the broker but not the user's preferred browser, meaning the user 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 will need to log in again, even if they have an active session in
their browser, but the session created in the broker will be their browser; but the session created in the broker will be
available to subsequent apps that use the broker. Personalisations available to subsequent apps that use the broker. Personalizations
the user has made to their browser, such as configuring a password the user has made to their browser, such as configuring a password
manager may not available in the broker. To qualify as an external manager, may not be available in the broker. To qualify as an
user-agent, the broker MUST be used in SSO mode. 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 security identifier (SID), which can be found in the app's
Windows enforces the URI authority on such redirects, ensuring only registration information or by calling the
the app with the matching SID can receive the response on Windows, "GetCurrentApplicationCallbackUri" method. While Windows enforces
the URI scheme could be claimed by apps on other platforms without the URI authority on such redirects, ensuring that only the app with
the same authority present, thus this redirect type should be treated the matching SID can receive the response on Windows, the URI scheme
similar to private-use URI scheme redirects for security purposes. could be claimed by apps on other platforms without the same
authority present; thus, this redirect type should be treated
similarly to private-use URI scheme redirects for security purposes.
An open source sample demonstrating these patterns is available 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 a To receive the authorization response, private-use URI schemes are a
good redirect URI choice on macOS, as the user is returned right back good redirect URI choice on macOS, as the user is returned right back
to the app they launched the request from. These are registered in to the app they launched the request from. These are registered in
the application's bundle information property list using the the application's bundle information property list using the
"CFBundleURLSchemes" key. Loopback IP redirects are another viable "CFBundleURLSchemes" key. Loopback IP redirects are another viable
option, and listening on the loopback interface is allowed by default option, and listening on the loopback interface is 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 SHOULD NOT apps on Linux to receive the authorization response. Apps SHOULD NOT
set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options, to prevent set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options in order to
other apps binding to the same socket. prevent other apps binding to the same socket.
Appendix C. Acknowledgements Acknowledgements
The author would like to acknowledge the work of Marius Scurtescu, The authors 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 app 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:
Andy Zmolek, Steven E Wright, Brian Campbell, Nat Sakimura, Eric Andy Zmolek, Steven E. Wright, Brian Campbell, Nat Sakimura, Eric
Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de
Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill
Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick
Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn
Davies. Davies.
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 United States of America
Email: wdenniss@google.com Email: rfc8252@wdenniss.com
URI: http://wdenniss.com/appauth URI: http://wdenniss.com/appauth
John Bradley John Bradley
Ping Identity Ping Identity
Phone: +1 202-630-5272 Phone: +1 202-630-5272
Email: ve7jtb@ve7jtb.com Email: rfc8252@ve7jtb.com
URI: http://www.thread-safe.com/p/appauth.html URI: http://www.thread-safe.com/p/appauth.html
 End of changes. 156 change blocks. 
334 lines changed or deleted 338 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/