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