draft-ietf-oauth-native-apps-08.txt   draft-ietf-oauth-native-apps-09.txt 
OAuth Working Group W. Denniss OAuth Working Group W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Best Current Practice J. Bradley Intended status: Best Current Practice J. Bradley
Expires: September 3, 2017 Ping Identity Expires: September 7, 2017 Ping Identity
March 2, 2017 March 6, 2017
OAuth 2.0 for Native Apps OAuth 2.0 for Native Apps
draft-ietf-oauth-native-apps-08 draft-ietf-oauth-native-apps-09
Abstract Abstract
OAuth 2.0 authorization requests from native apps should only be made OAuth 2.0 authorization requests from native apps should only be made
through external user-agents, primarily the user's browser. This through external user-agents, primarily the user's browser. This
specification details the security and usability reasons why this is specification details the security and usability reasons why this is
the case, and how native apps and authorization servers can implement the case, and how native apps and authorization servers can implement
this best practice. this best practice.
Status of This Memo Status of This Memo
skipping to change at page 1, line 35 skipping to change at page 1, line 35
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 3, 2017. This Internet-Draft will expire on September 7, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 27
7.1. App-declared Custom URI Scheme Redirection . . . . . . . 7 7.1. App-declared Custom URI Scheme Redirection . . . . . . . 7
7.2. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 8 7.2. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 8
7.3. Loopback URI Redirection . . . . . . . . . . . . . . . . 9 7.3. Loopback URI Redirection . . . . . . . . . . . . . . . . 9
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 9 8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 9
8.2. Non-Browser External User-Agents . . . . . . . . . . . . 10 8.2. Non-Browser External User-Agents . . . . . . . . . . . . 10
8.3. Phishability of In-App Browser Tabs . . . . . . . . . . . 10 8.3. Phishability of In-App Browser Tabs . . . . . . . . . . . 10
8.4. Protecting the Authorization Code . . . . . . . . . . . . 11 8.4. Protecting the Authorization Code . . . . . . . . . . . . 11
8.5. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 12 8.5. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 12
8.6. Loopback Redirect Considerations . . . . . . . . . . . . 12 8.6. Loopback Redirect Considerations . . . . . . . . . . . . 12
8.7. Registration of Native App Clients . . . . . . . . . . . 13 8.7. Registration of Native App Clients . . . . . . . . . . . 12
8.8. Client Authentication . . . . . . . . . . . . . . . . . . 13 8.8. Client Authentication . . . . . . . . . . . . . . . . . . 13
8.9. Client Impersonation . . . . . . . . . . . . . . . . . . 14 8.9. Client Impersonation . . . . . . . . . . . . . . . . . . 13
8.10. Cross-App Request Forgery Protections . . . . . . . . . . 14 8.10. Cross-App Request Forgery Protections . . . . . . . . . . 14
8.11. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 8.11. Authorization Server Mix-Up Mitigation . . . . . . . . . 14
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16
Appendix B. Operating System Specific Implementation Details . . 16 Appendix B. Operating System Specific Implementation Details . . 16
B.1. iOS Implementation Details . . . . . . . . . . . . . . . 17 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 17
B.2. Android Implementation Details . . . . . . . . . . . . . 17 B.2. Android Implementation Details . . . . . . . . . . . . . 17
B.3. Windows Implementation Details . . . . . . . . . . . . . 18 B.3. Windows Implementation Details . . . . . . . . . . . . . 18
B.4. macOS Implementation Details . . . . . . . . . . . . . . 18 B.4. macOS Implementation Details . . . . . . . . . . . . . . 18
B.5. Linux Implementation Details . . . . . . . . . . . . . . 19 B.5. Linux Implementation Details . . . . . . . . . . . . . . 19
skipping to change at page 7, line 41 skipping to change at page 7, line 41
account platform specific implementation details. account platform specific implementation details.
7.1. App-declared Custom URI Scheme Redirection 7.1. App-declared Custom URI Scheme Redirection
Many mobile and desktop computing platforms support inter-app Many mobile and desktop computing platforms support inter-app
communication via URIs by allowing apps to register private-use communication via URIs by allowing apps to register private-use
custom URI schemes like "com.example.app". When the browser or custom URI schemes like "com.example.app". When the browser or
another app attempts to load a URI with a custom scheme, the app that another app attempts to load a URI with a custom scheme, the app that
registered it is launched to handle the request. registered it is launched to handle the request.
As the custom URI scheme does not have a naming authority (as defined To perform an OAuth 2.0 authorization request with a custom URI
by [RFC3986]), there is only a single slash ("/") after the scheme scheme redirect, the native app launches the browser with a standard
component. The following is a complete example of a redirect URI authorization request, but one where the redirection URI utilizes a
utilizing a custom URI scheme: custom URI scheme it registered with the operating system.
com.example.app:/oauth2redirect/example-provider
To perform an OAuth 2.0 Authorization Request with a custom URI
scheme 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 it registered with the
operating system.
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 it results in the operating
system launching the native app, passing in the URI as a launch
parameter. The native app then processes the authorization response
like any OAuth client.
7.1.1. Custom URI Scheme Namespace Considerations
When choosing a URI scheme to associate with the app, apps MUST use a When choosing a URI scheme to associate with the app, apps MUST use a
URI scheme based on a domain name under their control, expressed in URI scheme based on a domain name under their control, expressed in
reverse order, as recommended by Section 3.8 of [RFC7595] for reverse order, as recommended by Section 3.8 of [RFC7595] for
private-use URI schemes. private-use URI schemes.
For example, an app that controls the domain name "app.example.com" For example, an app that controls the domain name "app.example.com"
can use "com.example.app" as their custom scheme. Some authorization can use "com.example.app" as their scheme. Some authorization
servers assign client identifiers based on domain names, for example servers assign client identifiers based on domain names, for example
"client1234.usercontent.example.net", which can also be used as the "client1234.usercontent.example.net", which can also be used as the
domain name for the custom scheme, when reversed in the same manner, domain name for the scheme when reversed in the same manner. A
for example "net.example.usercontent.client1234". scheme such as "myapp" however would not meet this requirement, as it
is not based on a domain name.
URI schemes not based on a domain name (for example "myapp") MUST NOT
be used, as they are not collision resistant, and don't comply with
Section 3.8 of [RFC7595].
Care must be taken when there are multiple apps by the same publisher 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 that each scheme is unique within that group. On platforms that use
use app identifiers that are also based on reverse order domain app identifiers that are also based on reverse order domain names,
names, those can be re-used as the custom URI scheme for the OAuth those can be reused as the custom URI scheme for the OAuth redirect
redirect. to help avoid this problem.
In addition to the collision resistant properties, basing the URI Following the requirements of [RFC3986] Section 3.2, as there is no
scheme off a domain name that is under the control of the app can naming authority for custom URI scheme redirects, only a single slash
help to prove ownership in the event of a dispute where two apps ("/") appears after the scheme component. A complete example of a
claim the same custom scheme (such as if an app is acting redirect URI utilizing a custom URI scheme:
maliciously). For example, if two apps claimed "com.example.app:",
the owner of "example.com" could petition the app store operator to com.example.app:/oauth2redirect/example-provider
remove the counterfeit app. Such a petition is harder to prove if a
generic URI scheme was used. When the authentication server completes the request, it redirects to
the client's redirection URI like it would any redirect URI. As the
redirection URI uses a custom scheme it results in the operating
system launching the native app, passing in the URI as a launch
parameter. The native app then processes the authorization response
like normal.
7.2. App-claimed HTTPS URI Redirection 7.2. App-claimed HTTPS URI Redirection
Some operating systems allow apps to claim HTTPS URL paths in domains Some operating systems allow apps to claim HTTPS URL paths in domains
they control. When the browser encounters a claimed URL, instead of they control. When the browser encounters a claimed URL, instead of
the page being loaded in the browser, the native app is launched with the page being loaded in the browser, the native app is launched with
the URL supplied as a launch parameter. the URL supplied as a launch parameter.
Such claimed HTTPS URIs can be used as OAuth redirect URIs. They are Such claimed HTTPS URIs can be used as OAuth redirect URIs. They are
indistinguishable from OAuth redirects of web-based clients. An indistinguishable from OAuth redirects of web-based clients. An
skipping to change at page 9, line 32 skipping to change at page 9, line 17
7.3. Loopback URI Redirection 7.3. Loopback URI Redirection
Native apps that are able to open a port on the loopback network Native apps that are able to open a port on the loopback network
interface without needing special permissions (typically, those on interface without needing special permissions (typically, those on
desktop operating systems) can use the loopback network interface to desktop operating systems) can use the loopback network interface to
receive the OAuth redirect. receive the OAuth redirect.
Loopback redirect URIs use the HTTP scheme and are constructed with Loopback redirect URIs use the HTTP scheme and are constructed with
the loopback IP literal and whatever port the client is listening on. the loopback IP literal and whatever port the client is listening on.
That is, "http://127.0.0.1:{port}/{path}" for IPv4, and That is, "http://127.0.0.1:{port}/{path}" for IPv4, and
"http://[::1]:{port}/{path}" for IPv6. An complete example of such a "http://[::1]:{port}/{path}" for IPv6. A complete example of such a
redirect with a randomly assigned port: redirect with a randomly assigned port:
http://127.0.0.1:56861/oauth2redirect/example-provider http://127.0.0.1:61023/oauth2redirect/example-provider
The authorization server MUST allow any port to be specified at the The authorization server MUST allow any port to be specified at the
time of the request for loopback IP redirect URIs, to accommodate time of the request for loopback IP redirect URIs, to accommodate
clients that obtain an available port from the operating system at clients that obtain an available ephemeral port from the operating
the time of the request. system at the time of the request.
8. Security Considerations 8. Security Considerations
8.1. Embedded User-Agents 8.1. Embedded User-Agents
Embedded user-agents are an alternative method for authorizing native Embedded user-agents are an alternative method for authorizing native
apps. They are however unsafe for use by third-parties to the apps. They are however unsafe for use by third-parties to the
authorization server by definition, as the app that hosts the authorization server by definition, as the app that hosts the
embedded user-agent can access the user's full authentication embedded user-agent can access the user's full authentication
credential, not just the OAuth authorization grant that was intended credential, not just the OAuth authorization grant that was intended
skipping to change at page 10, line 48 skipping to change at page 10, line 33
also be viable for secure and usable OAuth. This document makes no also be viable for secure and usable OAuth. This document makes no
comment on those patterns. comment on those patterns.
8.3. Phishability of In-App Browser Tabs 8.3. Phishability of In-App Browser Tabs
While in-app browser tabs provide a secure authentication context, as While in-app browser tabs provide a secure authentication context, as
the user initiates the flow from a native app, it is possible for the user initiates the flow from a native app, it is possible for
that native app to completely fake an in-app browser tab. that native app to completely fake an in-app browser tab.
This can't be prevented directly - once the user is in the native 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 app, that app is fully in control of what it can render - however
there are several mitigating factors. there are several mitigating factors.
Importantly, such an attack that uses a web-view to fake an in-app 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 browser tab will always start with no authentication state. If all
native apps use the techniques described in this best practice, users native apps use the techniques described in this best practice, users
will not need to sign-in frequently and thus should be suspicious of 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. any sign-in request when they should have already been signed-in.
This is the case even for authorization servers that require This is the case even for authorization servers that require
occasional or frequent re-authentication, as such servers can occasional or frequent re-authentication, as such servers can
preserve some user identifiable information from the old session, preserve some user identifiable information from the old session,
like the email address or profile picture and display that on the re- like the email address or profile picture and display that
authentication. information during re-authentication.
Users who are particularly concerned about their security may also Users who are particularly concerned about their security may also
take the additional step of opening the request in the browser from take the additional step of opening the request in the browser from
the in-app browser tab, and completing the authorization there, as the in-app browser tab, and completing the authorization there, as
most implementations of the in-app browser tab pattern offer such most implementations of the in-app browser tab pattern offer such
functionality. functionality.
8.4. Protecting the Authorization Code 8.4. Protecting the Authorization Code
The redirect URI options documented in Section 7 share the benefit The redirect URI options documented in Section 7 share the benefit
skipping to change at page 11, line 49 skipping to change at page 11, line 36
authorization response is a risk for native apps. App-claimed HTTPS authorization response is a risk for native apps. App-claimed HTTPS
redirects are hardened against this type of attack due to the redirects are hardened against this type of attack due to the
presence of the URI authority, but they are still public clients and presence of the URI authority, but they are still public clients and
the URI is still transmitted over local channels with unknown the URI is still transmitted over local channels with unknown
security properties. security properties.
The Proof Key for Code Exchange by OAuth Public Clients (PKCE The Proof Key for Code Exchange by OAuth Public Clients (PKCE
[RFC7636]) standard was created specifically to mitigate against this [RFC7636]) standard was created specifically to mitigate against this
attack. It is a Proof of Possession extension to OAuth 2.0 that attack. It is a Proof of Possession extension to OAuth 2.0 that
protects the code grant from being used if it is intercepted. It protects the code grant from being used if it is intercepted. It
achieves this by having the client generate a secret verifier which achieves this by having the client generate a secret verifier, a hash
it passes in the initial authorization request, and which it must of which it passes in the initial authorization request, and which it
present later when redeeming the authorization code grant. An app must present in full when redeeming the authorization code grant. An
that intercepted the authorization code would not be in possession of app that intercepted the authorization code would not be in
this secret, rendering the code useless. possession of this secret, rendering the code useless.
Public native app clients MUST protect the authorization request with Public native app clients MUST protect the authorization request with
PKCE [RFC7636]. Authorization servers MUST support PKCE [RFC7636] PKCE [RFC7636]. Authorization servers MUST support PKCE [RFC7636]
for public native app clients. Authorization servers SHOULD reject for public native app clients. Authorization servers SHOULD reject
authorization requests from native apps that don't use PKCE by authorization requests from native apps that don't use PKCE by
returning an error message as defined in Section 4.4.1 of PKCE returning an error message as defined in Section 4.4.1 of PKCE
[RFC7636]. [RFC7636].
8.5. OAuth Implicit Flow 8.5. OAuth Implicit Flow
The OAuth 2.0 Implicit Flow as defined in Section 4.2 of OAuth 2.0 The OAuth 2.0 Implicit Flow as defined in Section 4.2 of OAuth 2.0
[RFC6749] generally works with the practice of performing the [RFC6749] generally works with the practice of performing the
authorization request in the browser, and receiving the authorization authorization request in the browser, and receiving the authorization
response via URI-based inter-app communication. However, as the response via URI-based inter-app communication. However, as the
Implicit Flow cannot be protected by PKCE (which is a required in Implicit Flow cannot be protected by PKCE (which is a required in
Section 8.4), the use of the Implicit Flow with native apps is NOT Section 8.4), the use of the Implicit Flow with native apps is NOT
RECOMMENDED. RECOMMENDED.
Tokens granted via the implicit flow also cannot be refreshed without Tokens granted via the implicit flow also cannot be refreshed without
user interaction, making the code flow which can issue refresh tokens user interaction, making the code flow - which can issue refresh
the more practical option for native app authorizations that require tokens - the more practical option for native app authorizations that
refreshing. require refreshing.
8.6. Loopback Redirect Considerations 8.6. Loopback Redirect Considerations
Loopback interface redirect URIs use the "http" scheme (i.e. without Loopback interface redirect URIs use the "http" scheme (i.e. without
TLS). This is acceptable for loopback interface redirect URIs as the TLS). This is acceptable for loopback interface redirect URIs as the
HTTP request never leaves the device. HTTP request never leaves the device.
Clients should open the network port only when starting the Clients should open the network port only when starting the
authorization request, and close it once the response is returned. authorization request, and close it once the response is returned.
skipping to change at page 13, line 22 skipping to change at page 13, line 9
client registration details in order to identify and process requests client registration details in order to identify and process requests
accordingly. accordingly.
Authorization servers MUST require clients to register their complete Authorization servers MUST require clients to register their complete
redirect URI (including the path component), and reject authorization redirect URI (including the path component), and reject authorization
requests that specify a redirect URI that doesn't exactly match the requests that specify a redirect URI that doesn't exactly match the
one that was registered, with the exception of loopback redirects, one that was registered, with the exception of loopback redirects,
where an exact match is required except for the port URI component. where an exact match is required except for the port URI component.
For Custom URI scheme based redirects, authorization servers SHOULD For Custom URI scheme based redirects, authorization servers SHOULD
enforce the requirement in Section 7.1.1 that clients use reverse enforce the requirement in Section 7.1 that clients use reverse
domain name based schemes. domain name based schemes. At a minimum, any scheme that doesn't
contain a period character ("."), SHOULD be rejected.
In addition to the collision resistant properties, requiring a URI
scheme based on a domain name that is under the control of the app
can help to prove ownership in the event of a dispute where two apps
claim the same custom URI scheme (where one app is acting
maliciously). For example, if two apps claimed "com.example.app",
the owner of "example.com" could petition the app store operator to
remove the counterfeit app. Such a petition is harder to prove if a
generic URI scheme was used.
Authorization servers MAY request the inclusion of other platform- Authorization servers MAY request the inclusion of other platform-
specific information, such as the app package or bundle name, or specific information, such as the app package or bundle name, or
other information used to associate the app that may be useful for other information used to associate the app that may be useful for
verifying the calling app's identity, on operating systems that verifying the calling app's identity, on operating systems that
support such functions. support such functions.
8.8. Client Authentication 8.8. Client Authentication
Secrets that are statically included as part of an app distributed to Secrets that are statically included as part of an app distributed to
skipping to change at page 15, line 11 skipping to change at page 14, line 48
The requirements of Section 8.7 that authorization servers reject The requirements of Section 8.7 that authorization servers reject
requests with URIs that don't match what was registered are also requests with URIs that don't match what was registered are also
required to prevent such attacks. required to prevent such attacks.
9. IANA Considerations 9. IANA Considerations
[RFC Editor: please do NOT remove this section.] [RFC Editor: please do NOT remove this section.]
Section 7.1 specifies how private-use URI schemes are used for inter- Section 7.1 specifies how private-use URI schemes are used for inter-
app communication in OAuth protocol flows. This document requires in app communication in OAuth protocol flows. This document requires in
Section 7.1.1 that such schemes are based on domain names owned or Section 7.1 that such schemes are based on domain names owned or
assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per
section 6 of [RFC7595], registration of domain based URI schemes with section 6 of [RFC7595], registration of domain based URI schemes with
IANA is not required. Therefore, this document has no IANA actions. IANA is not required. Therefore, this document has no IANA actions.
10. References 10. References
10.1. Normative References 10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
skipping to change at page 18, line 40 skipping to change at page 18, line 37
Both traditional and Universal Windows Platform (UWP) apps can Both traditional and Universal Windows Platform (UWP) apps can
perform authorization requests in the user's browser. Traditional perform authorization requests in the user's browser. Traditional
apps typically use a loopback redirect to receive the authorization apps typically use a loopback redirect to receive the authorization
response, and listening on the loopback interface is allowed by response, and listening on the loopback interface is allowed by
default firewall rules. Universal Windows Platform (UWP) apps can default firewall rules. Universal Windows Platform (UWP) apps can
use custom URI scheme redirects to receive the authorization use custom URI scheme redirects to receive the authorization
response, which will bring the app to the foreground. Known on the response, which will bring the app to the foreground. Known on the
platform as "URI Activation", the URI scheme is limited to 39 platform as "URI Activation", the URI scheme is limited to 39
characters in length, and may include the "." character, making short characters in length, and may include the "." character, making short
reverse domain name based schemes (as recommended in Section 7.1.1) reverse domain name based schemes (as recommended in Section 7.1)
possible. possible.
An open source sample demonstrating these patterns is available An open source sample demonstrating these patterns is available
[SamplesForWindows]. [SamplesForWindows].
B.4. macOS Implementation Details B.4. macOS Implementation Details
Apps can initiate an authorization request in the user's default Apps can initiate an authorization request in the user's default
browser using platform APIs for opening URIs in the browser. browser using platform APIs for opening URIs in the browser.
 End of changes. 21 change blocks. 
66 lines changed or deleted 61 lines changed or added

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