OAuth Working Group                                           W. Denniss
Internet-Draft                                                    Google
Intended status: Best Current Practice                        J. Bradley
Expires: January 21, April 15, 2017                                    Ping Identity
                                                           July 20,
                                                        October 12, 2016

                       OAuth 2.0 for Native Apps
                    draft-ietf-oauth-native-apps-03
                    draft-ietf-oauth-native-apps-04

Abstract

   OAuth 2.0 authorization requests from native apps should only be made
   through external user-agents, primarily the system user's browser.  This
   specification details the security and usability reasons why this is
   the case, and how native apps and authorization servers can implement
   this best practice.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   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
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 21, April 15, 2017.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   3
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Authorization Flow for Native Apps Using App-Claimed URI
           Schemes . . . . . . . . . . . . . . . . . . . . . . . the Browser  . .   4   5
   5.  Using Inter-app URI Communication for OAuth . . . . . . . . .   6
   6.  Initiating the Authorization Request  . . . . . . . . . from a Native App  . . .   6
   7.  Receiving the Authorization Response  . . . . . . . . in a Native App  . . . .   7
     7.1.  App-declared Custom URI Scheme Redirection  . . . . . . .   7
     7.2.  App-claimed HTTPS URI Redirection . . . . . . . . . . . .   9   8
     7.3.  Loopback URI Redirection  . . . . . . . . . . . . . . . .   9   8
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  10   9
     8.1.  Embedded User-Agents  . . . . . . . . . . . . . . . . . .  10   9
     8.2.  Protecting the Authorization Code . . . . . . . . . . . .  11  10
     8.3.  Loopback Redirect Considerations  . . . . . . . . . . . .  11
     8.4.  Registration of App Redirection URIs  . . . . . . . . . .  11
     8.5.  OAuth Implicit Flow . . . . . . . . . . . . . . . . . . .  11
     8.6.  Phishability of In-App Browser Tabs . . . . . . . . . . .  12
     8.4.
     8.7.  Limitations of Non-verifiable Clients . . . . . . . . . .  12
   9.  Other
     8.8.  Non-Browser External User Agents  . . . . . . . . . . . .  12
     8.9.  Client Authentication . . . . . . . . . . .  12
   10. Client Authentication . . . . . . .  13
     8.10. Cross-App Request Forgery Protections . . . . . . . . . .  13
     8.11. Authorization Server Mix-Up Mitigation  . . . . . . . . .  13
   11.
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  14
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  13
     11.1.  14
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  13
     11.2.  14
     10.2.  Informative References . . . . . . . . . . . . . . . . .  13  14
   Appendix A.  Server Support Checklist . . . . . . . . . . . . . .  15
   Appendix B.  Operating System Specific Implementation Details . .  15
     A.1.
     B.1.  iOS Implementation Details  . . . . . . . . . . . . . . .  15
     A.2.  16
     B.2.  Android Implementation Details  . . . . . . . . . . . . .  15
     A.3.  16
     B.3.  Windows Implementation Details  . . . . . . . . . . . . .  16
     A.4.
     B.4.  macOS Implementation Details  . . . . . . . . . . . . . .  16  17
     B.5.  Linux Implementation Details  . . . . . . . . . . . . . .  17
   Appendix B. C.  Acknowledgements . . . . . . . . . . . . . . . . . .  17
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  17  18

1.  Introduction

   The OAuth 2.0 [RFC6749] authorization framework, framework documents two
   approaches in Section 9 for native apps to interact with the
   authorization endpoint: via an embedded user-agent, or an external
   user-agent. user-
   agent.

   This document best current practice recommends that only external user-agents
   like in-app browser
   tabs as the only secure and usable choice browser are used for OAuth. OAuth by native apps.  It documents how
   native apps can implement authorization flows with such agents, using the browser as
   the preferred external user-agent, and the additional requirements of for
   authorization servers needed to support such usage.

   This practice is also known as the AppAuth pattern, in reference to
   open source libraries that implement it.

2.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in Key
   words for use in RFCs to Indicate Requirement Levels [RFC2119].  If
   these words are used without being spelled in uppercase then they are
   to be interpreted with their normal natural language meanings.

