idnits 2.17.1 draft-ietf-oauth-native-apps-02.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 02, 2016) is 2855 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 596, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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 3, 2017 Ping Identity 6 July 02, 2016 8 OAuth 2.0 for Native Apps 9 draft-ietf-oauth-native-apps-02 11 Abstract 13 OAuth 2.0 authorization requests from native apps should only be made 14 through external user-agents, primarily 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 3, 2017. 36 Copyright Notice 38 Copyright (c) 2016 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 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 55 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.1. Authorization Flow for Native Apps Using App-Claimed URI 58 Schemes . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 5. Using Inter-app URI Communication for OAuth . . . . . . . . . 6 60 6. Initiating the Authorization Request . . . . . . . . . . . . 6 61 7. Receiving the Authorization Response . . . . . . . . . . . . 7 62 7.1. App-declared Custom URI Scheme Redirection . . . . . . . 7 63 7.2. App-claimed HTTPS URI Redirection . . . . . . . . . . . . 9 64 7.3. Loopback URI Redirection . . . . . . . . . . . . . . . . 9 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 66 8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 10 67 8.2. Protecting the Authorization Code . . . . . . . . . . . . 11 68 8.3. Phishability of In-App Browser Tabs . . . . . . . . . . . 12 69 8.4. Limitations of Non-verifiable Clients . . . . . . . . . . 12 70 9. Other External User Agents . . . . . . . . . . . . . . . . . 12 71 10. Client Authentication . . . . . . . . . . . . . . . . . . . . 13 72 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 11.1. Normative References . . . . . . . . . . . . . . . . . . 13 74 11.2. Informative References . . . . . . . . . . . . . . . . . 13 75 Appendix A. Operating System Specific Implementation Details . . 15 76 A.1. iOS Implementation Details . . . . . . . . . . . . . . . 15 77 A.2. Android Implementation Details . . . . . . . . . . . . . 15 78 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 15 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 81 1. Introduction 83 The OAuth 2.0 [RFC6749] authorization framework, documents two 84 approaches in Section 9 for native apps to interact with the 85 authorization endpoint: via an embedded user-agent, or an external 86 user-agent. 88 This document recommends external user-agents like in-app browser 89 tabs as the only secure and usable choice for OAuth. It documents 90 how native apps can implement authorization flows with such agents, 91 and the additional requirements of authorization servers needed to 92 support such usage. 94 2. Notational Conventions 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in Key 99 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 100 these words are used without being spelled in uppercase then they are 101 to be interpreted with their normal natural language meanings. 103 3. Terminology 105 In addition to the terms defined in referenced specifications, this 106 document uses the following terms: 108 "app" A native application, such as one on a mobile device or 109 desktop operating system. 111 "app store" An ecommerce store where users can download and purchase 112 apps. Typically with quality-control measures to protect users 113 from malicious developers. 115 "authz" Abbreviation of "authorization". 117 "system browser" The operating system's default browser, typically 118 pre-installed as part of the operating system, or installed and 119 set as default by the user. 121 "browser tab" An open page of the system browser. Browser typically 122 have multiple "tabs" representing various open pages. 124 "in-app browser tab" A full page browser with limited navigation 125 capabilities that is displayed inside a host app, but retains the 126 full security properties and authentication state of the system 127 browser. Has different platform-specific product names, such as 128 SFSafariViewController on iOS 9, and Chrome Custom Tab on Android. 130 "Claimed HTTPS URL" Some platforms allow apps to claim a domain name 131 by hosting a file that proves the link between site and app. 132 Typically this means that URLs opened by the system will be opened 133 in the app instead of the browser. 135 "web-view" A web browser UI component that can be embedded in apps 136 to render web pages, used to create embedded user-agents. 138 "reverse domain name notation" A naming convention based on the 139 domain name system, but where where the domain components are 140 reversed, for example "app.example.com" becomes "com.example.app". 142 "custom URI scheme" A URI scheme (as defined by [RFC3986]) that the 143 app creates and registers with the OS (and is not a standard URI 144 scheme like "https:" or "tel:"). Requests to such a scheme 145 results in the app which registered it being launched by the OS. 146 For example, "myapp:", "com.example.myapp:" are both custom URI 147 schemes. 149 "inter-app communication" Communication between two apps on a 150 device. 152 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 154 4. Overview 156 At the time of writing, many native apps are still using web-views, a 157 type of embedded user-agent, for OAuth. That approach has multiple 158 drawbacks, including the client app being able to eavesdrop user 159 credentials, and is a suboptimal user experience as the 160 authentication session can't be shared, and users need to sign-in to 161 each app separately. 163 OAuth flows between a native app and the system browser (or another 164 external user-agent) are more secure, and take advantage of the 165 shared authentication state to enable single sign-on. 167 Inter-process communication, such as OAuth flows between a native app 168 and the system browser can be achieved through URI-based 169 communication. As this is exactly how OAuth works for web-based 170 OAuth flows between RP and IDP websites, OAuth can be used for native 171 app auth with very little modification. 173 4.1. Authorization Flow for Native Apps Using App-Claimed URI Schemes 174 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 175 | User Device | 176 | | 177 | +---------------------------+ | +-----------+ 178 | | | | (5) Authz Code | | 179 | | Client App |----------------------->| Token | 180 | | |<-----------------------| Endpoint | 181 | +---------------------------+ | (6) Access Token, | | 182 | | ^ | Refresh Token +-----------+ 183 | | | | 184 | | | | 185 | | (1) | (4) | 186 | | Authz | Authz | 187 | | Request | Code | 188 | | | | 189 | | | | 190 | v | | 191 | +---------------------------+ | +---------------+ 192 | | | | (2) Authz Request | | 193 | | Browser |--------------------->| Authorization | 194 | | |<---------------------| Endpoint | 195 | +---------------------------+ | (3) Authz Code | | 196 | | +---------------+ 197 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 199 Figure 1: Native App Authorization via External User-agent 201 Figure 1 illustrates the interaction of the native app with the 202 system browser to authorize the user via an external user-agent. 204 1) The client app opens a browser tab with the authorization request. 206 2) Authorization endpoint receives the authorization request, and 207 processes it, typically by authenticating the end-user and 208 obtaining an authorization decision. How the authorization server 209 authenticates the end-user is out of scope for this specification, 210 but can potentially involve chaining to other authentication 211 systems using various authentication protocols. 213 3) Authorization server issues an authorization code to the redirect 214 URI. 216 4) Client receives the authorization code from the redirect URI. 218 5) Client app presents the authorization code at the Token endpoint. 220 6) Token endpoint validates the authorization code and issues the 221 tokens requested. 223 5. Using Inter-app URI Communication for OAuth 225 Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 226 the authorization request and return the authorization response to 227 the requesting website, URIs can be used by native apps to initiate 228 the authorization request in the device's system browser and return 229 the response to the requesting native app. 231 By applying the same principles from the web to native apps, we gain 232 similar benefits like the usability of a single sign-on session, and 233 the security by a separate authentication context. It also reduces 234 the implementation complexity by reusing the same flows as the web, 235 and increases interoperability by relying on standards-based web 236 flows that are not specific to a particular platform. 238 It is RECOMMENDED that native apps use the URI-based communication 239 functionality of the operating system to perform OAuth flows in an 240 external user-agent, typically the system browser. 242 Some platforms support a browser feature known as in-app browser 243 tabs, where an app can present a tab of the browser within the app 244 context without switching apps, but still retain key benefits of the 245 browser such as a shared authentication state and security context. 246 On platforms where they are supported, it is RECOMMENDED for 247 usability reasons that apps use in-app browser tabs for the 248 Authorization Request. 250 It is possible to create an external user-agent for OAuth that is a 251 native app provided by the authorization server, as opposed to the 252 system browser. This approach shares a lot of similarity with using 253 the system browser as both use URIs for inter-app communication and 254 is able to provide a secure, shared authentication session, and thus 255 MAY be used for secure native OAuth, applying most of the techniques 256 described here. However it is NOT RECOMMENDED due to the increased 257 complexity and requirement for the user to have the AS app installed. 258 While much of the advice and security considerations are applicable 259 to such clients, they are out of scope for this specification. 261 6. Initiating the Authorization Request 263 The authorization request is created as per OAuth 2.0 [RFC6749], and 264 opened in the system browser. Where the operating system supports 265 in-app browser tabs, those should be preferred over switching to the 266 system browser, to improve usability. 268 The function of the redirect URI for a native app authorization 269 request is similar to that of a web-based authorization request. 270 Rather than returning the authorization code to the OAuth client's 271 server, it returns it to the native app. The various options for a 272 redirect URI that will return the code to the native app are 273 documented in Section 7. Any redirect URI that allows the app to 274 receive the URI and inspect its parameters is viable. 276 7. Receiving the Authorization Response 278 There are three main approaches to redirection URIs for native apps: 279 custom URI schemes, app-claimed HTTPS URI schemes, and loopback 280 redirects. 282 7.1. App-declared Custom URI Scheme Redirection 284 Most major mobile and desktop computing platforms support inter-app 285 communication via URIs by allowing apps to register custom URI 286 schemes. When the system browser or another app attempts to follow a 287 URI with a custom scheme, the app that registered it is launched to 288 handle the request. This document is only relevant on platforms that 289 support this pattern. 291 In particular, the custom URI scheme pattern is supported on the 292 mobile platforms Android [Android.URIScheme], iOS [iOS.URIScheme], 293 and Windows Phone [WindowsPhone.URIScheme]. Desktop operating 294 systems Windows [Windows.URIScheme] and OS X [OSX.URIScheme] also 295 support custom URI schemes. 297 7.1.1. Using Custom URI Schemes for Redirection 299 To perform an OAuth 2.0 Authorization Request on a supported 300 platform, the native app launches the system browser with a normal 301 OAuth 2.0 Authorization Request, but provides a redirection URI that 302 utilizes a custom URI scheme that is registered by the calling app. 304 When the authentication server completes the request, it redirects to 305 the client's redirection URI like it would any redirect URI, but as 306 the redirection URI uses a custom scheme, this results in the OS 307 launching the native app passing in the URI. The native app extracts 308 the code from the query parameters from the URI just like a web 309 client would, and exchanges the Authorization Code like a regular 310 OAuth 2.0 client. 312 7.1.2. Custom URI Scheme Namespace Considerations 314 When selecting which URI scheme to associate with the app, apps 315 SHOULD pick a scheme that is globally unique, and which they can 316 assert ownership over. 318 To avoid clashing with existing schemes in use, using a scheme that 319 follows the reverse domain name pattern applied to a domain under the 320 app publishers control is RECOMMENDED. Such a scheme can be based on 321 a domain they control, or the OAuth client identifier in cases where 322 the authorization server issues client identifiers that are also 323 valid DNS subdomains. The chosen scheme MUST NOT clash with any IANA 324 registered scheme [IANA.URISchemes]. You SHOULD also ensure that no 325 other app by the same publisher uses the same scheme. 327 Schemes using reverse domain name notation are hardened against 328 collision. They are unlikely to clash with an officially registered 329 scheme [IANA.URISchemes] or unregistered de-facto scheme, as these 330 generally don't include a period character, and are unlikely to match 331 your domain name in any case. They are guaranteed not to clash with 332 any OAuth client following these naming guidelines in full. 334 Some platforms use globally unique bundle or package names that 335 follow the reverse domain name notation pattern. In these cases, the 336 app SHOULD register that bundle id as the custom scheme. If an app 337 has a bundle id or package name that doesn't match a domain name 338 under the control of the app, the app SHOULD NOT register that as a 339 scheme, and instead create a URI scheme based off one of their domain 340 names. 342 For example, an app whose publisher owns the top level domain name 343 "example.com" can register "com.example.app:/" as their custom 344 scheme. An app whose authorization server issues client identifiers 345 that are also valid domain names, for example 346 "client1234.usercontent.idp.com", can use the reverse domain name 347 notation of that domain as the scheme, i.e. 348 "com.idp.usercontent.client1234:/". Each of these examples are URI 349 schemes which are likely to be unique, and where the publisher can 350 assert ownership. 352 As a counter-example, using a simple custom scheme like "myapp:/" is 353 not guaranteed to be unique and is NOT RECOMMENDED. 355 In addition to uniqueness, basing the URI scheme off a name that is 356 under the control of the app's publisher can help to prove ownership 357 in the event of a dispute where two apps register the same custom 358 scheme (such as if an app is acting maliciously). For example, if 359 two apps registered "com.example.app:", the true owner of 360 "example.com" could petition the app store operator to remove the 361 counterfeit app. This petition is harder to prove if a generic URI 362 scheme was chosen. 364 7.1.3. Registration of App Redirection URIs 366 As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the 367 authorization server SHOULD require the client to pre-register the 368 redirection URI. This remains true for app redirection URIs that use 369 custom schemes. 371 Additionally, authorization servers MAY request the inclusion of 372 other platform-specific information, such as the app package or 373 bundle name, or other information used to associate the app that may 374 be useful for verifying the calling app's identity, on operating 375 systems that support such functions. 377 Authorizations servers SHOULD support the ability for native apps to 378 register Redirection URIs that utilize custom URI schemes. 379 Authorization servers SHOULD enforce the recommendation in 380 Section 7.1.2 that apps follow naming guidelines for URI schemes. 382 7.2. App-claimed HTTPS URI Redirection 384 Some operating systems allow apps to claim HTTPS URLs of their 385 domains. When the browser sees such a claimed URL, instead of the 386 page being loaded in the browser, the native app is launched instead 387 with the URL given as input. 389 Where the operating environment provided app-claimed HTTPS URIs in a 390 usable fashion, these URIs should be used as the OAuth redirect, as 391 they allow the identity of the destination app to be guaranteed by 392 the operating system. 394 Apps on platforms that allow the user to disable this functionality, 395 present it in a user-unfriendly way, or lack it altogether MUST 396 fallback to using custom URI schemes. 398 The authorization server MUST allow the registration of HTTPS 399 redirect URIs for non-confidential native clients to support app- 400 claimed HTTPS redirect URIs. 402 7.3. Loopback URI Redirection 404 More applicable to desktop operating systems, some environments allow 405 apps to create a local HTTP listener on a random port, and receive 406 URI redirects that way. This is an acceptable redirect URI choice 407 for native apps on compatible platforms. 409 Authorization servers SHOULD support redirect URIs on the loopback IP 410 address and HTTP scheme, that is, redirect URIs beginning with 411 http://127.0.0.1[:port]/, http://::1[:port]/, and 412 http://localhost[:port]/. Authorization servers supporting this class 413 of redirect URI MUST allow the client to specify a port of their 414 choice, and SHOULD allow the client to use an arbitrary path 415 component. 417 While both the loopback IP and localhost variants SHOULD be supported 418 by the authorization server for completeness, it is RECOMMENDED that 419 apps primarily use the loopback IP variant, as it is less susceptible 420 to misconfigured routing and client side firewalls Note that the HTTP 421 scheme is acceptable for this category of redirect URIs, as the 422 request never leaves the device. 424 8. Security Considerations 426 8.1. Embedded User-Agents 428 Embedded user-agents, commonly implemented with web-views, are an 429 alternative method for authorizing native apps. They are however 430 unsafe for use by third-parties by definition. They involve the user 431 signing in with their full login credentials, only to have them 432 downscoped to less powerful OAuth credentials. 434 Even when used by trusted first-party apps, embedded user-agents 435 violate the principle of least privilege by obtaining more powerful 436 credentials than they need, potentially increasing the attack 437 surface. 439 In typical web-view based implementations of embedded user-agents, 440 the host application can: log every keystroke entered in the form to 441 capture usernames and passwords; automatically submit forms and 442 bypass user-consent; copy session cookies and use them to perform 443 authenticated actions as the user. 445 Encouraging users to enter credentials in an embedded web-view 446 without the usual address bar and other identity features that 447 browsers have makes it impossible for the user to know if they are 448 signing in to the legitimate site, and even when they are, it trains 449 them that it's OK to enter credentials without validating the site 450 first. 452 Aside from the security concerns, web-views do not share the 453 authentication state with other apps or the system browser, requiring 454 the user to login for every authorization request and leading to a 455 poor user experience. 457 Due to the above, use of embedded user-agents is NOT RECOMMENDED, 458 except where a trusted first-party app acts as the external user- 459 agent for other apps, or provides single sign-on for multiple first- 460 party apps. 462 Authorization servers SHOULD consider taking steps to detect and 463 block logins via embedded user-agents that are not their own, where 464 possible. 466 8.2. Protecting the Authorization Code 468 A limitation of custom URI schemes is that multiple apps can 469 typically register the same scheme, which makes it indeterminate as 470 to which app will receive the Authorization Code Grant. This is not 471 an issue for HTTPS redirection URIs (i.e. standard web URLs) due to 472 the fact the HTTPS URI scheme is enforced by the authority (as 473 defined by [RFC3986]), the domain name system, which does not allow 474 multiple entities to own the same domain. 476 If multiple apps register the same scheme, it is possible that the 477 authorization code will be sent to the wrong app (generally the 478 operating system makes no guarantee of which app will handle the URI 479 when multiple register the same scheme). PKCE [RFC7636] details how 480 this limitation can be used to execute a code interception attack 481 (see Figure 1). This attack vector applies to public clients 482 (clients that are unable to maintain a client secret) which is 483 typical of most native apps. 485 While Section 7.1.2 details ways that this can be mitigated through 486 policy enforcement (through being able to report and have removed any 487 offending apps), we can also protect the authorization code grant 488 from being used in cases where it was intercepted. 490 The Proof Key for Code Exchange by OAuth Public Clients (PKCE 491 [RFC7636]) standard was created specifically to mitigate against this 492 attack. It is a Proof of Possession extension to OAuth 2.0 that 493 protects the code grant from being used if it is intercepted. It 494 achieves this by having the client generate a secret verifier which 495 it passes in the initial authorization request, and which it must 496 present later when redeeming the authorization code grant. An app 497 that intercepted the authorization code would not be in possession of 498 this secret, rendering the code useless. 500 Both the client and the Authorization Server MUST support PKCE 501 [RFC7636] to use custom URI schemes, or loopback redirects. 502 Authorization Servers SHOULD reject authorization requests using a 503 custom scheme, or localhost as part of the redirection URI if the 504 required PKCE parameters are not present, returning the error message 505 as defined in Section 4.4.1 of PKCE [RFC7636]. It is RECOMMENDED to 506 use PKCE [RFC7636] for app-claimed HTTPS redirect URIs, even though 507 these are not generally subject to interception, to protect against 508 attacks on inter-app communication. 510 8.3. Phishability of In-App Browser Tabs 512 While in-app browser tabs provide a secure authentication context, as 513 the user initiates the flow from a native app, it is possible for 514 that native app to completely fake an in-app browser tab. 516 This can't be prevented directly - once the user is in the native 517 app, that app is fully in control of what it can render, however 518 there are several mitigating factors. 520 Importantly, such an attack that uses a web-view to fake an in-app 521 browser tab will always start with no authentication state. If all 522 native apps use the techniques described in this best practice, users 523 will not need to sign-in frequently and thus should be suspicious of 524 any sign-in request when they should have already been signed-in. 526 This is true even for authorization servers that require frequent or 527 occasional re-authentication, as such servers can preserve some user 528 identifiable information from the old request, like the email address 529 or avatar. To help mitigate against phishing, it is RECOMMENDED to 530 show the user some hint that they were previously logged in, as an 531 attacking app would not be capable of doing this. 533 Users who are particularly concerned about their security may also 534 take the additional step of opening the request in the system browser 535 from the in-app browser tab, and completing the authorization there, 536 as most implementations of the in-app browser tab pattern offer such 537 functionality. This is not expected to be common user behavior, 538 however. 540 8.4. Limitations of Non-verifiable Clients 542 As stated in Section 10.2 of RFC 6749, the authorization server 543 SHOULD NOT process authorization requests automatically without user 544 consent or interaction, except when the identity of the client can be 545 assured. Measures such as claimed HTTPS redirects can be used by 546 native apps to prove their identity to the authorization server, and 547 some operating systems may offer alternative platform-specific 548 identity features which may be used, as appropriate. 550 9. Other External User Agents 552 This best practice recommends a particular type of external user- 553 agent, the system browser. Other external user-agents patterns may 554 also be viable for secure and usable OAuth. This document makes no 555 comment on those patterns. 557 10. Client Authentication 559 Secrets that are statically included as part of an app distributed to 560 multiple users should not be treated as confidential secrets, as one 561 user may inspect their copy and learn the secret of all users. For 562 this reason it is NOT RECOMMENDED for authorization servers to 563 require client authentication of native apps using a secret shared by 564 multiple installs of the app, as this serves little value beyond 565 client identification which is already provided by the client_id 566 request parameter. If an authorization server requires a client 567 secret for native apps, it MUST NOT assume that it is actually 568 secret, unless some method is being used to dynamically provision a 569 unique secret to each installation. 571 11. References 573 11.1. Normative References 575 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 576 RFC 6749, DOI 10.17487/RFC6749, October 2012, 577 . 579 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 580 for Code Exchange by OAuth Public Clients", RFC 7636, 581 DOI 10.17487/RFC7636, September 2015, 582 . 584 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 585 Requirement Levels", BCP 14, RFC 2119, 586 DOI 10.17487/RFC2119, March 1997, 587 . 589 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 590 Resource Identifier (URI): Generic Syntax", STD 66, 591 RFC 3986, DOI 10.17487/RFC3986, January 2005, 592 . 594 11.2. Informative References 596 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 597 Threat Model and Security Considerations", RFC 6819, 598 DOI 10.17487/RFC6819, January 2013, 599 . 601 [iOS.URIScheme] 602 "Inter-App Communication", February 2015, . 607 [OSX.URIScheme] 608 "Launch Services Concepts", February 2015, . 613 [Android.URIScheme] 614 "Intents and Intent Filters", February 2015, 615 . 618 [WindowsPhone.URIScheme] 619 "Auto-launching apps using file and URI associations for 620 Windows Phone 8", February 2015, 621 . 624 [Windows.URIScheme] 625 "Registering an Application to a URI Scheme", February 626 2015, . 629 [IANA.URISchemes] 630 "Uniform Resource Identifier (URI) Schemes", February 631 2015, . 634 [ChromeCustomTab] 635 "Chrome Custom Tabs", July 2015, 636 . 639 [SFSafariViewController] 640 "SafariServices Changes", July 2015, . 644 [Android.AppLinks] 645 "App Links", July 2015, 646 . 649 Appendix A. Operating System Specific Implementation Details 651 Most of this document attempts to lay out best practices in an 652 generic manner, referencing technology available on most operating 653 systems. This non-normative section contains OS-specific 654 implementation details that are accurate at the time of authorship. 656 It is expected that this OS-specific information will change, but 657 that the overall principles described in this document for using 658 external user-agents will remain valid. 660 A.1. iOS Implementation Details 662 From iOS 9, apps can invoke the system browser without the user 663 leaving the app through SFSafariViewController 664 [SFSafariViewController], which implements the browser-view pattern. 665 This class has all the properties of the system browser, and is 666 considered an 'external user-agent', even though it is presented 667 within the host app. Regardless of whether the system browser is 668 opened, or SFSafariViewController, the return of the token goes 669 through the same system. 671 A.2. Android Implementation Details 673 Chrome 45 introduced the concept of Chrome Custom Tab 674 [ChromeCustomTab], which follows the browser-view pattern and allows 675 authentication without the user leaving the app. 677 The return of the token can go through the custom URI scheme or 678 claimed HTTPS URI (including those registered with the App Link 679 [Android.AppLinks] system), or the navigation events can be observed 680 by the host app. It is RECOMMENDED that the custom URI, or claimed 681 HTTPS URI options be used for better portability, to allow the user 682 to open the authorization request in the Chrome app, and to prevent 683 accidental observation of intermediate tokens on URI parameters. 685 At the time of writing, Android does allow apps to claim HTTPs links 686 (App Links), but not in a way that is usable for OAuth, the native 687 app is only opened if the intent is fired from outside the browser. 689 Appendix B. Acknowledgements 691 The author would like to acknowledge the work of Marius Scurtescu, 692 and Ben Wiley Sittler whose design for using custom URI schemes in 693 native OAuth 2.0 clients formed the basis of Section 7.1. 695 The following individuals contributed ideas, feedback, and wording 696 that shaped and formed the final specification: 698 Naveen Agarwal, John Bradley, Brian Campbell, Adam Dawes, Hannes 699 Tschofenig, Ashish Jain, Paul Madsen, Breno de Medeiros, Eric Sachs, 700 Nat Sakimura, Steve Wright, Erik Wahlstrom, Andy Zmolek, Sudhi 701 Umarji. 703 Authors' Addresses 705 William Denniss 706 Google 707 1600 Amphitheatre Pkwy 708 Mountain View, CA 94043 709 USA 711 Phone: +1 650-253-0000 712 Email: wdenniss@google.com 713 URI: http://google.com/ 715 John Bradley 716 Ping Identity 718 Phone: +1 202-630-5272 719 Email: ve7jtb@ve7jtb.com 720 URI: http://www.thread-safe.com/