idnits 2.17.1 draft-wdenniss-oauth-native-apps-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 22, 2015) is 3201 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC6819' is defined on line 480, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCE' Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group W. Denniss 3 Internet-Draft Google 4 Intended status: Best Current Practice J. Bradley 5 Expires: January 23, 2016 Ping Identity 6 July 22, 2015 8 OAuth 2.0 for Native Apps 9 draft-wdenniss-oauth-native-apps-00 11 Abstract 13 OAuth 2.0 authorization requests from native apps should only be made 14 through external user-agents such as the system browser. This 15 specification details the security and usability reasons why this is 16 the case, and how native apps and authorization servers can implement 17 this best practice. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 23, 2016. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Authorization Flow for Native Apps . . . . . . . . . . . 3 55 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 4 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4. The External User-Agent . . . . . . . . . . . . . . . . . . . 5 58 5. Redirection URIs for Native Apps . . . . . . . . . . . . . . 5 59 5.1. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 5 60 5.2. App-declared Custom URI Scheme Redirection . . . . . . . 6 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 62 6.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 8 63 6.2. Protecting the Authorization Code . . . . . . . . . . . . 9 64 6.3. Claimed URLs and Phishing . . . . . . . . . . . . . . . . 10 65 6.4. Always Prompting for User Interaction . . . . . . . . . . 10 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 68 7.2. Informative References . . . . . . . . . . . . . . . . . 11 69 Appendix A. Operating System Specific Implementation Details . . 12 70 A.1. iOS Implementation Details . . . . . . . . . . . . . . . 12 71 A.2. Android Implementation Details . . . . . . . . . . . . . 12 72 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 13 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 75 1. Introduction 77 The OAuth 2.0 [RFC6749] authorization framework, documents two ways 78 in Section 9 for native apps to interact with the authorization 79 endpoint: via an embedded user-agent, or an external user-agent. 81 This document recommends external user-agents (such as the system 82 browser) as the only secure and usable choice for OAuth2. It 83 documents how native apps can implement authorization flows with such 84 agents, and the additional requirements of authorization servers 85 needed to support such usage. 87 Many native apps today are using an embedded user-agent in the form 88 of a web-view. This approach suffers from several security and 89 usability issues including allowing the client app to eavesdrop user 90 credentials, and forcing users to sign-in to each app separately. 92 OAuth flows between a native app and the system browser (or another 93 external user-agent) are more secure, and take advantage of the 94 shared authentication state. Operating systems are increasingly 95 making the system browser even more viable for OAuth by allowing apps 96 to show a browser window within the active app, removing the only 97 usability benefit of using embedded browsers in the first place (not 98 wanting to send the user to another app). 100 Inter-app communication (such as that between a native OAuth client 101 and the system browser) can be achieved through app-specific custom 102 URI schemes and/or claimed HTTPS URLs. For example, an app can 103 launch the system browser with a HTTPS request (such as an OAuth 104 request), the browser can process the request and return control to 105 the app by simply following a URI using a scheme that the app 106 registered (for example "com.example.app:/oauth2callback?code=..."), 107 or a HTTPS path that the app claimed. Parameters can be passed 108 through these URIs, allowing complete use of OAuth flows, while 109 minimizing the added complexity for authorization servers to support 110 native apps. 112 1.1. Authorization Flow for Native Apps 114 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 115 | User Device | 116 | | 117 | +---------------------------+ | +-----------+ 118 | | | | (4) Authz Grant | | 119 | | Client App |----------------------->| Authz | 120 | | |<-----------------------| Server | 121 | +---------------------------+ | (5) Access Token | | 122 | | ^ | +-----------+ 123 | | | | 124 | | | | 125 | | (1) | (3) | 126 | | Authz | Authz | 127 | | Request | Grant | 128 | | "https://" | "app:/" | 129 | | | | 130 | v | | 131 | +---------------------------+ | +-----------+ 132 | | | | (2) User | | 133 | | System Browser | | authenticated | Identity | 134 | | |<---------------------->| Provider | 135 | +---------------------------+ | | | 136 | | +-----------+ 137 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 139 Figure 1: Native App Authorization via External User-agent 141 Figure 1 illustrates the interaction of the native app with the 142 system browser to achieve authorization via an external user-agent. 144 1) The client app launches the system browser or browser-view with 145 the authorization request (e.g. https://idp.example.com/oauth2/ 146 auth...) 148 2) Server authenticates the end-user, potentially chaining to another 149 authentication system, and issues Authorization Code Grant on 150 success 152 3) Browser switches focus back to the client app using a URI with a 153 custom scheme or claimed HTTPS URL, passing the code as a URI 154 parameter. 156 4) Client presents the OAuth 2.0 authorization code and PKCE [PKCE] 157 proof of possession verifier 159 5) Server issues the tokens requested 161 2. Notational Conventions 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this document are to be interpreted as described in Key 166 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 167 these words are used without being spelled in uppercase then they are 168 to be interpreted with their normal natural language meanings. 170 3. Terminology 172 In addition to the terms defined in referenced specifications, this 173 document uses the following terms: 175 "app" A native application, such as one on a mobile device or 176 desktop operating system. 178 "app store" An ecommerce store where users can download and purchase 179 apps. Typically with quality-control measures to product users. 181 "system browser" The operating system's native default browser, 182 typically pre-installed as part of the operating system, or 183 installed and set as default by the user. For example mobile 184 Safari on iOS, and Chrome on Android. 186 "web-view" A web browser UI component that can be embedded in apps 187 to render web pages, used to create embedded user-agents. 189 "browser-view" A full page browser with limited navigation 190 capabilities that is displayed inside a host app, but retains the 191 full security properties and authentication state of the system 192 browser. Goes by different names on different platforms, such as 193 SFSafariViewController on iOS 9, and Chrome Custom Tab in Chrome 194 for Android. 196 "reverse domain name notation" A naming convention based on the 197 domain name system, but where where the domain components are 198 reversed, for example "app.example.com" becomes "com.example.app". 200 "custom URI scheme" A URI scheme (as defined by [RFC3986]) that the 201 app creates and registers with the OS (and is not a standard URI 202 scheme like "https:" or "tel:"). Requests to such a scheme 203 results in the app which registered it being launched by the OS. 204 For example, "myapp:", "com.example.myapp:" are both custom URI 205 schemes. 207 "inter-app communication" Communication between two apps on a 208 device. 210 4. The External User-Agent 212 The external user-agent for native apps can be the system browser, or 213 a native app provided by the authorization server. 215 Both the system browser and authorization server app affords several 216 advantages for OAuth over embedded web-view based user-agents, 217 including the security of a separate process, and usability of a 218 shared authentication session. 220 The system browser is the RECOMMENDED external user-agent choice for 221 most authorization servers, as it reduces implementation complexity 222 by reusing the web authorization endpoint, and is often needed as a 223 fallback even when an authorization server app is available. 225 5. Redirection URIs for Native Apps 227 5.1. App-claimed HTTPS URI Redirection 229 Several operating systems support a method for an app to claim a 230 regular HTTPS URL. When such a URL is loaded in the browser, instead 231 of the request being made and the page loaded, the native app is 232 launched instead. 234 On operating systems that support app-claimed HTTPS URIs, these URIs 235 SHOULD be used with OAuth, as they allow the identity of the 236 destination app to be guaranteed by the operating system. 238 Apps on platforms that allow the user to disable this functionality, 239 or lack it altogether MUST fallback to using custom URI schemes. 241 The authorization server MUST allow the registration of HTTPS 242 redirect URIs for non-confidential native clients to support app- 243 claimed HTTPS redirect URIs. 245 5.2. App-declared Custom URI Scheme Redirection 247 Most major mobile and desktop computing platforms support inter-app 248 communication via URIs by allowing apps to register custom URI 249 schemes. When the system browser or another app attempts to follow a 250 URI with a custom scheme, the app that registered it is launched to 251 handle the request. This document is only relevant on platforms that 252 support this pattern. 254 In particular, the custom URI scheme pattern is supported on the 255 mobile platforms Android [Android.URIScheme], iOS [iOS.URIScheme], 256 and Windows Phone [WindowsPhone.URIScheme]. Desktop operating 257 systems Windows [Windows.URIScheme] and OS X [OSX.URIScheme] also 258 support custom URI schemes. 260 5.2.1. Using Custom URI Schemes for Redirection 262 To perform an OAuth 2.0 Authorization Request on a supported 263 platform, the native app launches the system browser with a normal 264 OAuth 2.0 Authorization Request, but provides a redirection URI that 265 utilizes a custom URI scheme that is registered by the calling app. 267 When the authentication server completes the request, it redirects to 268 the client's redirection URI like it would any redirect URI, but as 269 the redirection URI uses a custom scheme, this results in the OS 270 launching the native app passing in the URI. The native app extracts 271 the code from the query parameters from the URI just like a web 272 client would, and exchanges the Authorization Code like a regular 273 OAuth 2.0 client. 275 5.2.2. Custom URI Scheme Namespace Considerations 277 When selecting which URI scheme to associate with the app, apps 278 SHOULD pick a scheme that is globally unique, and which they can 279 assert ownership over. 281 To avoid clashing with existing schemes in use, using a scheme that 282 follows the reverse domain name pattern applied to a domain under the 283 app publishers control is RECOMMENDED. Such a scheme can be based on 284 a domain they control, or the OAuth client identifier in cases where 285 the authorization server issues client identifiers that are also 286 valid DNS subdomains. The chosen scheme MUST NOT clash with any IANA 287 registered scheme [IANA.URISchemes]. You SHOULD also ensure that no 288 other app by the same publisher uses the same scheme. 290 Schemes using reverse domain name notation are hardened against 291 collision. They are unlikely to clash with an officially registered 292 scheme [IANA.URISchemes] or unregistered de-facto scheme, as these 293 generally don't include a period character, and are unlikely to match 294 your domain name in any case. They are guaranteed not to clash with 295 any OAuth client following these naming guidelines in full. 297 Some platforms use globally unique bundle or package names that 298 follow the reverse domain name notation pattern. In these cases, the 299 app SHOULD register that bundle id as the custom scheme. If an app 300 has a bundle id or package name that doesn't match a domain name 301 under the control of the app, the app SHOULD NOT register that as a 302 scheme, and instead create a URI scheme based off one of their domain 303 names. 305 For example, an app whose publisher owns the top level domain name 306 "example.com" can register "com.example.app:/" as their custom 307 scheme. An app whose authorization server issues client identifiers 308 that are also valid domain names, for example 309 "client1234.usercontent.idp.com", can use the reverse domain name 310 notation of that domain as the scheme, i.e. 311 "com.idp.usercontent.client1234:/". Each of these examples are URI 312 schemes which are likely to be unique, and where the publisher can 313 assert ownership. 315 As a counter-example, using a simple custom scheme like "myapp:/" is 316 not guaranteed to be unique and is NOT RECOMMENDED. 318 In addition to uniqueness, basing the URI scheme off a name that is 319 under the control of the app's publisher can help to prove ownership 320 in the event of a dispute where two apps register the same custom 321 scheme (such as if an app is acting maliciously). For example, if 322 two apps registered "com.example.app:", the true owner of 323 "example.com" could petition the app store operator to remove the 324 counterfeit app. This petition is harder to prove if a generic URI 325 scheme was chosen. 327 5.2.3. Registration of App Redirection URIs 329 As recommended in Section 3.1.2.2 of [RFC6749], the authorization 330 server SHOULD require the client to pre-register the redirection URI. 331 This remains true for app redirection URIs that use custom schemes. 333 Additionally, authorization servers MAY request the inclusion of 334 other platform-specific information, such as the app package or 335 bundle name, or other information used to associate the app that may 336 be useful for verifying the calling app's identity, on operating 337 systems that support such functions. 339 Authorizations servers SHOULD support the ability for native apps to 340 register Redirection URIs that utilize custom URI schemes. 341 Authorization servers SHOULD enforce the recommendation in 342 Section 5.2.2 that apps follow naming guidelines for URI schemes. 344 6. Security Considerations 346 6.1. Embedded User-Agents 348 Embedded user-agents, commonly implemented with web-views, are an 349 alternative method for authorizing native apps. They are however 350 unsafe for use by third-parties by definition. They involve the user 351 signing in with their full login credentials, only to have them 352 downscoped to less powerful OAuth credentials. 354 Even when used by trusted first-party apps, embedded user-agents 355 violate the principle of least privilege by obtaining more powerful 356 credentials than they need, potentially increasing the attack 357 surface. 359 In typical web-view based implementations of embedded user-agents, 360 the host application can: log every keystroke entered in the form to 361 capture usernames and passwords; automatically submit forms and 362 bypass user-consent; copy session cookies and use them to perform 363 authenticated actions as the user. 365 Encouraging users to enter credentials in an embedded web-view 366 without the usual address bar and other identity features that 367 browsers have makes it impossible for the user to know if they are 368 signing in to the legitimate site, and even when they are, it trains 369 them that it's OK to enter credentials without validating the site 370 first. 372 Aside from the security concerns, web-views do not share the 373 authentication state with other apps or the system browser, requiring 374 the user to login for every authorization request and leading to a 375 poor user experience. 377 The only use-case where it is reasonable to use an embedded user- 378 agent is when the app itself is a trusted and secure first-party app 379 that acts as the external user-agent for other apps. Use of embedded 380 user-agents by first party apps other than those that act as an 381 external user-agent themselves is NOT RECOMMENDED, as it increases 382 development complexity and the potential to introduce security 383 issues, and hampers the potential for usability improvements through 384 taking advantage of the shared authentication context. 386 Authorization servers SHOULD consider taking steps to detect and 387 block logins via embedded user-agents that are not their own, where 388 possible. 390 6.2. Protecting the Authorization Code 392 A limitation of custom URI schemes is that multiple apps can 393 typically register the same scheme, which makes it indeterminate as 394 to which app will receive the Authorization Code Grant. This is not 395 an issue for HTTPS redirection URIs (i.e. standard web URLs) due to 396 the fact the HTTPS URI scheme is enforced by the authority (as 397 defined by [RFC3986]), being the domain name system, which does not 398 allow multiple entities to own a single domain. 400 If multiple apps register the same scheme, it is possible that the 401 authorization code will be sent to the wrong app (generally the 402 operating system makes no guarantee of which app will handle the URI 403 when multiple register the same scheme). Figure 1 of [PKCE] 404 demonstrates the code interception attack. This attack vector 405 applies to public clients (clients that are unable to maintain a 406 client secret) which is typical of most installed apps. 408 While Section 5.2.2 mentions ways that this can be mitigated through 409 policy enforcement (by being able to request that the offending app 410 is removed), we can also protect the authorization code grant from 411 being used in cases where it was intercepted. 413 The Proof Key for Code Exchange by OAuth Public Clients (PKCE) [PKCE] 414 standard was created specifically to mitigate against this attack. 415 It is a Proof of Possession extension to OAuth 2.0 that protects the 416 code grant from being used if it is intercepted. 418 Both the client and the Authorization Server MUST support PKCE [PKCE] 419 to use custom URI schemes. Authorization Servers SHOULD reject 420 requests that use a custom scheme in the redirection URI if the 421 required PKCE parameters are not also present, returning the error 422 message as defined in Section 4.4.1 of [PKCE] 424 PKCE provides proof of possession by the client generating a secret 425 verifier which it passes in the initial authorization request, and 426 which it must present later when redeeming the authorization code 427 grant. An app that intercepted the authorization code would not be 428 in possession of this secret, rendering the code useless. 430 6.3. Claimed URLs and Phishing 432 While using a claimed HTTPS URI for redirection in the system browser 433 guarantees the identity of the receiving app, it is still possible 434 for a bad app to put the user through an authentication flow in an 435 embedded user-agent of their own, and observe the redirect URI. 437 We can't directly prevent this, however it can be mitigated through 438 user contextual awareness. Such an attack necessarily starts with no 439 authentication state, meaning that the user will be prompted to sign- 440 in. If all native apps are using the techniques described here, 441 users should not be signing-in frequently, and thus should treat any 442 password request event with more suspicion. Sophisticated users will 443 be able to recognise the UI treatment of the browser-view or full 444 system browser, and shouldn't sign-in anywhere else. Users who are 445 particularly security conscious can also use the "open in browser" 446 functionality from the browser-view to gain even more assurances 447 about where they are entering their credentials. 449 6.4. Always Prompting for User Interaction 451 Due to the fact that the identity of non-confidential clients cannot 452 be assured, tokens SHOULD NOT be issued to such clients without user 453 consent or interaction, even if the the user has consented to the 454 scopes and approved the client previously. 456 7. References 458 7.1. Normative References 460 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 461 RFC 6749, DOI 10.17487/RFC6749, October 2012, 462 . 464 [PKCE] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "The Proof 465 Key for Code Exchange by OAuth Public Clients", February 466 2015, . 468 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 469 Requirement Levels", BCP 14, RFC 2119, 470 DOI 10.17487/RFC2119, March 1997, 471 . 473 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 474 Resource Identifier (URI): Generic Syntax", STD 66, 475 RFC 3986, DOI 10.17487/RFC3986, January 2005, 476 . 478 7.2. Informative References 480 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 481 Threat Model and Security Considerations", RFC 6819, 482 DOI 10.17487/RFC6819, January 2013, 483 . 485 [iOS.URIScheme] 486 "Inter-App Communication", February 2015, . 491 [OSX.URIScheme] 492 "Launch Services Concepts", February 2015, . 497 [Android.URIScheme] 498 "Intents and Intent Filters", February 2015, 499 . 502 [WindowsPhone.URIScheme] 503 "Auto-launching apps using file and URI associations for 504 Windows Phone 8", February 2015, 505 . 508 [Windows.URIScheme] 509 "Registering an Application to a URI Scheme", February 510 2015, . 513 [IANA.URISchemes] 514 "Uniform Resource Identifier (URI) Schemes", February 515 2015, . 518 [ChromeCustomTab] 519 "Chrome Custom Tabs", July 2015, 520 . 523 [SFSafariViewController] 524 "SafariServices Changes", July 2015, . 528 [Android.AppLinks] 529 "App Links", July 2015, 530 . 533 Appendix A. Operating System Specific Implementation Details 535 Most of this document attempts to lay out best practices in an 536 generic manner, referencing technology available on most operating 537 systems. This non-normative section contains OS-specific 538 implementation details valid at the time of authorship. 540 It is expected that this OS-specific information will change, but 541 that the overall principles described in this document for using 542 external user-agents will remain valid for longer. 544 A.1. iOS Implementation Details 546 From iOS 9, apps can invoke the system browser without the user 547 leaving the app through SFSafariViewController 548 [SFSafariViewController], which implements the browser-view pattern. 549 This class has all the properties of the system browser, and is 550 considered an 'external user-agent', even though it is presented 551 within the host app. Regardless of whether the system browser is 552 opened, or SFSafariViewController, the return of the token goes 553 through the same system. 555 A.2. Android Implementation Details 557 Chrome 45 introduced the concept of Chrome Custom Tab 558 [ChromeCustomTab], which follows the browser-view pattern and allows 559 authentication without the user leaving the app. 561 The return of the token can go through the custom URI scheme or 562 claimed HTTPS URI (including those registered with the App Link 563 [Android.AppLinks] system), or the navigation events can be observed 564 by the host app. It is RECOMMENDED that the custom URI, or claimed 565 HTTPS URI options be used for better portability, to allow the user 566 to open the authorization request in the Chrome app, and to prevent 567 accidental observation of intermediate tokens on URI parameters. 569 Appendix B. Acknowledgements 571 The author would like to acknowledge the work of Marius Scurtescu, 572 and Ben Wiley Sittler whose design for using custom URI schemes in 573 native OAuth 2.0 clients formed the basis of Section 5.2. 575 The following individuals contributed ideas, feedback, and wording 576 that shaped and formed the final specification: 578 Naveen Agarwal, John Bradley, Brian Campbell, Adam Dawes, Ashish 579 Jain, Paul Madsen, Breno de Medeiros, Eric Sachs, Nat Sakimura, Steve 580 Wright. 582 Authors' Addresses 584 William Denniss 585 Google 586 1600 Amphitheatre Pkwy 587 Mountain View, CA 94043 588 USA 590 Phone: +1 650-253-0000 591 Email: wdenniss@google.com 592 URI: http://google.com/ 594 John Bradley 595 Ping Identity 597 Phone: +44 20 8133 3718 598 Email: ve7jtb@ve7jtb.com 599 URI: http://www.thread-safe.com/