3.  Terminology

   In addition to the terms defined in referenced specifications, this
   document uses the following terms:

   "app"  A native application, such

   "native app"  An application that is installed by the user to their
      device, as one on distinct from a mobile device or
      desktop operating system. 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.

   "OAuth"  In this document, OAuth refers to OAuth 2.0 [RFC6749].

   "app"  Shorthand for "native app".

   "app store"  An ecommerce store where users can download and purchase
      apps.  Typically with quality-control measures to protect users
      from malicious developers.

   "authz"  Abbreviation of "authorization".

   "system browser"

   "browser"  The operating system's default browser, typically pre-installed as
      part of the operating system, or installed and set as default by
      the user.

   "browser tab"  An open page of the system browser.  Browser typically have
      multiple "tabs" representing various open pages.

   "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 system browser.

      Has different platform-specific product names, such as
      SFSafariViewController on iOS 9, iOS, and Chrome Custom Tab on Android.

   "Claimed

   "inter-app communication"  Communication between two apps on a
      device.

   "claimed HTTPS URL"  Some platforms allow apps to claim a domain name
      by hosting a file that proves HTTPS URL
      after proving ownership of the link between site and app.
      Typically this means that domain name.  URLs opened by the system will be claimed in such
      a way are then opened in the app instead of the browser.

   "web-view"  A web browser UI component that can be embedded in apps
      to render web pages, used to create embedded user-agents.

   "reverse domain name notation"  A naming convention based on the
      domain name system, but where where the domain components are
      reversed, for example "app.example.com" becomes "com.example.app".

   "custom URI scheme"  A URI scheme (as defined by [RFC3986]) that the
      app creates and registers with the OS (and is not a standard URI
      scheme like "https:" or "tel:").  Requests to such a scheme
      results in the app which registered it being launched by the OS.
      For example, "myapp:", "com.example.myapp:" are both custom URI
      schemes.

   "inter-app communication"  Communication between two

   "web-view"  A web browser UI component that can be embedded in apps on a
      device.

   "OAuth"  In this document, OAuth refers
      to OAuth 2.0 [RFC6749]. render web pages, used to create embedded user-agents.

   "reverse domain name notation"  A naming convention based on the
      domain name system, but where where the domain components are
      reversed, for example "app.example.com" becomes "com.example.app".

4.  Overview

   At the time of writing, many

   The best current practice for authorizing users in native apps are still using web-views, is to
   perform the OAuth authorization request in a
   type of browser (an external
   user-agent), rather than web-view (an embedded user-agent, user-agent).

   Previously it was common for OAuth. native apps to use web-views for OAuth
   authorization requests.  That approach has multiple many drawbacks, typically
   including the client host app being able to eavesdrop copy user
   credentials, credentials and is a suboptimal user experience as the
   authentication session can't be shared,
   cookies, and users need to sign-in the user needing to authenticate from scratch in each app separately.

   OAuth flows between
   app.  See Section 8.1 for a native deeper analysis of using embedded user-
   agents for OAuth.

   Native app and authorization requests that use the system browser (or another
   external user-agent) are more secure,
   secure and can take advantage of the
   shared user's authentication state state.
   Being able to enable use the existing authentication session in the browser
   enables single sign-on.

   Inter-process communication, such sign-on, as OAuth users don't need to authenticate to the
   authorization server each time they use a new app (unless required by
   authorization server policy).

   Supporting authorization flows between a native app and the system browser can be achieved through URI-based
   communication.  As this
   is exactly how OAuth works for web-based possible without changing the OAuth flows between RP protocol itself, as the
   authorization request and IDP websites, OAuth 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 auth with very little modification. OAuth clients and the types of redirect
   URIs they use to support this best practice.

4.1.  Authorization Flow for Native Apps Using App-Claimed URI Schemes the Browser

  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
  |          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    |               |
  |                                |                   +---------------+
  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

        Figure 1: Native App Authorization via External User-agent

   Figure 1 illustrates the interaction of the native app with the
   system browser to authorize the user via an external user-agent.

   1) The client app opens a browser tab with the authorization request.

   2) Authorization endpoint receives the authorization request, and
      processes it, typically by authenticating
      authenticates the end-user user and
      obtaining an authorization decision.  How the authorization server
      authenticates obtains authorization.  Authenticating
      the end-user is out of scope for this specification,
      but can potentially user may involve chaining to other authentication
      systems using various authentication protocols. systems.

   3) Authorization server issues an authorization code to the redirect
      URI.

   4) Client receives the authorization code from the redirect URI.

   5) Client app presents the authorization code at the Token token endpoint.

   6) Token endpoint validates the authorization code and issues the
      tokens requested.

5.  Using Inter-app URI Communication for OAuth

   Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate
   the authorization request and return the authorization response to
   the requesting website, URIs can be used by native apps to initiate
   the authorization request in the device's system browser and return the
   response to the requesting native app.

   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 by 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.

   It is RECOMMENDED that native

   Native apps MUST use the URI-based communication
   functionality of the operating system an external user-agent to perform OAuth flows
   authentication requests.  This is achieved by opening the
   authorization request in an
   external user-agent, typically the system browser.

   Some platforms support a browser feature known as in-app browser
   tabs, where an app can present (detailed in Section 6), and
   using a tab of redirect URI that will return the browser within authorization response back
   to the app
   context without switching apps, but still retain key benefits of native app, as defined in Section 7.

   This best practice focuses on 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.

   It is possible to create an RECOMMENDED external
   user-agent for OAuth that is native apps.  Other external user-agents, such as a
   native app provided by the authorization server, as opposed to server may meet the
   system browser.  This approach shares a lot of similarity with criteria
   set out in this best practice, including using the system browser as both same redirection
   URI properties, but their use URIs for inter-app communication and
   is able to provide a secure, shared authentication session, and thus
   MAY be used for secure native OAuth, applying most of the techniques
   described here.  However it is NOT RECOMMENDED due to the increased
   complexity and requirement for the user to have the AS app installed.
   While much of the advice and security considerations are applicable
   to such clients, they are out of scope for this specification.
   options for inter-app communication, offering similar security

