One document matched: draft-ietf-oauth-native-apps-05.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="2"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="no"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="bcp" docName="draft-ietf-oauth-native-apps-05"
ipr="trust200902">
<front>
<title>OAuth 2.0 for Native Apps</title>
<author fullname="William Denniss" initials="W." surname="Denniss">
<organization>Google</organization>
<address>
<postal>
<street>1600 Amphitheatre Pkwy</street>
<city>Mountain View</city>
<region>CA</region>
<code>94043</code>
<country>USA</country>
</postal>
<email>wdenniss@google.com</email>
<uri>http://wdenniss.com/appauth</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>Ping Identity</organization>
<address>
<phone>+1 202-630-5272</phone>
<email>ve7jtb@ve7jtb.com</email>
<uri>http://www.thread-safe.com/p/appauth.html</uri>
</address>
</author>
<date day="21" month="October" year="2016"/>
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<abstract>
<t>
OAuth 2.0 authorization requests from native apps should only
be made through external user-agents, primarily the user's browser.
This specification details the security and usability reasons why
this is the case, and how native apps and authorization servers
can implement this best practice.
</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="intro">
<t>
The <xref target="RFC6749">OAuth 2.0</xref> authorization framework
documents two approaches in Section 9 for native apps to interact with
the authorization endpoint: an embedded user-agent, or an external
user-agent.
</t>
<t>
This best current practice recommends that only external user-agents
like the browser are used for OAuth by native apps. It documents how
native apps can implement authorization flows using the browser
as the preferred external user-agent, and the requirements for
authorization servers to support such usage.
</t>
<t>
This practice is also known as the AppAuth pattern, in reference to
open source libraries that implement it.
</t>
</section>
<section title="Notational Conventions" anchor="NotationalConventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as described in
Key words for use in RFCs to Indicate Requirement Levels
<xref target='RFC2119' />. If these words are used without being spelled
in uppercase then they are to be interpreted with their normal natural
language meanings.
</t>
</section>
<section title="Terminology" anchor="terminology">
<t>
In addition to the terms defined in referenced specifications, this
document uses the following terms:
</t>
<t>
<list style="hanging">
<t hangText='"native app"'>
An application that is installed by the user to their device, as distinct from
a web app that runs in the browser context only.
Apps implemented using web-based technology but distributed as a native
app, so-called hybrid apps, are considered equivalent to native apps
for the purpose of this specification.
</t>
<t hangText='"OAuth"'>
In this document, OAuth refers to
<xref target="RFC6749">OAuth 2.0</xref>.
</t>
<t hangText='"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.
</t>
<t hangText='"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.
</t>
<t hangText='"app"'>
Shorthand for "native app".
</t>
<t hangText='"app store"'>
An ecommerce store where users can download and purchase apps.
</t>
<t hangText='"browser"'>
The operating system's default browser, pre-installed as
part of the operating system, or installed and set as default by
the user.
</t>
<t hangText='"browser tab"'>
An open page of the browser. Browser typically have multiple
"tabs" representing various open pages.
</t>
<t hangText='"in-app browser tab"'>
A full page browser with limited navigation capabilities that is
displayed inside a host app, but retains the full security
properties and authentication state of the browser. Has
different platform-specific product names, such as
SFSafariViewController on iOS, and Chrome Custom Tab on Android.
</t>
<t hangText='"inter-app communication"'>
Communication between two apps on a device.
</t>
<t hangText='"claimed HTTPS URL"'>
Some platforms allow apps to claim a HTTPS URL after proving
ownership of the domain name. URLs claimed in such a way are then
opened in the app instead of the browser.
</t>
<t hangText='"custom URI scheme"'>
A URI scheme (as defined by <xref target='RFC3986' />) that
the app creates and registers with the OS (and is not a standard URI
scheme like <spanx style="verb">https:</spanx> or
<spanx style="verb">tel:</spanx>). Requests to such a scheme results
in the app which registered it being launched by the OS.
</t>
<t hangText='"web-view"'>
A web browser UI component that can be embedded in apps to render
web pages, used to create embedded user-agents.
</t>
<t hangText='"reverse domain name notation"'>
A naming convention based on the domain name system, but where
where the domain components are reversed, for example
<spanx style="verb">app.example.com</spanx> becomes
<spanx style="verb">com.example.app</spanx>.
</t>
</list>
</t>
</section>
<section title="Overview" anchor="overview">
<t>
The best current practice for authorizing users in native apps is
to perform the OAuth authorization request in an external user-agent
(typically the browser), rather than an embedded user-agent (such as
one implemented with web-views).
</t>
<t>
Previously it was common for native apps to use embedded user-agents
(commonly implemented with web-views) for OAuth
authorization requests. That approach has many drawbacks,
including the host app being able to copy user credentials and cookies,
and the user needing to authenticate from scratch in each app. See
<xref target="security-webviews" /> for a deeper analysis of using
embedded user-agents for OAuth.
</t>
<t>
Native app authorization requests that use the browser are
more secure and can take advantage of the user's authentication state.
Being able to use the existing authentication session in the browser enables
single sign-on, as users don't need to authenticate to the authorization
server each time they use a new app (unless required by authorization
server policy).
</t>
<t>
Supporting authorization flows between a native app and the browser
is possible without changing the OAuth protocol itself, as the
authorization request and response are already defined in terms of URIs,
which emcompasses URIs that can be used for inter-process communication.
Some OAuth server implementations that
assume all clients are confidential web-clients will need to add an
understanding of native app OAuth clients and the types of redirect URIs
they use to support this best practice.
</t>
<section title="Authorization Flow for Native Apps Using the Browser" anchor="intro-overview">
<t>
<figure anchor="figure_mobile_apps_overview"
title="Native App Authorization via External User-agent">
<artwork><![CDATA[
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
| User Device |
| |
| +---------------------------+ | +-----------+
| | | | (5) Authz Code | |
| | Client App |----------------------->| Token |
| | |<-----------------------| Endpoint |
| +---------------------------+ | (6) Access Token, | |
| | ^ | Refresh Token +-----------+
| | | |
| | | |
| | (1) | (4) |
| | Authz | Authz |
| | Request | Code |
| | | |
| | | |
| v | |
| +---------------------------+ | +---------------+
| | | | (2) Authz Request | |
| | Browser |--------------------->| Authorization |
| | |<---------------------| Endpoint |
| +---------------------------+ | (3) Authz Code | |
| | +---------------+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
]]></artwork>
</figure>
</t>
<t>Figure 1 illustrates the interaction of the native app with the system
browser to authorize the user via an external user-agent.
<list style="format (%d)">
<t>
The client app opens a browser tab with the authorization
request.
</t>
<t>
Authorization endpoint receives the authorization request,
authenticates the user and obtains authorization. Authenticating
the user may involve chaining to other authentication systems.
</t>
<t>
Authorization server issues an authorization code to the
redirect URI.
</t>
<t>
Client receives the authorization code from the redirect URI.
</t>
<t>
Client app presents the authorization code at the token
endpoint.
</t>
<t>
Token endpoint validates the authorization code and issues
the tokens requested.
</t>
</list>
</t>
</section>
</section>
<section title="Using Inter-app URI Communication for OAuth">
<t>
Just as URIs are used for <xref target="RFC6749">OAuth 2.0</xref> on
the web to initiate the authorization request and return the
authorization response to the requesting website, URIs can be used by
native apps to initiate the authorization request in the device's
browser and return the response to the requesting native app.
</t>
<t>
By applying the same principles from the web to native apps, we gain
similar benefits like the usability of a single sign-on session, and
the security of a separate authentication context. It also reduces the
implementation complexity by reusing the same flows as the web, and
increases interoperability by relying on standards-based web flows that
are not specific to a particular platform.
</t>
<t>
Native apps MUST use an external user-agent to perform OAuth
authentication requests. This is achieved by
opening the authorization request in the browser
(detailed in <xref target="authorization-request" />),
and using a redirect URI that will return the authorization response
back to the native app, as defined in <xref target="authorization-response" />.
</t>
<t>
This best practice focuses on the browser as the RECOMMENDED external
user-agent for native apps. Other external user-agents, such as a
native app provided by the authorization server may meet the criteria
set out in this best practice, including using the same redirection URI
properties, but their use is out of scope for this specification.
</t>
</section>
<section title="Initiating the Authorization Request from a Native App"
anchor="authorization-request">
<t>
The authorization request is created as per <xref target="RFC6749">OAuth
2.0</xref>, and opened in the user's browser using platform-specific
APIs for that purpose.
</t>
<t>
The function of the redirect URI for a native app authorization request
is similar to that of a web-based authorization request. Rather than
returning the authorization response to the OAuth client's server, the
redirect URI used by a native app returns the response to the app. The
various options for a redirect URI that will return the code to the
native app are documented in <xref target='authorization-response' />.
Any redirect URI that allows the app to receive the URI and inspect its
parameters is viable.
</t>
<t>
Some platforms support a browser feature known as in-app browser tabs,
where an app can present a tab of the browser within the app context
without switching apps, but still retain key benefits of the browser
such as a shared authentication state and security context. On platforms
where they are supported, it is RECOMMENDED for usability reasons that
apps use in-app browser tabs for the Authorization Request.
</t>
</section>
<section title="Receiving the Authorization Response in a Native App"
anchor="authorization-response">
<t>
There are several redirect URI options available to native apps for
receiving the authorization response from the browser, the availability
and user experience of which varies by platform.
</t>
<t>
To fully support this best practice, authorization servers MUST support
the following three redirect URI options. Native apps MAY use
whichever redirect option suits their needs best, taking into account
platform specific implementation details.
</t>
<section title="App-declared Custom URI Scheme Redirection" anchor="custom-uri-scheme">
<t>
Many mobile and desktop computing platforms support inter-app communication via URIs
by allowing apps to register custom URI schemes, like
<spanx style="verb">com.example.app:</spanx>. When the browser or
another app attempts to load a URI with a custom scheme, the app that
registered it is launched to handle the request.
</t>
<t>
To perform an OAuth 2.0 Authorization Request with a custom URI
scheme-based redirect URI,
the native app launches the browser with a normal OAuth 2.0 Authorization Request,
but provides a redirection URI that utilizes a custom
URI scheme registered with the operating system by the calling app.
</t>
<t>
When the authentication server completes the request, it redirects
to 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
launching the native app passing in the URI. The native app
then processes the authorization response like any OAuth client.
</t>
<section title="Custom URI Scheme Namespace Considerations" anchor="namespace-considerations">
<t>
When choosing a URI scheme to associate with the app, apps MUST
use a URI scheme based on a domain name under their control,
expressed in reverse order, as recommended by Section 3.8 of
<xref target="RFC7595" /> for private-use URI schemes.
</t>
<t>
For example, an app that controls the domain name
<spanx style="verb">app.example.com</spanx> can use
<spanx style="verb">com.example.app:/</spanx> as their custom scheme.
Some authorization servers assign client identifiers based on domain
names, for example
<spanx style="verb">client1234.usercontent.example.net</spanx>,
which can also be used as the domain name for the custom scheme,
when reversed in the same manner, for example
<spanx style="verb">net.example.usercontent.client1234</spanx>.
</t>
<t>
URI schemes not based on a domain name (for example
<spanx style="verb">myapp:/</spanx>) MUST NOT be used, as they are
not collision resistant, and don't comply with
Section 3.8 of <xref target="RFC7595" />.
</t>
<t>
Care must be taken when there are multiple apps by the same publisher
that each URI scheme is unique within that group. On platforms that use
app identifiers that are also based on reverse order domain
names, those can be re-used as the custom URI scheme for the OAuth
redirect.
</t>
<t>
In addition to the collision resistant properties, basing the URI
scheme off a domain name that is under the control of the app can
help to prove ownership in the event of a dispute where two apps
claim the same custom scheme (such as if an app is acting
maliciously). For example, if two apps claimed
<spanx style="verb">com.example.app:</spanx>, the owner of
<spanx style="verb">example.com</spanx> could petition
the app store operator to remove the counterfeit app. This petition
is harder to prove if a generic URI scheme was used.
</t>
</section>
</section>
<section title="App-claimed HTTPS URI Redirection" anchor="App-Claimed">
<t>
Some operating systems allow apps to claim HTTPS URLs in their domains.
When the browser encounters a claimed URL, instead of the page being
loaded in the browser, the native app is launched instead with the URL
supplied as a launch parameter.
</t>
<t>
App-claimed HTTPS redirect URIs have some advantages in that the
identity of the destination app is guaranteed by the operating system.
Due to this reason, they SHOULD be used over the other redirect
choices for native apps where possible.
</t>
<t>
App-claimed HTTPS redirect URIs function as normal HTTPS
redirects from the perspective of the authorization server, though
it is RECOMMENDED that the authorization server is able to distinguish
between public native app clients that use app-claimed HTTPS redirect
URIs and confidential web clients. A configuration option in the
client registration (as documented in
<xref target="customuri-registration" />) is one method for
distinguishing client types.
</t>
</section>
<section title="Loopback URI Redirection" anchor="Loopback">
<t>
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 authorization responses on compatible
platforms.
</t>
<t>
Loopback redirect URIs take the form of the loopback IP, any port
(dynamically provided by the client), and a path component.
Specifically:
<spanx style="verb">http://127.0.0.1:{port}/{path}</spanx> for IPv4,
and <spanx style="verb">http://[::1]:{port}/{path}</spanx> for IPv6.
</t>
<t>
For loopback IP redirect URIs, the authorization server MUST allow
any port to be specified at the time of the request, to accommodate
clients that obtain an available port from the operating
system at the time of the request. Other than that, the redirect is be
treated like any other.
</t>
</section>
</section>
<section title="Security Considerations" anchor="security-considerations">
<section title="Embedded User-Agents" anchor="security-webviews">
<t>
Embedded user-agents are an alternative method for
authorization native apps. They are however unsafe for use by
third-parties to the authorization server by definition, as the app
that hosts the embedded user-agent can access the user's full
authentication credential, not just the OAuth authorization grant
that was intended for the app.
</t>
<t>
In typical web-view based implementations of embedded user-agents,
the host application can: log every keystroke entered in the form to
capture usernames and passwords; automatically submit forms and bypass
user-consent; copy session cookies and use them to perform
authenticated actions as the user.
</t>
<t>
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.
</t>
<t>
Encouraging users to enter credentials in an embedded user-agent
without the usual address bar and visible certificate validation
features that browsers have makes it impossible for the user to know
if they are signing in to the legitimate site, and even when they are,
it trains them that it's OK to enter credentials without validating
the site first.
</t>
<t>
Aside from the security concerns, embedded user-agents do not share
the authentication state with other apps or the browser, requiring
the user to login for every authorization request and leading to a
poor user experience.
</t>
<t>
Native apps MUST NOT use embedded user-agents to perform authorization
requests.
</t>
<t>
Authorization endpoints MAY take steps to detect and block
authorization requests in embedded user-agents.
</t>
</section>
<section title="Protecting the Authorization Code"
anchor="protecting-auth-grant">
<t>
The redirect URI options documented in
<xref target='authorization-response' /> share the benefit
that only a native app on the same device can receive the
authorization code which limits the attack surface, however code
interception by a native app other than the intended app may still be
possible.
</t>
<t>
A limitation of using custom URI schemes for redirect URIs is that
multiple apps can typically register the same scheme, which makes it
indeterminate as to which app will receive the Authorization Code.
<xref target="RFC7636">PKCE</xref> details how this limitation can
be used to execute a code interception attack (see Figure 1). Loopback
IP based redirect URIs may be susceptible to interception
by other apps listening on the same loopback interface.
</t>
<t>
As most forms of inter-app URI-based communication sends data over
insecure local channels, eavesdropping and interception of the
authorization response is a risk for native apps. App-claimed HTTPS
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.
</t>
<t>
The Proof Key for Code Exchange by OAuth Public Clients
(<xref target="RFC7636">PKCE</xref>) standard was created specifically
to mitigate against this 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 achieves this by having the client generate a
secret verifier which it passes in the initial authorization request,
and which it must present later when redeeming the authorization code
grant. An app that intercepted the authorization code would
not be in possession of this secret, rendering the code useless.
</t>
<t>
Public native app clients MUST protect the authorization request
with <xref target="RFC7636">PKCE</xref>. Authorization servers MUST
support <xref target="RFC7636">PKCE</xref> for public native app
clients. Authorization servers SHOULD reject authorization requests
from native apps that don't use PKCE by returning an error message
as defined in Section 4.4.1 of <xref
target="RFC7636">PKCE</xref>.
</t>
</section>
<section title="Loopback Redirect Considerations"
anchor="security-loopback">
<t>
Loopback interface redirect URIs use the
<spanx style="verb">http</spanx> scheme (i.e. without
TLS). This is acceptable for loopback interface redirect URIs as the
HTTP request never leaves the device.
</t>
<t>
Clients should open the loopback port only when starting the
authorization request, and close it once the response is returned.
</t>
<t>
While redirect URIs using localhost (i.e.
<spanx style="verb">http://localhost:{port}/</spanx>
function similarly to loopback IP redirects described in
<xref target="Loopback"></xref>,
the use of <spanx style="verb">localhost</spanx> is NOT RECOMMENDED.
Opening a port on the loopback interface
is more secure as only apps on the local device can connect to it.
It is also less susceptible to misconfigured routing, and interference
by client side firewalls.
</t>
</section>
<section title="Registration of Native App Clients" anchor="customuri-registration">
<t>
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.
</t>
<t>
As recommended in Section 3.1.2.2 of
<xref target="RFC6749">OAuth 2.0</xref>, the authorization server
SHOULD require the client to pre-register the complete redirection URI.
This applies and is RECOMMENDED for all redirection URIs used by
native apps.
</t>
<t>
For Custom URI scheme based redirects, authorization servers SHOULD
enforce the requirement in <xref target="namespace-considerations" />
that clients use reverse domain name based schemes.
</t>
<t>
Authorization servers MAY request the inclusion of
other platform-specific information, such as the app package or bundle
name, or other information used to associate the app that may be
useful for verifying the calling app's identity, on operating systems
that support such functions.
</t>
</section>
<section title="OAuth Implicit Flow"
anchor="implicit-flow">
<t>
The OAuth 2.0 Implicit Flow as defined in Section 4.2 of <xref
target="RFC6749">OAuth 2.0</xref> generally works with the practice of
performing the authorization request in the browser, and receiving the
authorization response via URI-based inter-app communication.
However, as the Implicit Flow cannot be protected by
PKCE (which is a recommended in <xref target="namespace-considerations" />),
the use of the Implicit Flow with native apps is NOT RECOMMENDED.
</t>
<t>
Tokens granted via the implicit flow also cannot be refreshed without
user interaction making the code flow, with refresh tokens the more
practical option for native app authorizations that require refreshing.
</t>
</section>
<section title="Phishability of In-App Browser Tabs" anchor="phishing">
<t>
While in-app browser tabs provide a secure authentication context,
as the user initiates the flow from a native app, it is possible for
that native app to completely fake an in-app browser tab.
</t>
<t>
This can't be prevented directly - once the user is in the native app,
that app is fully in control of what it can render, however there are
several mitigating factors.
</t>
<t>
Importantly, such an attack that uses a web-view to fake an in-app
browser tab will always start with no authentication state. If all
native apps use the techniques described in this best practice, users
will not need to sign-in frequently and thus should be suspicious of
any sign-in request when they should have already been signed-in.
</t>
<t>
This is the case even for authorization servers that require
occasional or frequent re-authentication, as such servers can
preserve some user identifiable information from the old session, like
the email address or profile picture and display that on the
re-authentication.
</t>
<t>
Users who are particularly concerned about their security may also
take the additional step of opening the request in the browser
from the in-app browser tab, and completing the authorization there,
as most implementations of the in-app browser tab pattern offer such
functionality.
</t>
</section>
<section title="Limitations of Non-verifiable Clients"
anchor="security-user-interaction">
<t>
As stated in Section 10.2 of <xref target="RFC6749">OAuth 2.0</xref>, the authorization server
SHOULD NOT process authorization requests automatically without user
consent or interaction, except when the identity of the client can be
assured. Measures such as claimed HTTPS redirects can be used by
native apps to prove their identity to the authorization server, and
some operating systems may offer alternative platform-specific
identity features which may be used, as appropriate.
</t>
</section>
<section title="Non-Browser External User-Agents" anchor="other-external-agents">
<t>
This best practice recommends a particular type of external user-agent,
the user's browser. Other external user-agent patterns may also be
viable for secure and usable OAuth. This document makes no comment on
those patterns.
</t>
</section>
<section title="Client Authentication" anchor="client-authentication">
<t>
Secrets that are statically included as part of an app distributed to
multiple users should not be treated as confidential secrets, as one
user may inspect their copy and learn the shared secret.
For this reason, and those stated in Section 5.3.1 of
<xref target="RFC6819" />, it is NOT RECOMMENDED for authorization
servers to require client authentication of native apps using a shared
secret, as this serves little value beyond client identification which
is already provided by the <spanx style="verb">client_id</spanx> request
parameter.
</t>
<t>
Authorization servers that still require a shared secret for native app
clients MUST treat the client as a public client, and not treat the secret as
proof of the client's identity. In those cases, it is NOT RECOMMENDED
to automatically issue tokens on the basis that the user has previously
granted access to the same client, as there is no guarantee that the
client is not counterfeit.
</t>
</section>
<section title="Cross-App Request Forgery Protections" anchor="oauth-state">
<t>
Section 5.3.5 of <xref target="RFC6819" /> recommends using the 'state'
parameter to link client requests and responses to prevent CSRF attacks.
</t>
<t>
It is similarly RECOMMENDED for native apps to include a high entropy secure random
number in the 'state' parameter of the authorization request, and
reject any incoming authorization responses without a state value
that matches a pending outgoing authorization request.
</t>
</section>
<section title="Authorization Server Mix-Up Mitigation" anchor="oauth-mixup">
<t>
To protect against a compromised or malicious authorization server
attacking another authorization server used by the same app, it is
RECOMMENDED that a unique redirect URI is used for each different
authorization server used by the app (for example, by varying the path
component), and that authorization responses are rejected if the
redirect URI they were received on doesn't match the redirect URI
in a pending outgoing authorization request.
</t>
<t>
Authorization servers SHOULD allow the registration
of a specific redirect URI, including path components, and reject
authorization requests that specify a redirect URI that doesn't exactly
match the one that was registered.
</t>
</section>
</section>
<section title="IANA Considerations" anchor="iana-considerations">
<t>
[RFC Editor: please do not remove this section.]
</t>
<t>
<xref target="custom-uri-scheme" /> specifies how private-use URI
schemes are used for inter-app communication in OAuth protocol flows.
This document requires in <xref target="namespace-considerations" />
that such schemes are based on domain names owned or assigned to the
app, as recommended in Section 3.8 of <xref target="RFC7595" />.
Per section 6 of <xref target="RFC7595" />,
registration of domain based URI schemes with IANA is not required.
Therefore, this document has no IANA actions.
</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='reference.RFC.2119'?>
<?rfc include='reference.RFC.3986'?>
<?rfc include='reference.RFC.6749'?>
<?rfc include='reference.RFC.7595'?>
<?rfc include='reference.RFC.7636'?>
</references>
<references title="Informative References">
<?rfc include='reference.RFC.6819'?>
<reference anchor="AppAuth.iOSmacOS" target="https://github.com/openid/AppAuth-iOS">
<front>
<title>AppAuth for iOS and macOS</title>
<author fullname="Steven E Wright" surname="Wright" initials="S."><organization>Google</organization></author>
<author fullname="William Denniss" surname="Denniss" initials="W."><organization>Google</organization></author>
<author>
<organization>others</organization>
</author>
<date month="February" year="2016" />
</front>
</reference>
<reference anchor="AppAuth.Android" target="https://github.com/openid/AppAuth-Android">
<front>
<title>AppAuth for Android</title>
<author fullname="Iain McGinniss" surname="McGinniss" initials="I."><organization>Google</organization></author>
<author fullname="William Denniss" surname="Denniss" initials="W."><organization>Google</organization></author>
<author>
<organization>others</organization>
</author>
<date month="February" year="2016" />
</front>
</reference>
<reference anchor="SamplesForWindows"
target="https://github.com/googlesamples/oauth-apps-for-windows">
<front>
<title>OAuth for Apps: Samples for Windows</title>
<author fullname="William Denniss" surname="Denniss" initials="W."><organization>Google</organization></author>
<date month="July" year="2016" />
</front>
</reference>
</references>
<section title="Server Support Checklist"
anchor="as-checklist">
<t>
OAuth servers that support native apps should:
</t>
<t>
<list style="numbers">
<t>
Support custom URI-scheme redirect URIs.
This is required to support mobile operating systems.
See <xref target="custom-uri-scheme"></xref>.
</t>
<t>
Support HTTPS redirect URIs for use with public native app
clients. This is used by apps on advanced mobile operating
systems that allow app-claimed HTTPS URIs.
See <xref target="App-Claimed"></xref>.
</t>
<t>
Support loopback IP redirect URIs.
This is required to support desktop operating systems.
See <xref target="Loopback"></xref>.
</t>
<t>
Not assume native app clients can keep a secret.
If secrets are distributed to multiple installs of the same
native app, they should not be treated as confidential.
See <xref target="client-authentication"></xref>.
</t>
<t>
Support PKCE. Recommended to protect authorization code
grants transmitted to public clients over inter-app
communication channels.
See <xref target="protecting-auth-grant"></xref>
</t>
</list>
</t>
</section>
<section title="Operating System Specific Implementation Details"
anchor="os">
<t>
Most of this document defines best practices in an generic manner,
referencing techniques commonly available in a variety of environments.
This non-normative section contains OS-specific implementation details
for the generic pattern, that are considered accurate at the time of
publishing, but may change over time.
</t>
<t>
It is expected that this OS-specific information will change,
but that the overall principles described in this document for using
external user-agents will remain valid.
</t>
<section title="iOS Implementation Details" anchor="os-ios">
<t>
Apps can initiate an authorization request in the browser
without the user leaving the app, through the SFSafariViewController
class which implements the browser-view pattern. Safari
can be used to handle requests on old versions of iOS without
SFSafariViewController.
</t>
<t>
To receive the authorization response, both custom URI scheme
redirects and claimed HTTPS links (known as Universal Links) are
viable choices, and function the same whether the request is loaded in
SFSafariViewController or
the Safari app. Apps can claim Custom URI schemes with the
<spanx style="verb">CFBundleURLTypes</spanx>
key in the application's property list file
<spanx style="verb">Info.plist</spanx>, and HTTPS
links using the Universal Links feature with an entitlement file
and an association file on the domain.
</t>
<t>
Universal Links are the preferred choice on iOS 9 and above due to the
ownership proof that is provided by the operating system.
</t>
<t>
A complete open source sample is included in the
<xref target="AppAuth.iOSmacOS">AppAuth for iOS and macOS</xref> library.
</t>
</section>
<section title="Android Implementation Details" anchor="os-android">
<t>
Apps can initiate an authorization request in the browser
without the user leaving the app, through the Android Custom Tab feature which
implements the browser-view pattern. The user's default browser can
be used to handle requests when no browser supports Custom Tabs.
</t>
<t>
Android browser vendors should support the Custom Tabs
protocol (by providing an implementation of the <spanx style="verb">CustomTabsService</spanx>
class), to provide the in-app browser tab user experience optimization to their users.
Chrome is one such browser that implements Custom Tabs.
</t>
<t>
To receive the authorization response, custom URI schemes
are broadly supported through Android Implicit Intends. Claimed HTTPS
redirect URIs through Android App Links are available on Android 6.0
and above. Both types of redirect URIs are registered in the application's
manifest.
</t>
<t>
A complete open source sample is included in the
<xref target="AppAuth.Android">AppAuth for Android</xref> library.
</t>
</section>
<section title="Windows Implementation Details" anchor="os-windows">
<t>
Apps can initiate an authorization request in the user's default browser
using platform APIs for this purpose.
</t>
<t>
The custom URI scheme redirect is a good choice for Universal
Windows Platform (UWP) apps as it will open the app returning the
user right back where they were. Known on UWP as URI Activation,
the scheme is limited to 39 characters, but may include the "."
character, making short reverse domain name based schemes
(as recommended in <xref target="namespace-considerations"></xref>)
possible.
</t>
<t>
The loopback redirect is the common choice for traditional desktop
apps, listening on a loopback interface port is permitted by
default Windows firewall rules.
</t>
<t>
A complete open source sample is available
<xref target="SamplesForWindows"></xref>.
</t>
</section>
<section title="macOS Implementation Details" anchor="os-macos">
<t>
Apps can initiate an authorization request in the user's default browser
using platform APIs for this purpose.
</t>
<t>
To receive the authorization response, custom URI schemes are
are a good redirect URI choice on macOS, as the user
is returned right back to the app they launched the request from.
These are registered in the application's bundle information property list
using the <spanx style="verb">CFBundleURLSchemes</spanx> key.
Loopback IP redirects are another viable option, and listening on the
loopback interface is allowed by default firewall rules.
</t>
<t>
A complete open source sample is included in the
<xref target="AppAuth.iOSmacOS">AppAuth for iOS and macOS</xref> library.
</t>
</section>
<section title="Linux Implementation Details" anchor="os-linux">
<t>
Opening the Authorization Request in the user's default browser
requires a distro-specific command,
<spanx style="verb">xdg-open</spanx> is one such tool.
</t>
<t>
The loopback redirect is the recommended redirect choice for desktop apps
on Linux to receive the authorization response.
</t>
</section>
</section>
<section title="Acknowledgements" anchor="Acknowledgements">
<t>
The author would like to acknowledge the work of
Marius Scurtescu, and Ben Wiley Sittler whose design for using
custom URI schemes in native OAuth 2.0 clients formed
the basis of <xref target="custom-uri-scheme"></xref>.
</t>
<t>
The following individuals contributed ideas, feedback, and wording
that shaped and formed the final specification:
</t>
<t>
Andy Zmolek, Steven E Wright, Brian Campbell, Paul Madsen, Nat Sakimura,
Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de Medeiros,
Adam Dawes, Naveen Agarwal, Hannes Tschofenig, Ashish Jain,
Erik Wahlstrom, Bill Fisher, Sudhi Umarji, Michael B. Jones,
Vittorio Bertocci, Dick Hardt, David Waite, and Ignacio Fiorentino.
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 08:25:38 |