draft-ietf-oauth-native-apps-02.txt   draft-ietf-oauth-native-apps-03.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: January 3, 2017 Ping Identity Expires: January 21, 2017 Ping Identity
July 02, 2016 July 20, 2016
OAuth 2.0 for Native Apps OAuth 2.0 for Native Apps
draft-ietf-oauth-native-apps-02 draft-ietf-oauth-native-apps-03
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 system browser. This through external user-agents, primarily the system 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 January 3, 2017. This Internet-Draft will expire on January 21, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 34 skipping to change at page 2, line 34
8.3. Phishability of In-App Browser Tabs . . . . . . . . . . . 12 8.3. Phishability of In-App Browser Tabs . . . . . . . . . . . 12
8.4. Limitations of Non-verifiable Clients . . . . . . . . . . 12 8.4. Limitations of Non-verifiable Clients . . . . . . . . . . 12
9. Other External User Agents . . . . . . . . . . . . . . . . . 12 9. Other External User Agents . . . . . . . . . . . . . . . . . 12
10. Client Authentication . . . . . . . . . . . . . . . . . . . . 13 10. Client Authentication . . . . . . . . . . . . . . . . . . . . 13
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
11.1. Normative References . . . . . . . . . . . . . . . . . . 13 11.1. Normative References . . . . . . . . . . . . . . . . . . 13
11.2. Informative References . . . . . . . . . . . . . . . . . 13 11.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Operating System Specific Implementation Details . . 15 Appendix A. Operating System Specific Implementation Details . . 15
A.1. iOS Implementation Details . . . . . . . . . . . . . . . 15 A.1. iOS Implementation Details . . . . . . . . . . . . . . . 15
A.2. Android Implementation Details . . . . . . . . . . . . . 15 A.2. Android Implementation Details . . . . . . . . . . . . . 15
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 15 A.3. Windows Implementation Details . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 A.4. macOS Implementation Details . . . . . . . . . . . . . . 16
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
The OAuth 2.0 [RFC6749] authorization framework, documents two The OAuth 2.0 [RFC6749] authorization framework, documents two
approaches in Section 9 for native apps to interact with the approaches in Section 9 for native apps to interact with the
authorization endpoint: via an embedded user-agent, or an external authorization endpoint: via an embedded user-agent, or an external
user-agent. user-agent.
This document recommends external user-agents like in-app browser This document recommends external user-agents like in-app browser
tabs as the only secure and usable choice for OAuth. It documents tabs as the only secure and usable choice for OAuth. It documents
skipping to change at page 7, line 24 skipping to change at page 7, line 24
7.1. App-declared Custom URI Scheme Redirection 7.1. App-declared Custom URI Scheme Redirection
Most major mobile and desktop computing platforms support inter-app Most major mobile and desktop computing platforms support inter-app
communication via URIs by allowing apps to register custom URI communication via URIs by allowing apps to register custom URI
schemes. When the system browser or another app attempts to follow a schemes. When the system browser or another app attempts to follow a
URI with a custom scheme, the app that registered it is launched to URI with a custom scheme, the app that registered it is launched to
handle the request. This document is only relevant on platforms that handle the request. This document is only relevant on platforms that
support this pattern. support this pattern.
In particular, the custom URI scheme pattern is supported on the In particular, the custom URI scheme pattern is supported on Android
mobile platforms Android [Android.URIScheme], iOS [iOS.URIScheme], [Android.URIScheme], iOS [iOS.URIScheme], Windows Universal Platform
and Windows Phone [WindowsPhone.URIScheme]. Desktop operating (UWP) [WindowsUWP.URIScheme] and macOS [macOS.URIScheme].
systems Windows [Windows.URIScheme] and OS X [OSX.URIScheme] also
support custom URI schemes.
7.1.1. Using Custom URI Schemes for Redirection 7.1.1. Using Custom URI Schemes for Redirection
To perform an OAuth 2.0 Authorization Request on a supported To perform an OAuth 2.0 Authorization Request on a supported
platform, the native app launches the system browser with a normal platform, the native app launches the system browser with a normal
OAuth 2.0 Authorization Request, but provides a redirection URI that OAuth 2.0 Authorization Request, but provides a redirection URI that
utilizes a custom URI scheme that is registered by the calling app. utilizes a custom URI scheme that is registered by the calling app.
When the authentication server completes the request, it redirects to When the authentication server completes the request, it redirects to
the client's redirection URI like it would any redirect URI, but as the client's redirection URI like it would any redirect URI, but as
skipping to change at page 10, line 38 skipping to change at page 10, line 34
credentials than they need, potentially increasing the attack credentials than they need, potentially increasing the attack
surface. surface.
In typical web-view based implementations of embedded user-agents, In typical web-view based implementations of embedded user-agents,
the host application can: log every keystroke entered in the form to the host application can: log every keystroke entered in the form to
capture usernames and passwords; automatically submit forms and capture usernames and passwords; automatically submit forms and
bypass user-consent; copy session cookies and use them to perform bypass user-consent; copy session cookies and use them to perform
authenticated actions as the user. authenticated actions as the user.
Encouraging users to enter credentials in an embedded web-view Encouraging users to enter credentials in an embedded web-view
without the usual address bar and other identity features that without the usual address bar and visible certificate validation
browsers have makes it impossible for the user to know if they are features that browsers have makes it impossible for the user to know
signing in to the legitimate site, and even when they are, it trains if they are signing in to the legitimate site, and even when they
them that it's OK to enter credentials without validating the site are, it trains them that it's OK to enter credentials without
first. validating the site first.
Aside from the security concerns, web-views do not share the Aside from the security concerns, web-views do not share the
authentication state with other apps or the system browser, requiring authentication state with other apps or the system browser, requiring
the user to login for every authorization request and leading to a the user to login for every authorization request and leading to a
poor user experience. poor user experience.
Due to the above, use of embedded user-agents is NOT RECOMMENDED, Due to the above, use of embedded user-agents is NOT RECOMMENDED,
except where a trusted first-party app acts as the external user- except where a trusted first-party app acts as the external user-
agent for other apps, or provides single sign-on for multiple first- agent for other apps, or provides single sign-on for multiple first-
party apps. party apps.
skipping to change at page 11, line 46 skipping to change at page 11, line 40
[RFC7636]) standard was created specifically to mitigate against this [RFC7636]) standard was created specifically to mitigate against this
attack. It is a Proof of Possession extension to OAuth 2.0 that attack. It is a Proof of Possession extension to OAuth 2.0 that
protects the code grant from being used if it is intercepted. It protects the code grant from being used if it is intercepted. It
achieves this by having the client generate a secret verifier which achieves this by having the client generate a secret verifier which
it passes in the initial authorization request, and which it must it passes in the initial authorization request, and which it must
present later when redeeming the authorization code grant. An app present later when redeeming the authorization code grant. An app
that intercepted the authorization code would not be in possession of that intercepted the authorization code would not be in possession of
this secret, rendering the code useless. this secret, rendering the code useless.
Both the client and the Authorization Server MUST support PKCE Both the client and the Authorization Server MUST support PKCE
[RFC7636] to use custom URI schemes, or loopback redirects. [RFC7636] to use custom URI schemes, or loopback IP redirects.
Authorization Servers SHOULD reject authorization requests using a Authorization Servers SHOULD reject authorization requests using a
custom scheme, or localhost as part of the redirection URI if the custom scheme, or loopback IP as part of the redirection URI if the
required PKCE parameters are not present, returning the error message required PKCE parameters are not present, returning the error message
as defined in Section 4.4.1 of PKCE [RFC7636]. It is RECOMMENDED to 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 use PKCE [RFC7636] for app-claimed HTTPS redirect URIs, even though
these are not generally subject to interception, to protect against these are not generally subject to interception, to protect against
attacks on inter-app communication. attacks on inter-app communication.
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
skipping to change at page 14, line 6 skipping to change at page 14, line 6
<http://www.rfc-editor.org/info/rfc3986>. <http://www.rfc-editor.org/info/rfc3986>.
11.2. Informative References 11.2. Informative References
[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819, Threat Model and Security Considerations", RFC 6819,
DOI 10.17487/RFC6819, January 2013, DOI 10.17487/RFC6819, January 2013,
<http://www.rfc-editor.org/info/rfc6819>. <http://www.rfc-editor.org/info/rfc6819>.
[iOS.URIScheme] [iOS.URIScheme]
"Inter-App Communication", February 2015, <https://develop "Inter-App Communication", July 2016, <https://developer.a
er.apple.com/library/ios/documentation/iPhone/Conceptual/ pple.com/library/ios/documentation/iPhone/Conceptual/
iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter- iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-
AppCommunication.html>. AppCommunication.html>.
[OSX.URIScheme] [macOS.URIScheme]
"Launch Services Concepts", February 2015, <https://develo "Launch Services Concepts", July 2016, <https://developer.
per.apple.com/library/mac/documentation/Carbon/Conceptual/ apple.com/library/mac/documentation/Carbon/Conceptual/Laun
LaunchServicesConcepts/LSCConcepts/LSCConcepts.html#//appl chServicesConcepts/LSCConcepts/LSCConcepts.html#//apple_re
e_ref/doc/uid/TP30000999-CH202-CIHFEEAD>. f/doc/uid/TP30000999-CH202-CIHFEEAD>.
[Android.URIScheme] [Android.URIScheme]
"Intents and Intent Filters", February 2015, "Intents and Intent Filters", July 2016,
<http://developer.android.com/guide/components/ <http://developer.android.com/guide/components/
intents-filters.html#ires>. intents-filters.html#ires>.
[WindowsPhone.URIScheme] [WindowsUWP.URIScheme]
"Auto-launching apps using file and URI associations for "Handle URI activation", July 2016,
Windows Phone 8", February 2015, <https://msdn.microsoft.com/en-us/windows/uwp/launch-
<https://msdn.microsoft.com/en-us/library/windows/apps/ resume/handle-uri-activation>.
jj206987(v=vs.105).aspx>.
[Windows.URIScheme]
"Registering an Application to a URI Scheme", February
2015, <https://msdn.microsoft.com/en-us/library/ie/
aa767914%28v=vs.85%29.aspx>.
[IANA.URISchemes] [IANA.URISchemes]
"Uniform Resource Identifier (URI) Schemes", February "Uniform Resource Identifier (URI) Schemes", July 2016,
2015, <http://www.iana.org/assignments/uri-schemes/ <http://www.iana.org/assignments/uri-schemes/
uri-schemes.xhtml>. uri-schemes.xhtml>.
[ChromeCustomTab] [ChromeCustomTab]
"Chrome Custom Tabs", July 2015, "Chrome Custom Tabs", July 2016,
<https://developer.chrome.com/multidevice/android/ <https://developer.chrome.com/multidevice/android/
customtabs>. customtabs>.
[SFSafariViewController] [SFSafariViewController]
"SafariServices Changes", July 2015, <https://developer.ap "SafariServices Changes", July 2016,
ple.com/library/prerelease/ios/releasenotes/General/ <https://developer.apple.com/library/ios/documentation/
iOS90APIDiffs/frameworks/SafariServices.html>. SafariServices/Reference/SFSafariViewController_Ref/>.
[Android.AppLinks] [Android.AppLinks]
"App Links", July 2015, "App Links", July 2015,
<https://developer.android.com/preview/features/app- <https://developer.android.com/preview/features/app-
linking.html>. linking.html>.
[CustomTabsService]
"CustomTabsService", July 2016,
<https://developer.android.com/reference/android/support/
customtabs/CustomTabsService.html>.
[UniversalLinks]
"Universal Links", July 2016, <https://developer.apple.com
/library/ios/documentation/General/Conceptual/AppSearch/
UniversalLinks.html>.
Appendix A. Operating System Specific Implementation Details Appendix A. Operating System Specific Implementation Details
Most of this document attempts to lay out best practices in an Most of this document attempts to lay out best practices in an
generic manner, referencing technology available on most operating generic manner, referencing technology available on most operating
systems. This non-normative section contains OS-specific systems. This non-normative section contains OS-specific
implementation details that are accurate at the time of authorship. implementation details that are accurate at the time of authorship.
It is expected that this OS-specific information will change, but It is expected that this OS-specific information will change, but
that the overall principles described in this document for using that the overall principles described in this document for using
external user-agents will remain valid. external user-agents will remain valid.
A.1. iOS Implementation Details A.1. iOS Implementation Details
From iOS 9, apps can invoke the system browser without the user Claimed HTTPS and custom URI scheme redirects are both viable choices
leaving the app through SFSafariViewController for OAuth on iOS. Developers can claim HTTPS links using Universal
[SFSafariViewController], which implements the browser-view pattern. Links [UniversalLinks], available since iOS 9, and can use custom URI
This class has all the properties of the system browser, and is scheme [iOS.URIScheme] redirects for backwards compatibility.
considered an 'external user-agent', even though it is presented Clients SHOULD use Universal Links for authorization requests on iOS
within the host app. Regardless of whether the system browser is 9 and beyond, with the custom URI scheme redirect substituted on
opened, or SFSafariViewController, the return of the token goes older versions. In both cases, the app claims the redirect in the
through the same system. application manifest.
As a user experience optimisation, since iOS 9, apps can invoke the
system browser without the user leaving the app through
SFSafariViewController [SFSafariViewController], which implements the
browser-view pattern. This class has all the properties of the
system browser, and is an 'external user-agent', even though it is
presented within the host app. Regardless of whether the user
completes the request in the system browser (as is their choice), or
the SFSafariViewController, the return of the token via custom URI
scheme or claimed HTTPS link is the same.
A.2. Android Implementation Details A.2. Android Implementation Details
Chrome 45 introduced the concept of Chrome Custom Tab Claimed HTTPS and custom URI scheme redirects are both viable choices
[ChromeCustomTab], which follows the browser-view pattern and allows for OAuth on Android. Developers can claim HTTPS links using App
authentication without the user leaving the app. Links [Android.AppLinks], available since 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 redirect in the application manifest.
The return of the token can go through the custom URI scheme or As a user experience optimisation, apps SHOULD try to launch the
claimed HTTPS URI (including those registered with the App Link authorization request in a Custom Tab. Custom Tab is an
[Android.AppLinks] system), or the navigation events can be observed implementation of the browser-view pattern, providing a secure
by the host app. It is RECOMMENDED that the custom URI, or claimed browser tab displayed in the context of the app. Chrome is an
HTTPS URI options be used for better portability, to allow the user example of a browser that supports [ChromeCustomTab] CustomTabs.
to open the authorization request in the Chrome app, and to prevent
accidental observation of intermediate tokens on URI parameters.
At the time of writing, Android does allow apps to claim HTTPs links Android Browser vendors SHOULD implement the CustomTabsService
(App Links), but not in a way that is usable for OAuth, the native [CustomTabsService] to provide this functionality to their users.
app is only opened if the intent is fired from outside the browser.
A.3. Windows Implementation Details
Apps written on the Universal Windows Platform (UWP) can claim custom
URI schemes [WindowsUWP.URIScheme] in their application manifest.
This redirect choice will also open the app when the user taps the
link. The scheme is limited to 39 characters, and may include the
`.` character.
UWP apps can launch the authorization request in the user's default
browser like so:
Uri authorizationRequest = ...
var success = Windows.System.Launcher.LaunchUriAsync(authorizationRequest)
The loopback IP redirect is a common choice for traditional Desktop
apps, and listening on a loopback port is permitted by default
Windows firewall rules.
Traditional apps can launch the URI in the user's default browser
like so:
string authorizationRequest = ...
System.Diagnostics.Process.Start(authorizationRequest);
When using the "Process.Start" method, care must be taken that the
input is a valid URL, including correct URI encoding of the
parameters. This is especially important when the URL includes user-
supplied information such as a login hint.
A.4. macOS Implementation Details
Both the loopback IP and custom URI scheme redirect choices are
viable on macOS. Custom URI schemes [macOS.URIScheme] are registered
in the application manifest. Listening on the loopback IP typically
does not require any firewall changes.
Apps can launch the authorization request like so:
NSURL *authorizationRequest = ...
BOOL success = [[NSWorkspace sharedWorkspace] openURL:authorizationRequest];
Appendix B. Acknowledgements Appendix B. Acknowledgements
The author would like to acknowledge the work of Marius Scurtescu, The author would like to acknowledge the work of Marius Scurtescu,
and Ben Wiley Sittler whose design for using custom URI schemes in and Ben Wiley Sittler whose design for using custom URI schemes in
native OAuth 2.0 clients formed the basis of Section 7.1. native OAuth 2.0 clients formed the basis of Section 7.1.
The following individuals contributed ideas, feedback, and wording The following individuals contributed ideas, feedback, and wording
that shaped and formed the final specification: that shaped and formed the final specification:
Naveen Agarwal, John Bradley, Brian Campbell, Adam Dawes, Hannes Naveen Agarwal, Brian Campbell, Adam Dawes, Hannes Tschofenig, Ashish
Tschofenig, Ashish Jain, Paul Madsen, Breno de Medeiros, Eric Sachs, Jain, Paul Madsen, Breno de Medeiros, Eric Sachs, Nat Sakimura, Steve
Nat Sakimura, Steve Wright, Erik Wahlstrom, Andy Zmolek, Sudhi Wright, Erik Wahlstrom, Andy Zmolek, Sudhi Umarji.
Umarji.
Authors' Addresses Authors' Addresses
William Denniss William Denniss
Google Google
1600 Amphitheatre Pkwy 1600 Amphitheatre Pkwy
Mountain View, CA 94043 Mountain View, CA 94043
USA USA
Phone: +1 650-253-0000 Phone: +1 650-253-0000
 End of changes. 21 change blocks. 
67 lines changed or deleted 123 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/