6.  Initiating the Authorization Request from a Native App

   The authorization request is created as per OAuth 2.0 [RFC6749], and
   opened in the system browser.  Where the operating system supports
   in-app user's browser tabs, those should be preferred over switching to the
   system browser, to improve usability. using platform-specific APIs for that
   purpose.

   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 code response to the OAuth
   client's server, it the redirect URI used by a native app returns it the
   response to the native app.  The various options for a redirect URI that
   will return the code to the native app are documented in Section 7.
   Any redirect URI that allows the app to receive the URI and inspect
   its parameters is viable.

7.  Receiving

   Some platforms support a browser feature known as in-app browser
   tabs, where an app can present a tab of the Authorization Response

   There are three main approaches to redirection URIs 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 native apps:
   custom URI schemes, app-claimed HTTPS
   usability reasons that apps use in-app browser tabs for the
   Authorization Request.

7.  Receiving the Authorization Response in a Native App

   There are several redirect URI schemes, options available to native apps for
   receiving the authorization response from the browser, the
   availability and loopback
   redirects. user experience of which varies by platform.

   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.

7.1.  App-declared Custom URI Scheme Redirection

   Most major

   Many mobile and desktop computing platforms support inter-app
   communication via URIs by allowing apps to register custom URI
   schemes.
   schemes, like "com.example.app:".  When the system browser or another app
   attempts to follow load a URI with a custom scheme, the app that registered
   it is launched to handle the request.  This document is only relevant on platforms that
   support this pattern.

   In particular, the custom URI scheme pattern is supported on Android
   [Android.URIScheme], iOS [iOS.URIScheme], Windows Universal Platform
   (UWP) [WindowsUWP.URIScheme] and macOS [macOS.URIScheme].

7.1.1.  Using Custom URI Schemes for Redirection

   To perform an OAuth 2.0 Authorization Request on a supported
   platform, the native app launches the system browser with a normal OAuth 2.0
   Authorization Request, but provides a redirection URI that utilizes a
   custom URI scheme that is registered with the operating system by the calling
   app.

   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 extracts
   the code from the query parameters from the URI just like a web
   client would, and exchanges then
   processes the Authorization Code authorization response like a regular any OAuth 2.0 client.

7.1.2.

7.1.1.  Custom URI Scheme Namespace Considerations

   When selecting which choosing a URI scheme to associate with the app, apps
   SHOULD pick MUST use a
   URI scheme that is globally unique, and which they can
   assert ownership over.

   To avoid clashing with existing schemes in use, using based on a scheme that
   follows the reverse domain name pattern applied to a domain under the their control, expressed in
   reverse order, as recommended by Section 3.8 of [RFC7595] for
   private-use URI schemes.

   For example, an app publishers control is RECOMMENDED.  Such a scheme that controls the domain name "app.example.com"
   can be use "com.example.app:/" as their custom scheme.  Some
   authorization servers assign client identifiers based on
   a domain they control, or the OAuth client identifier in cases where
   the authorization server issues client identifiers that are also
   valid DNS subdomains.  The chosen scheme MUST NOT clash with any IANA
   registered scheme [IANA.URISchemes].  You SHOULD
   names, for example "client1234.usercontent.example.net", which can
   also ensure that no
   other app by the same publisher uses be used as the same scheme.

   Schemes using reverse domain name notation are hardened against
   collision.  They are unlikely to clash with an officially registered
   scheme [IANA.URISchemes] or unregistered de-facto for the custom scheme, as these
   generally don't include when reversed
   in the same manner, for example "net.example.usercontent.client1234".

   URI schemes not based on a period character, and are unlikely to match
   your domain name in any case.  They (for example "myapp:/") MUST
   NOT be used, as they are guaranteed not to clash collision resistant, and don't comply
   with
   any OAuth client following these naming guidelines in full.

   Some Section 3.8 of [RFC7595].

   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 globally unique bundle or package names app identifiers that
   follow the are also based on reverse order domain name notation pattern.  In these cases, the
   app SHOULD register that bundle id
   names, those can be re-used as the custom scheme.  If an app
   has a bundle id or package name that doesn't match URI scheme for the OAuth
   redirect.

   In addition to the collision resistant properties, basing the URI
   scheme off a domain name that is under the control of the app, the app SHOULD NOT register that as a
   scheme, and instead create can
   help to prove ownership in the event of a URI dispute where two apps
   claim the same custom scheme based off one of their domain
   names.

   For example, (such as if an app whose publisher owns is acting
   maliciously).  For example, if two apps claimed "com.example.app:",
   the top level domain name owner of "example.com" can register "com.example.app:/" as their custom
   scheme.  An app whose authorization server issues client identifiers
   that are also valid domain names, for example
   "client1234.usercontent.idp.com", can use the reverse domain name
   notation of that domain as the scheme, i.e.
   "com.idp.usercontent.client1234:/".  Each of these examples are URI
   schemes which are likely to be unique, and where the publisher can
   assert ownership.

   As a counter-example, using a simple custom scheme like "myapp:/" is
   not guaranteed to be unique and is NOT RECOMMENDED.

   In addition to uniqueness, basing the URI scheme off a name that is
   under the control of the app's publisher can help to prove ownership
   in the event of a dispute where two apps register the same custom
   scheme (such as if an app is acting maliciously).  For example, if
   two apps registered "com.example.app:", the true owner of
   "example.com" could petition the could petition the app store operator to
   remove the counterfeit app.  This petition is harder to prove if a
   generic URI scheme was chosen.

7.1.3.  Registration of App Redirection URIs

   As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the
   authorization server SHOULD require the client to pre-register the
   redirection URI.  This remains true for app redirection URIs that use
   custom schemes.

   Additionally, 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.

   Authorizations servers SHOULD support the ability for native apps to
   register Redirection URIs that utilize custom URI schemes.
   Authorization servers SHOULD enforce the recommendation in
   Section 7.1.2 that apps follow naming guidelines for URI schemes. used.

7.2.  App-claimed HTTPS URI Redirection

   Some operating systems allow apps to claim HTTPS URLs of in their
   domains.  When the browser sees such encounters a claimed URL, instead of the
   page being loaded in the browser, the native app is launched instead
   with the URL given supplied as input.

   Where the operating environment provided app-claimed

   App-claimed HTTPS redirect URIs have some advantages in a
   usable fashion, these URIs should be used as the OAuth redirect, as
   they allow that the
   identity of the destination app to be is guaranteed by the operating
   system.

   Apps on platforms that allow the user  Due to disable this functionality,
   present it in a user-unfriendly way, or lack it altogether MUST
   fallback to using custom URI schemes.

   The authorization server MUST allow reason, they SHOULD be used over the registration of other
   redirect choices for native apps where possible.

   App-claimed HTTPS redirect URIs for non-confidential function exactly 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 to support app-
   claimed that use app-claimed HTTPS redirect URIs.
   URIs and confidential web clients.  A flag in the client registration
   information that indicates a public native app client is one such
   method for distinguishing client types.

7.3.  Loopback URI Redirection

   More applicable to desktop

   Desktop operating systems, some environments systems allow native apps to create listen on a local port
   for HTTP listener on a random port, and receive
   URI redirects that way. redirects.  This is an acceptable redirect URI choice
   for can be used by native apps to receive OAuth
   authorization responses on compatible platforms.

   Authorization servers SHOULD support

   Loopback redirect URIs on take the loopback IP
   address and HTTP scheme, that is, redirect URIs beginning with
   http://127.0.0.1[:port]/, http://::1[:port]/, and
   http://localhost[:port]/. Authorization servers supporting this class form of redirect URI MUST allow the client to specify a loopback IP, any port of their
   choice, and SHOULD allow
   (dynamically provided by the client to use an arbitrary client), and a path component.

   While both the
   Specifically: "http://127.0.0.1:{port}/{path}", and
   "http://[::1]:{port}/{path}".

   For loopback IP and localhost variants SHOULD be supported
   by redirect URIs, the authorization server for completeness, it is RECOMMENDED that
   apps primarily use MUST allow
   any port to be specified at the loopback IP variant, as it is less susceptible time of the request, to misconfigured routing and client side firewalls Note accommodate
   clients that obtain an available port from the HTTP
   scheme is acceptable for this category operating system at
   the time of redirect URIs, as the
   request never leaves request.  Other than that, the device. redirect is be treated
   like any other.

8.  Security Considerations

8.1.  Embedded User-Agents

   Embedded user-agents, commonly implemented with web-views, are an
   alternative method for authorizing native apps.  They are however
   unsafe for use by third-parties by definition.  They involve the user
   signing in with their full login credentials, only to have them
   downscoped to less powerful OAuth credentials.

   Even when used by trusted first-party apps, embedded user-agents
   violate the principle of least privilege by obtaining more powerful
   credentials than they need, potentially increasing the attack
   surface.

   In typical web-view based implementations of embedded user-agents,
   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.

   Encouraging users to enter credentials in an embedded web-view
   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.

   Aside from the security concerns, web-views do not share the
   authentication state with other apps or the system browser, requiring the
   user to login for every authorization request and leading to a poor
   user experience.

   Due to the above,

   Native apps MUST NOT use of embedded user-agents is NOT RECOMMENDED,
   except where a trusted first-party app acts as the external user-
   agent for other apps, or provides single sign-on for multiple first-
   party apps. OAuth to third-
   parties.

   Authorization servers SHOULD consider taking MAY take steps to detect and block logins via
   authorization requests in third-party embedded user-agents that are not their own, where
   possible. user-agents.

8.2.  Protecting the Authorization Code

   The redirect URI options documented in Section 7 share the benefit
   that only a native app on the same device can receive the
   authorization code, however code interception by a native app other
   than the intended recipient may be possible.

   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
   Grant.  This is not an issue for HTTPS redirection URIs (i.e.
   standard web URLs) due to the fact the HTTPS URI scheme is enforced
   by the authority (as defined by [RFC3986]), the domain name system,
   which does not allow multiple entities to own the same domain.

   If multiple apps register the same scheme, it is possible that the
   authorization code will be sent to the wrong app (generally the
   operating system makes no guarantee of which app will handle the URI
   when multiple register the same scheme).  PKCE [RFC7636] details how
   this limitation can be used to execute a code interception attack
   (see Figure 1).  This attack vector applies to public clients
   (clients that are unable to maintain a client secret) which is
   typical of most native apps.

   While Section 7.1.2 7.1.1 details ways that this can be mitigated through
   policy enforcement (through being able to report and have removed any
   offending apps), we can also protect the authorization code grant
   from being used in cases where it was intercepted.

   The Proof Key for Code Exchange by OAuth Public Clients (PKCE
   [RFC7636]) 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.

   Both the client and the Authorization Server MUST support PKCE
   [RFC7636] to use custom URI schemes, or loopback IP redirects.
   Authorization Servers SHOULD reject authorization requests using a
   custom scheme, or loopback IP as part of the redirection URI if the
   required PKCE parameters are not present, returning the error message
   as defined in Section 4.4.1 of PKCE [RFC7636].  It is RECOMMENDED to
   use PKCE [RFC7636] for app-claimed HTTPS redirect URIs, even though
   these are not generally subject to interception, to protect against
   attacks on inter-app communication.

8.3.  Phishability of In-App Browser Tabs

   While in-app browser tabs provide a secure authentication context,  Loopback Redirect Considerations

   Loopback interface redirect URIs use the "http" scheme (i.e. without
   TLS).  This is acceptable for loopback interface redirect URIs as the user initiates
   HTTP request never leaves the flow from a native app, device.

   Clients should open the loopback port only when starting the
   authorization request, and close it is possible for
   that native app to completely fake an in-app browser tab.

   This can't be prevented directly - once the user response is returned.

   While redirect URIs using localhost (i.e.  "http://localhost:{port}/"
   function similarly to loopback IP redirects described in Section 7.3,
   the native
   app, that app is fully in control use of what it can render, however
   there are several mitigating factors.

   Importantly, such an attack that uses "localhost" is NOT RECOMMENDED.  Opening a web-view to fake an in-app
   browser tab will always start with no authentication state.  If all
   native port on the
   loopback interface is more secure as only apps use on the techniques described in this best practice, users
   will not need local device
   can connect to sign-in frequently it.  It is also less susceptible to misconfigured
   routing, and thus should be suspicious interference by client side firewalls.

8.4.  Registration of
   any sign-in request when they should have already been signed-in. App Redirection URIs

   As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the
   authorization server SHOULD require the client to pre-register the
   complete redirection URI.  This applies and is true even RECOMMENDED for all
   redirection URIs used by native apps.

   For Custom URI scheme based redirects, authorization servers SHOULD
   enforce the requirement in Section 7.1.1 that require frequent or
   occasional re-authentication, as such clients use reverse
   domain name based schemes.

   Authorization servers can preserve some user
   identifiable information from MAY request the old request, like inclusion of other platform-
   specific information, such as the email address app package or avatar.  To help mitigate against phishing, it is RECOMMENDED bundle name, or
   other information used to
   show associate the user some hint that they were previously logged in, as an
   attacking app would not that may be capable useful for
   verifying the calling app's identity, on operating systems that
   support such functions.

8.5.  OAuth Implicit Flow

   The OAuth 2.0 Implicit Flow as defined in Section 4.2 of doing this.

   Users who are particularly concerned about their security may also
   take OAuth 2.0
   [RFC6749] generally works with the additional step practice of opening performing the
   authorization request in the system browser
   from the in-app browser tab, browser, and completing receiving the authorization there,
   response via URI-based inter-app communication.  However, as most implementations of the in-app browser tab pattern offer such
   functionality.  This is not expected to
   Implicit Flow cannot be common user behavior,
   however.

8.4.  Limitations of Non-verifiable Clients

   As stated protected by PKCE (which is a recommended in
   Section 10.2 7.1.1), the use of RFC 6749, the authorization server
   SHOULD Implicit Flow with native apps is NOT process authorization requests automatically
   RECOMMENDED.

   Tokens granted via the implicit flow also cannot be refreshed without
   user
   consent or interaction, except when interaction making the identity of code flow, with refresh tokens the client can be
   assured.  Measures such as claimed HTTPS redirects can be used by more
   practical option for native app authorizations that require
   refreshing.

8.6.  Phishability of In-App Browser Tabs

   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.

   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.

   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.

   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.

   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.

8.7.  Limitations of Non-verifiable Clients

   As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization
   server SHOULD NOT process authorization requests automatically
   without user consent or interaction, except when the identity of the
   client can be assured.  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 platform-
   specific identity features which may be used, as appropriate.

9.  Other

8.8.  Non-Browser External User Agents

   This best practice recommends a particular type of external user-
   agent, the system user's browser.  Other external user-agents patterns may
   also be viable for secure and usable OAuth.  This document makes no
   comment on those patterns.

10.  Client Authentication

   Secrets makes no
   comment on those patterns.

8.9.  Client Authentication

   Secrets that are statically included as part of an app distributed to
   multiple users should not be treated as confidential secrets, as one
   user may inspect their copy and learn the shared secret.  For this
   reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT
   RECOMMENDED for authorization servers to require client
   authentication of native apps using a shared secret, as this serves
   little value beyond client identification which is already provided
   by the "client_id" request parameter.

   Authorization servers that still require a 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.

8.10.  Cross-App Request Forgery Protections

   Section 5.3.5 of [RFC6819] recommends using the 'state' parameter to
   link client requests and responses to prevent CSRF attacks.

   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.

8.11.  Authorization Server Mix-Up Mitigation

   To protect against a compromised or malicious authorization server
   attacking another authorization server used by the same app, it is
   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.

   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.

9.  IANA Considerations

   [RFC Editor: please do not remove this section.]

   Section 7.1 specifies how private-use URI schemes are used for inter-
   app communication in OAuth protocol flows.  This document requires in
   Section 7.1.1 that such schemes are statically included as part of an app distributed based on domain names owned or
   assigned to
   multiple users should not be treated as confidential secrets, as one
   user may inspect their copy and learn the secret app, as recommended in Section 3.8 of all users.  For
   this reason it is NOT RECOMMENDED for authorization servers to
   require client authentication [RFC7595].  Per
   section 6 of native apps using a secret shared by
   multiple installs [RFC7595], registration of the app, as this serves little value beyond
   client identification which is already provided by the client_id
   request parameter.  If an authorization server requires a client
   secret for native apps, it MUST NOT assume that it is actually
   secret, unless some method domain based URI schemes with
   IANA is being used to dynamically provision a
   unique secret to each installation.

11. not required.  Therefore, this document has no IANA actions.

10.  References

11.1.

10.1.  Normative References

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <http://www.rfc-editor.org/info/rfc6749>.

   [RFC7636]  Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
              for Code Exchange by OAuth Public Clients", RFC 7636,
              DOI 10.17487/RFC7636, September 2015,
              <http://www.rfc-editor.org/info/rfc7636>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <http://www.rfc-editor.org/info/rfc3986>.

11.2.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <http://www.rfc-editor.org/info/rfc6749>.

   [RFC7595]  Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
              and Registration Procedures for URI Schemes", BCP 35,
              RFC 7595, DOI 10.17487/RFC7595, June 2015,
              <http://www.rfc-editor.org/info/rfc7595>.

   [RFC7636]  Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
              for Code Exchange by OAuth Public Clients", RFC 7636,
              DOI 10.17487/RFC7636, September 2015,
              <http://www.rfc-editor.org/info/rfc7636>.

10.2.  Informative References

   [RFC6819]  Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
              Threat Model and Security Considerations", RFC 6819,
              DOI 10.17487/RFC6819, January 2013,
              <http://www.rfc-editor.org/info/rfc6819>.

   [iOS.URIScheme]
              "Inter-App Communication", July 2016, <https://developer.a
              pple.com/library/ios/documentation/iPhone/Conceptual/
              iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-
              AppCommunication.html>.

   [macOS.URIScheme]
              "Launch Services Concepts", July 2016, <https://developer.
              apple.com/library/mac/documentation/Carbon/Conceptual/Laun
              chServicesConcepts/LSCConcepts/LSCConcepts.html#//apple_re
              f/doc/uid/TP30000999-CH202-CIHFEEAD>.

   [Android.URIScheme]
              "Intents and Intent Filters", July 2016,
              <http://developer.android.com/guide/components/
              intents-filters.html#ires>.

   [WindowsUWP.URIScheme]
              "Handle URI activation", July 2016,
              <https://msdn.microsoft.com/en-us/windows/uwp/launch-
              resume/handle-uri-activation>.

   [IANA.URISchemes]
              "Uniform Resource Identifier (URI) Schemes", July 2016,
              <http://www.iana.org/assignments/uri-schemes/
              uri-schemes.xhtml>.

   [ChromeCustomTab]
              "Chrome Custom Tabs", July 2016,
              <https://developer.chrome.com/multidevice/android/
              customtabs>.

   [SFSafariViewController]
              "SafariServices Changes", July

   [AppAuth.iOSmacOS]
              Wright, S., Denniss, W., and others, "AppAuth for iOS and
              macOS", February 2016,
              <https://developer.apple.com/library/ios/documentation/
              SafariServices/Reference/SFSafariViewController_Ref/>.

   [Android.AppLinks]
              "App Links", July 2015,
              <https://developer.android.com/preview/features/app-
              linking.html>.

   [CustomTabsService]
              "CustomTabsService", July <https://github.com/openid/AppAuth-
              iOS>.

   [AppAuth.Android]
              McGinniss, I., Denniss, W., and others, "AppAuth for
              Android", February 2016,
              <https://developer.android.com/reference/android/support/
              customtabs/CustomTabsService.html>.

   [UniversalLinks]
              "Universal Links", <https://github.com/openid/
              AppAuth-Android>.

   [SamplesForWindows]
              Denniss, W., "OAuth for Apps: Samples for Windows", July
              2016, <https://developer.apple.com
              /library/ios/documentation/General/Conceptual/AppSearch/
              UniversalLinks.html>. <https://github.com/googlesamples/oauth-apps-for-
              windows>.

Appendix A.  Server Support Checklist

   OAuth servers that support native apps should:

   1.  Support custom URI-scheme redirect URIs.  This is required to
       support mobile operating systems.  See Section 7.1.

   2.  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 Section 7.2.

   3.  Support loopback IP redirect URIs.  This is required to support
       desktop operating systems.  See Section 7.3.

   4.  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 Section 8.9.

   5.  Support PKCE.  Recommended to protect authorization code grants
       transmitted to public clients over inter-app communication
       channels.  See Section 8.2

Appendix B.  Operating System Specific Implementation Details

   Most of this document attempts to lay out defines best practices in an generic manner,
   referencing technology techniques commonly available on most operating
   systems. 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 authorship. publishing, but may change over time.

   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.

A.1.

B.1.  iOS Implementation Details

   Claimed HTTPS and

   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.

   To receive the authorization response, both custom URI scheme
   redirects and claimed HTTPS links (known as Universal Links) are both
   viable choices
   for OAuth on iOS.  Developers choices, and function the same whether the request is loaded
   in SFSafariViewController or the Safari app.  Apps can claim Custom
   URI schemes with the "CFBundleURLTypes" key in the application's
   property list file "Info.plist", and HTTPS links using the Universal
   Links [UniversalLinks], available since iOS 9, feature with an entitlement file and can use custom URI
   scheme [iOS.URIScheme] redirects for backwards compatibility.
   Clients SHOULD use an association file on the
   domain.

   Universal Links for authorization requests on iOS
   9 and beyond, with are the custom URI scheme redirect substituted preferred choice on
   older versions.  In both cases, iOS 9 and above due to
   the app claims ownership proof that is provided by the redirect operating system.

   A complete open source sample is included in the
   application manifest.

   As a user experience optimisation, since AppAuth for iOS 9, apps and
   macOS [AppAuth.iOSmacOS] library.

B.2.  Android Implementation Details

   Apps can invoke initiate an authorization request in the
   system browser without the
   user leaving the app app, through
   SFSafariViewController [SFSafariViewController], the Android Custom Tab feature which
   implements the browser-view pattern.  This class has all the properties of  The user's default browser can
   be used to handle requests when no browser supports Custom Tabs.

   Android browser vendors should support the
   system browser, and is Custom Tabs protocol (by
   providing an 'external user-agent', even though it is
   presented within the host app.  Regardless implementation of whether the user
   completes the request in "CustomTabsService" class), to
   provide the system in-app browser (as is tab user experience optimization to their choice), or
   the SFSafariViewController, the return of the token via custom URI
   scheme or claimed HTTPS link
   users.  Chrome is one such browser that implements Custom Tabs.

   To receive the same.

A.2.  Android Implementation Details

   Claimed HTTPS and authorization response, custom URI scheme redirects schemes are both viable choices
   for OAuth on Android.  Developers can claim broadly
   supported through Android Implicit Intends.  Claimed HTTPS links using redirect
   URIs through Android App Links [Android.AppLinks], are available since on Android 6.0 though browser
   support varies, and custom URI scheme [Android.URIScheme] redirects
   are broadly supported.  Clients SHOULD support custom URI scheme
   redirects for broad compatibility and MAY upgrade to using claimed
   HTTPs redirects in supported environments.  For both redirect
   options, the app claims the
   above.  Both types of redirect URIs are registered in the application
   application's manifest.

   As a user experience optimisation, apps SHOULD try to launch the
   authorization request in a Custom Tab. Custom Tab is an
   implementation of the browser-view pattern, providing a secure
   browser tab displayed in the context of the app.  Chrome

   A complete open source sample is an
   example of a browser that supports [ChromeCustomTab] CustomTabs.

   Android Browser vendors SHOULD implement the CustomTabsService
   [CustomTabsService] to provide this functionality to their users.

A.3. included in the AppAuth for Android
   [AppAuth.Android] library.

B.3.  Windows Implementation Details

   Apps written on the Universal Windows Platform (UWP) can claim initiate an authorization request in the user's default
   browser using platform APIs for this purpose.

   The custom URI schemes [WindowsUWP.URIScheme] in their application manifest.
   This scheme redirect is a good choice for Universal Windows
   Platform (UWP) apps as it will also open the app when returning the user taps right
   back where they were.  Known on UWP as URI Activation, the
   link.  The scheme is
   limited to 39 characters, and but may include the
   `.` character.

   UWP apps can launch the authorization request "." character, making
   short reverse domain name based schemes (as recommended in the user's default
   browser like so:

    Uri authorizationRequest = ...
    var success = Windows.System.Launcher.LaunchUriAsync(authorizationRequest)
   Section 7.1.1) possible.

   The loopback IP redirect is a the common choice for traditional Desktop desktop
   apps, and listening on a loopback interface port is permitted by default
   Windows firewall rules.

   Traditional apps

   A complete open source sample is available [SamplesForWindows].

B.4.  macOS Implementation Details

   Apps can launch the URI initiate an authorization request in the user's default
   browser
   like so:

       string authorizationRequest = ...
       System.Diagnostics.Process.Start(authorizationRequest);

   When using platform APIs for this purpose.

   To receive the "Process.Start" method, care must be taken that the
   input is authorization response, custom URI schemes are are a valid URL, including correct
   good redirect URI encoding of choice on macOS, as the
   parameters.  This user is especially important when returned right back
   to the URL includes user-
   supplied app they launched the request from.  These are registered in
   the application's bundle information such as a login hint.

A.4.  macOS Implementation Details

   Both property list using the loopback
   "CFBundleURLSchemes" key.  Loopback IP and custom URI scheme redirect choices redirects are another viable
   option, and listening on macOS.  Custom URI schemes [macOS.URIScheme] are registered the loopback interface is allowed by default
   firewall rules.

   A complete open source sample is included in the application manifest.  Listening on AppAuth for iOS and
   macOS [AppAuth.iOSmacOS] library.

B.5.  Linux Implementation Details

   Opening the Authorization Request in the user's default browser
   requires a distro-specific command, "xdg-open" is one such tool.

   The loopback IP typically
   does not require any firewall changes.

   Apps can launch redirect is the recommended redirect choice for desktop
   apps on Linux to receive the authorization request like so:

    NSURL *authorizationRequest = ...
    BOOL success = [[NSWorkspace sharedWorkspace] openURL:authorizationRequest]; response.

Appendix B. C.  Acknowledgements

   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 Section 7.1.

   The following individuals contributed ideas, feedback, and wording
   that shaped and formed the final specification:

   Naveen Agarwal,

   Andy Zmolek, Steven E Wright, Brian Campbell, Adam Dawes, Hannes Tschofenig, Ashish
   Jain, Paul Madsen, Nat
   Sakimura, Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de
   Medeiros, Eric Sachs, Nat Sakimura, Steve
   Wright, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Andy Zmolek, Bill
   Fisher, Sudhi Umarji. Umarji, Michael B.  Jones, Vittorio Bertocci, Paul
   Grassi, David Waite, Naveen Agarwal, and Adam Dawes.

Authors' Addresses

   William Denniss
   Google
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043
   USA

   Phone: +1 650-253-0000

   Email: wdenniss@google.com
   URI:   http://google.com/   http://wdenniss.com/appauth

   John Bradley
   Ping Identity

   Phone: +1 202-630-5272
   Email: ve7jtb@ve7jtb.com
   URI:   http://www.thread-safe.com/   http://www.thread-safe.com/p/appauth.html