idnits 2.17.1 draft-ietf-oauth-native-apps-11.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 19, 2017) is 2505 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) No issues found here. Summary: 0 errors (**), 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: November 20, 2017 Ping Identity 6 May 19, 2017 8 OAuth 2.0 for Native Apps 9 draft-ietf-oauth-native-apps-11 11 Abstract 13 OAuth 2.0 authorization requests from native apps should only be made 14 through external user-agents, primarily the user's 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 November 20, 2017. 36 Copyright Notice 38 Copyright (c) 2017 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 the Browser . . 5 58 5. Using Inter-app URI Communication for OAuth . . . . . . . . . 6 59 6. Initiating the Authorization Request from a Native App . . . 6 60 7. Receiving the Authorization Response in a Native App . . . . 7 61 7.1. Private-use URI Scheme Redirection . . . . . . . . . . . 8 62 7.2. Claimed HTTPS URI Redirection . . . . . . . . . . . . . . 9 63 7.3. Loopback Interface Redirection . . . . . . . . . . . . . 9 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 65 8.1. Protecting the Authorization Code . . . . . . . . . . . . 10 66 8.2. OAuth Implicit Grant Authorization Flow . . . . . . . . . 11 67 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11 68 8.4. Registration of Native App Clients . . . . . . . . . . . 11 69 8.5. Client Authentication . . . . . . . . . . . . . . . . . . 12 70 8.6. Client Impersonation . . . . . . . . . . . . . . . . . . 12 71 8.7. Phishability of In-App Browser Tabs . . . . . . . . . . . 13 72 8.8. Cross-App Request Forgery Protections . . . . . . . . . . 13 73 8.9. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 74 8.10. Non-Browser External User-Agents . . . . . . . . . . . . 14 75 8.11. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 10.1. Normative References . . . . . . . . . . . . . . . . . . 15 79 10.2. Informative References . . . . . . . . . . . . . . . . . 16 80 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16 81 Appendix B. Operating System Specific Implementation Details . . 17 82 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 17 83 B.2. Android Implementation Details . . . . . . . . . . . . . 18 84 B.3. Windows Implementation Details . . . . . . . . . . . . . 18 85 B.4. macOS Implementation Details . . . . . . . . . . . . . . 19 86 B.5. Linux Implementation Details . . . . . . . . . . . . . . 19 87 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 90 1. Introduction 92 The OAuth 2.0 [RFC6749] authorization framework documents two 93 approaches in Section 9 for native apps to interact with the 94 authorization endpoint: an embedded user-agent, and an external user- 95 agent. 97 This best current practice requires that only external user-agents 98 like the browser are used for OAuth by native apps. It documents how 99 native apps can implement authorization flows using the browser as 100 the preferred external user-agent, and the requirements for 101 authorization servers to support such usage. 103 This practice is also known as the AppAuth pattern, in reference to 104 open source libraries that implement it. 106 2. Notational Conventions 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 110 "OPTIONAL" in this document are to be interpreted as described in Key 111 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 112 these words are used without being spelled in uppercase then they are 113 to be interpreted with their normal natural language meanings. 115 3. Terminology 117 In addition to the terms defined in referenced specifications, this 118 document uses the following terms: 120 "native app" An app or application that is installed by the user to 121 their device, as distinct from a web app that runs in the browser 122 context only. Apps implemented using web-based technology but 123 distributed as a native app, so-called hybrid apps, are considered 124 equivalent to native apps for the purpose of this specification. 126 "app" In this document, "app" means a "native app" unless further 127 specified. 129 "app store" An ecommerce store where users can download and purchase 130 apps. 132 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 134 "external user-agent" A user-agent capable of handling the 135 authorization request that is a separate entity or security domain 136 to the native app making the request (such as a browser), such 137 that the app cannot access the cookie storage, nor inspect or 138 modify page content. 140 "embedded user-agent" A user-agent hosted inside the native app 141 itself (such as via a web-view), with which the app has control 142 over to the extent it is capable of accessing the cookie storage 143 and/or modifying the page content. 145 "browser" The default application launched by the operating system 146 to handle "http" and "https" scheme URI content. 148 "in-app browser tab" A programmatic instantiation of the browser 149 that is displayed inside a host app, but retains the full security 150 properties and authentication state of the browser. Has different 151 platform-specific product names, such as SFSafariViewController on 152 iOS, and Custom Tabs on Android. 154 "inter-app communication" Communication between two apps on a 155 device. 157 "claimed HTTPS URI" Some platforms allow apps to claim a HTTPS 158 scheme URI after proving ownership of the domain name. URIs 159 claimed in such a way are then opened in the app instead of the 160 browser. 162 "private-use URI scheme" A private-use URI scheme defined by the app 163 and registered with the operating system. URI requests to such 164 schemes trigger the app which registered it to be launched to 165 handle the request. 167 "web-view" A web browser UI component that can be embedded in apps 168 to render web pages, used to create embedded user-agents. 170 "reverse domain name notation" A naming convention based on the 171 domain name system, but where the domain components are reversed, 172 for example "app.example.com" becomes "com.example.app". 174 4. Overview 176 The best current practice for authorizing users in native apps is to 177 perform the OAuth authorization request in an external user-agent 178 (typically the browser), rather than an embedded user-agent (such as 179 one implemented with web-views). 181 Previously it was common for native apps to use embedded user-agents 182 (commonly implemented with web-views) for OAuth authorization 183 requests. That approach has many drawbacks, including the host app 184 being able to copy user credentials and cookies, and the user needing 185 to authenticate from scratch in each app. See Section 8.11 for a 186 deeper analysis of using embedded user-agents for OAuth. 188 Native app authorization requests that use the browser are more 189 secure and can take advantage of the user's authentication state. 190 Being able to use the existing authentication session in the browser 191 enables single sign-on, as users don't need to authenticate to the 192 authorization server each time they use a new app (unless required by 193 authorization server policy). 195 Supporting authorization flows between a native app and the browser 196 is possible without changing the OAuth protocol itself, as the 197 authorization request and response are already defined in terms of 198 URIs, which encompasses URIs that can be used for inter-app 199 communication. Some OAuth server implementations that assume all 200 clients are confidential web-clients will need to add an 201 understanding of public native app clients and the types of redirect 202 URIs they use to support this best practice. 204 4.1. Authorization Flow for Native Apps Using the Browser 206 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 207 | User Device | 208 | | 209 | +---------------------------+ | +-----------+ 210 | | | | (5) Authz Code | | 211 | | Client App |----------------------->| Token | 212 | | |<-----------------------| Endpoint | 213 | +---------------------------+ | (6) Access Token, | | 214 | | ^ | Refresh Token +-----------+ 215 | | | | 216 | | | | 217 | | (1) | (4) | 218 | | Authz | Authz | 219 | | Request | Code | 220 | | | | 221 | | | | 222 | v | | 223 | +---------------------------+ | +---------------+ 224 | | | | (2) Authz Request | | 225 | | Browser |--------------------->| Authorization | 226 | | |<---------------------| Endpoint | 227 | +---------------------------+ | (3) Authz Code | | 228 | | +---------------+ 229 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 231 Figure 1: Native App Authorization via External User-agent 233 Figure 1 illustrates the interaction of the native app with a browser 234 external user-agent to authorize the user. 236 (1) The client app opens a browser tab with the authorization 237 request. 239 (2) Authorization endpoint receives the authorization request, 240 authenticates the user and obtains authorization. 241 Authenticating the user may involve chaining to other 242 authentication systems. 244 (3) Authorization server issues an authorization code to the 245 redirect URI. 247 (4) Client receives the authorization code from the redirect URI. 249 (5) Client app presents the authorization code at the token 250 endpoint. 252 (6) Token endpoint validates the authorization code and issues the 253 tokens requested. 255 5. Using Inter-app URI Communication for OAuth 257 Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 258 the authorization request and return the authorization response to 259 the requesting website, URIs can be used by native apps to initiate 260 the authorization request in the device's browser and return the 261 response to the requesting native app. 263 By adopting the same methods used on the web for OAuth, benefits seen 264 in the web context like the usability of a single sign-on session and 265 the security of a separate authentication context are likewise gained 266 in the native app context. Re-using the same approach also reduces 267 the implementation complexity and increases interoperability by 268 relying on standards-based web flows that are not specific to a 269 particular platform. 271 To conform to this best practice, native apps MUST use an external 272 user-agent to perform OAuth authentication requests. This is 273 achieved by opening the authorization request in the browser 274 (detailed in Section 6), and using a redirect URI that will return 275 the authorization response back to the native app, as defined in 276 Section 7. 278 6. Initiating the Authorization Request from a Native App 280 Native apps needing user authorization create an authorization 281 request URI with the authorization code grant type per Section 4.1 of 282 OAuth 2.0 [RFC6749], using a redirect URI capable of being received 283 by the native app. 285 The function of the redirect URI for a native app authorization 286 request is similar to that of a web-based authorization request. 288 Rather than returning the authorization response to the OAuth 289 client's server, the redirect URI used by a native app returns the 290 response to the app. Several options for a redirect URI that will 291 return the authorization response to the native app in different 292 platforms are documented in Section 7. Any redirect URI that allows 293 the app to receive the URI and inspect its parameters is viable. 295 Public native app clients MUST implement the Proof Key for Code 296 Exchange (PKCE [RFC7636]) extension to OAuth, and authorization 297 servers MUST support PKCE for such clients, for the reasons detailed 298 in Section 8.1. 300 After constructing the authorization request URI, the app uses 301 platform-specific APIs to open the URI in an external user-agent. 302 Typically the external user-agent used is the default browser, that 303 is, the application configured for handling "http" and "https" scheme 304 URIs on the system, but different browser selection criteria and 305 other categories of external user-agents MAY be used. 307 This best practice focuses on the browser as the RECOMMENDED external 308 user-agent for native apps. An external user-agent designed 309 specifically for processing authorization requests capable of 310 processing the request and redirect URIs in the same way MAY also be 311 used. Other external user-agents, such as a native app provided by 312 the authorization server may meet the criteria set out in this best 313 practice, including using the same redirection URI properties, but 314 their use is out of scope for this specification. 316 Some platforms support a browser feature known as in-app browser 317 tabs, where an app can present a tab of the browser within the app 318 context without switching apps, but still retain key benefits of the 319 browser such as a shared authentication state and security context. 320 On platforms where they are supported, it is RECOMMENDED for 321 usability reasons that apps use in-app browser tabs for the 322 authorization request. 324 7. Receiving the Authorization Response in a Native App 326 There are several redirect URI options available to native apps for 327 receiving the authorization response from the browser, the 328 availability and user experience of which varies by platform. 330 To fully support this best practice, authorization servers MUST 331 support the following three redirect URI options. Native apps MAY 332 use whichever redirect option suits their needs best, taking into 333 account platform specific implementation details. 335 7.1. Private-use URI Scheme Redirection 337 Many mobile and desktop computing platforms support inter-app 338 communication via URIs by allowing apps to register private-use URI 339 schemes (sometimes colloquially referred to as custom URL schemes) 340 like "com.example.app". When the browser or another app attempts to 341 load a URI with a custom scheme, the app that registered it is 342 launched to handle the request. 344 To perform an OAuth 2.0 authorization request with a private-use URI 345 scheme redirect, the native app launches the browser with a standard 346 authorization request, but one where the redirection URI utilizes a 347 custom URI scheme it registered with the operating system. 349 When choosing a URI scheme to associate with the app, apps MUST use a 350 URI scheme based on a domain name under their control, expressed in 351 reverse order, as recommended by Section 3.8 of [RFC7595] for 352 private-use URI schemes. 354 For example, an app that controls the domain name "app.example.com" 355 can use "com.example.app" as their scheme. Some authorization 356 servers assign client identifiers based on domain names, for example 357 "client1234.usercontent.example.net", which can also be used as the 358 domain name for the scheme when reversed in the same manner. A 359 scheme such as "myapp" however would not meet this requirement, as it 360 is not based on a domain name. 362 Care must be taken when there are multiple apps by the same publisher 363 that each scheme is unique within that group. On platforms that use 364 app identifiers that are also based on reverse order domain names, 365 those can be reused as the private-use URI scheme for the OAuth 366 redirect to help avoid this problem. 368 Following the requirements of [RFC3986] Section 3.2, as there is no 369 naming authority for private-use URI scheme redirects, only a single 370 slash ("/") appears after the scheme component. A complete example 371 of a redirect URI utilizing a private-use URI scheme: 373 com.example.app:/oauth2redirect/example-provider 375 When the authentication server completes the request, it redirects to 376 the client's redirection URI as it would normally. As the 377 redirection URI uses a custom scheme it results in the operating 378 system launching the native app, passing in the URI as a launch 379 parameter. The native app then processes the authorization response 380 like normal. 382 7.2. Claimed HTTPS URI Redirection 384 Some operating systems allow apps to claim HTTPS scheme URIs in 385 domains they control. When the browser encounters a claimed URI, 386 instead of the page being loaded in the browser, the native app is 387 launched with the URI supplied as a launch parameter. 389 Such URIs can be used as OAuth redirect URIs. They are 390 indistinguishable from OAuth redirects of web-based clients. An 391 example is: 393 https://app.example.com/oauth2redirect/example-provider 395 App-claimed HTTPS redirect URIs have some advantages in that the 396 identity of the destination app is guaranteed by the operating 397 system. For this reason, they SHOULD be used in preference to the 398 other redirect options for native apps where possible. 400 Claimed HTTPS redirect URIs function as normal HTTPS redirects from 401 the perspective of the authorization server, though as stated in 402 Section 8.4, it is REQUIRED that the authorization server is able to 403 distinguish between public native app clients that use app-claimed 404 HTTPS redirect URIs and confidential web clients. 406 7.3. Loopback Interface Redirection 408 Native apps that are able to open a port on the loopback network 409 interface without needing special permissions (typically, those on 410 desktop operating systems) can use the loopback interface to receive 411 the OAuth redirect. 413 Loopback redirect URIs use the HTTP scheme and are constructed with 414 the loopback IP literal and whatever port the client is listening on. 415 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 416 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 417 IPv4 loopback interface with a randomly assigned port: 419 http://127.0.0.1:50719/oauth2redirect/example-provider 421 An example redirect using the IPv6 loopback interface with a randomly 422 assigned port: 424 http://[::1]:61023/oauth2redirect/example-provider 426 The authorization server MUST allow any port to be specified at the 427 time of the request for loopback IP redirect URIs, to accommodate 428 clients that obtain an available ephemeral port from the operating 429 system at the time of the request. 431 Clients SHOULD NOT assume the device supports a particular version of 432 the Internet Protocol. It is RECOMMENDED that clients attempt to 433 bind to the loopback interface using both IPv4 and IPv6, and use 434 whichever is available. 436 8. Security Considerations 438 8.1. Protecting the Authorization Code 440 The redirect URI options documented in Section 7 share the benefit 441 that only a native app on the same device can receive the 442 authorization code which limits the attack surface, however code 443 interception by a native app other than the intended app may still be 444 possible. 446 A limitation of using private-use URI schemes for redirect URIs is 447 that multiple apps can typically register the same scheme, which 448 makes it indeterminate as to which app will receive the Authorization 449 Code. PKCE [RFC7636] details how this limitation can be used to 450 execute a code interception attack (see Figure 1). 452 Loopback IP based redirect URIs may be susceptible to interception by 453 other apps listening on the same loopback interface. 455 As most forms of inter-app URI-based communication send data over 456 insecure local channels, eavesdropping and interception of the 457 authorization response is a risk for native apps. App-claimed HTTPS 458 redirects are hardened against this type of attack due to the 459 presence of the URI authority, but they are still public clients and 460 the URI is still transmitted over local channels with unknown 461 security properties. 463 The Proof Key for Code Exchange by OAuth Public Clients (PKCE 464 [RFC7636]) standard was created specifically to mitigate against this 465 attack. It is a Proof of Possession extension to OAuth 2.0 that 466 protects the code grant from being used if it is intercepted. It 467 achieves this by having the client generate a secret verifier, a hash 468 of which it passes in the initial authorization request, and which it 469 must present in full when redeeming the authorization code grant. An 470 app that intercepted the authorization code would not be in 471 possession of this secret, rendering the code useless. 473 Section 8.1 requires that both clients and servers use PKCE for 474 public native app clients. Authorization servers SHOULD reject 475 authorization requests from native apps that don't use PKCE by 476 returning an error message as defined in Section 4.4.1 of PKCE 477 [RFC7636]. 479 8.2. OAuth Implicit Grant Authorization Flow 481 The OAuth 2.0 implicit grant authorization flow as defined in 482 Section 4.2 of OAuth 2.0 [RFC6749] generally works with the practice 483 of performing the authorization request in the browser, and receiving 484 the authorization response via URI-based inter-app communication. 485 However, as the Implicit Flow cannot be protected by PKCE (which is a 486 required in Section 8.1), the use of the Implicit Flow with native 487 apps is NOT RECOMMENDED. 489 Tokens granted via the implicit flow also cannot be refreshed without 490 user interaction, making the authorization code grant flow - which 491 can issue refresh tokens - the more practical option for native app 492 authorizations that require refreshing. 494 8.3. Loopback Redirect Considerations 496 Loopback interface redirect URIs use the "http" scheme (i.e., without 497 TLS). This is acceptable for loopback interface redirect URIs as the 498 HTTP request never leaves the device. 500 Clients should open the network port only when starting the 501 authorization request, and close it once the response is returned. 503 Clients should listen on the loopback network interface only, to 504 avoid interference by other network actors. 506 While redirect URIs using localhost (i.e., 507 "http://localhost:{port}/") function similarly to loopback IP 508 redirects described in Section 7.3, the use of "localhost" is NOT 509 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 510 rather than localhost avoids inadvertently listening on network 511 interfaces other than the loopback interface. It is also less 512 susceptible to client side firewalls, and misconfigured host name 513 resolution on the user's device. 515 8.4. Registration of Native App Clients 517 Native apps, except when using a mechanism like Dynamic Client 518 Registration [RFC7591] to provision per-instance secrets, are 519 classified as public clients, as defined by Section 2.1 of OAuth 2.0 520 [RFC6749] and MUST be registered with the authorization server as 521 such. Authorization servers MUST record the client type in the 522 client registration details in order to identify and process requests 523 accordingly. 525 Authorization servers MUST require clients to register their complete 526 redirect URI (including the path component), and reject authorization 527 requests that specify a redirect URI that doesn't exactly match the 528 one that was registered, with the exception of loopback redirects, 529 where an exact match is required except for the port URI component. 531 For private-use URI scheme based redirects, authorization servers 532 SHOULD enforce the requirement in Section 7.1 that clients use 533 reverse domain name based schemes. At a minimum, any scheme that 534 doesn't contain a period character ("."), SHOULD be rejected. 536 In addition to the collision resistant properties, requiring a URI 537 scheme based on a domain name that is under the control of the app 538 can help to prove ownership in the event of a dispute where two apps 539 claim the same private-use URI scheme (where one app is acting 540 maliciously). For example, if two apps claimed "com.example.app", 541 the owner of "example.com" could petition the app store operator to 542 remove the counterfeit app. Such a petition is harder to prove if a 543 generic URI scheme was used. 545 Authorization servers MAY request the inclusion of other platform- 546 specific information, such as the app package or bundle name, or 547 other information used to associate the app that may be useful for 548 verifying the calling app's identity, on operating systems that 549 support such functions. 551 8.5. Client Authentication 553 Secrets that are statically included as part of an app distributed to 554 multiple users should not be treated as confidential secrets, as one 555 user may inspect their copy and learn the shared secret. For this 556 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 557 RECOMMENDED for authorization servers to require client 558 authentication of public native apps clients using a shared secret, 559 as this serves little value beyond client identification which is 560 already provided by the "client_id" request parameter. 562 Authorization servers that still require a statically included shared 563 secret for native app clients MUST treat the client as a public 564 client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not 565 accept the secret as proof of the client's identity. Without 566 additional measures, such clients are subject to client impersonation 567 (see Section 8.6). 569 8.6. Client Impersonation 571 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 572 server SHOULD NOT process authorization requests automatically 573 without user consent or interaction, except when the identity of the 574 client can be assured. This includes the case where the user has 575 previously approved an authorization request for a given client id - 576 unless the identity of the client can be proven, the request SHOULD 577 be processed as if no previous request had been approved. 579 Measures such as claimed HTTPS redirects MAY be accepted by 580 authorization servers as identity proof. Some operating systems may 581 offer alternative platform-specific identity features which MAY be 582 accepted, as appropriate. 584 8.7. Phishability of In-App Browser Tabs 586 While in-app browser tabs provide a secure authentication context, as 587 the user initiates the flow from a native app, it is possible for 588 that native app to completely fake an in-app browser tab. 590 This can't be prevented directly - once the user is in the native 591 app, that app is fully in control of what it can render - however 592 there are several mitigating factors. 594 Importantly, such an attack that uses a web-view to fake an in-app 595 browser tab will always start with no authentication state. If all 596 native apps use the techniques described in this best practice, users 597 will not need to sign-in frequently and thus should be suspicious of 598 any sign-in request when they should have already been signed-in. 600 This is the case even for authorization servers that require 601 occasional or frequent re-authentication, as such servers can 602 preserve some user identifiable information from the old session, 603 such as the email address or profile picture and display that 604 information during re-authentication. 606 Users who are particularly concerned about their security may also 607 take the additional step of opening the request in the browser from 608 the in-app browser tab, and completing the authorization there, as 609 most implementations of the in-app browser tab pattern offer such 610 functionality. 612 8.8. Cross-App Request Forgery Protections 614 Section 5.3.5 of [RFC6819] recommends using the "state" parameter to 615 link client requests and responses to prevent CSRF (Cross Site 616 Request Forgery) attacks. 618 To mitigate CSRF style attacks using inter-app URI communication, it 619 is similarly RECOMMENDED for native apps to include a high entropy 620 secure random number in the "state" parameter of the authorization 621 request, and reject any incoming authorization responses without a 622 state value that matches a pending outgoing authorization request. 624 8.9. Authorization Server Mix-Up Mitigation 626 To protect against a compromised or malicious authorization server 627 attacking another authorization server used by the same app, it is 628 REQUIRED that a unique redirect URI is used for each authorization 629 server used by the app (for example, by varying the path component), 630 and that authorization responses are rejected if the redirect URI 631 they were received on doesn't match the redirect URI in a outgoing 632 authorization request. 634 The native app MUST store the redirect URI used in the authorization 635 request with the authorization session data (i.e., along with "state" 636 and other related data), and MUST verify that the URI on which the 637 authorization response was received exactly matches it. 639 The requirements of Section 8.4 that authorization servers reject 640 requests with URIs that don't match what was registered are also 641 required to prevent such attacks. 643 8.10. Non-Browser External User-Agents 645 This best practice recommends a particular type of external user- 646 agent, the user's browser. Other external user-agent patterns may 647 also be viable for secure and usable OAuth. This document makes no 648 comment on those patterns. 650 8.11. Embedded User-Agents 652 OAuth 2.0 [RFC6749] Section 9 documents two approaches for native 653 apps to interact with the authorization endpoint. This best current 654 practice requires that native apps MUST NOT use embedded user-agents 655 to perform authorization requests, and allows that authorization 656 endpoints MAY take steps to detect and block authorization requests 657 in embedded user-agents. The security considerations for these 658 requirements are detailed herein. 660 Embedded user-agents are an alternative method for authorizing native 661 apps. These embedded user agents are unsafe for use by third-parties 662 to the authorization server by definition, as the app that hosts the 663 embedded user-agent can access the user's full authentication 664 credential, not just the OAuth authorization grant that was intended 665 for the app. 667 In typical web-view based implementations of embedded user-agents, 668 the host application can: log every keystroke entered in the form to 669 capture usernames and passwords; automatically submit forms and 670 bypass user-consent; copy session cookies and use them to perform 671 authenticated actions as the user. 673 Even when used by trusted apps belonging to the same party as the 674 authorization server, embedded user-agents violate the principle of 675 least privilege by having access to more powerful credentials than 676 they need, potentially increasing the attack surface. 678 Encouraging users to enter credentials in an embedded user-agent 679 without the usual address bar and visible certificate validation 680 features that browsers have makes it impossible for the user to know 681 if they are signing in to the legitimate site, and even when they 682 are, it trains them that it's OK to enter credentials without 683 validating the site first. 685 Aside from the security concerns, embedded user-agents do not share 686 the authentication state with other apps or the browser, requiring 687 the user to login for every authorization request which is often 688 considered an inferior user experience. 690 9. IANA Considerations 692 [RFC Editor: please do NOT remove this section.] 694 This document has no IANA actions. 696 Section 7.1 specifies how private-use URI schemes are used for inter- 697 app communication in OAuth protocol flows. This document requires in 698 Section 7.1 that such schemes are based on domain names owned or 699 assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per 700 Section 6 of [RFC7595], registration of domain based URI schemes with 701 IANA is not required. 703 10. References 705 10.1. Normative References 707 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 708 Requirement Levels", BCP 14, RFC 2119, 709 DOI 10.17487/RFC2119, March 1997, 710 . 712 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 713 Resource Identifier (URI): Generic Syntax", STD 66, 714 RFC 3986, DOI 10.17487/RFC3986, January 2005, 715 . 717 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 718 RFC 6749, DOI 10.17487/RFC6749, October 2012, 719 . 721 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 722 and Registration Procedures for URI Schemes", BCP 35, 723 RFC 7595, DOI 10.17487/RFC7595, June 2015, 724 . 726 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 727 for Code Exchange by OAuth Public Clients", RFC 7636, 728 DOI 10.17487/RFC7636, September 2015, 729 . 731 10.2. Informative References 733 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 734 Threat Model and Security Considerations", RFC 6819, 735 DOI 10.17487/RFC6819, January 2013, 736 . 738 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 739 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 740 RFC 7591, DOI 10.17487/RFC7591, July 2015, 741 . 743 [AppAuth.iOSmacOS] 744 Wright, S., Denniss, W., and others, "AppAuth for iOS and 745 macOS", February 2016, . 748 [AppAuth.Android] 749 McGinniss, I., Denniss, W., and others, "AppAuth for 750 Android", February 2016, . 753 [SamplesForWindows] 754 Denniss, W., "OAuth for Apps: Samples for Windows", July 755 2016, . 758 Appendix A. Server Support Checklist 760 OAuth servers that support native apps must: 762 1. Support private-use URI scheme redirect URIs. This is required 763 to support mobile operating systems. See Section 7.1. 765 2. Support HTTPS scheme redirect URIs for use with public native app 766 clients. This is used by apps on advanced mobile operating 767 systems that allow app-claimed URIs. See Section 7.2. 769 3. Support loopback IP redirect URIs. This is required to support 770 desktop operating systems. See Section 7.3. 772 4. Not assume native app clients can keep a secret. If secrets are 773 distributed to multiple installs of the same native app, they 774 should not be treated as confidential. See Section 8.5. 776 5. Support PKCE [RFC7636]. Required to protect authorization code 777 grants sent to public clients over inter-app communication 778 channels. See Section 8.1 780 Appendix B. Operating System Specific Implementation Details 782 This document primarily defines best practices in an generic manner, 783 referencing techniques commonly available in a variety of 784 environments. This non-normative section documents operating system 785 specific implementation details of the best practice. 787 The implementation details herein are considered accurate at the time 788 of publishing but will likely change over time. It is hoped that 789 such change won't invalidate the generic principles in the rest of 790 the document, and those principles should take precedence in the 791 event of a conflict. 793 B.1. iOS Implementation Details 795 Apps can initiate an authorization request in the browser without the 796 user leaving the app, through the SFSafariViewController class which 797 implements the in-app browser tab pattern. Safari can be used to 798 handle requests on old versions of iOS without 799 SFSafariViewController. 801 To receive the authorization response, both private-use URI scheme 802 redirects (referred to as Custom URL Schemes) and claimed HTTPS links 803 (known as Universal Links) are viable choices, and function the same 804 whether the request is loaded in SFSafariViewController or the Safari 805 app. Apps can claim Custom URI schemes with the "CFBundleURLTypes" 806 key in the application's property list file "Info.plist", and HTTPS 807 links using the Universal Links feature with an entitlement file and 808 an association file on the domain. 810 Universal Links are the preferred choice on iOS 9 and above due to 811 the ownership proof that is provided by the operating system. 813 A complete open source sample is included in the AppAuth for iOS and 814 macOS [AppAuth.iOSmacOS] library. 816 B.2. Android Implementation Details 818 Apps can initiate an authorization request in the browser without the 819 user leaving the app, through the Android Custom Tab feature which 820 implements the in-app browser tab pattern. The user's default 821 browser can be used to handle requests when no browser supports 822 Custom Tabs. 824 Android browser vendors should support the Custom Tabs protocol (by 825 providing an implementation of the "CustomTabsService" class), to 826 provide the in-app browser tab user experience optimization to their 827 users. Chrome is one such browser that implements Custom Tabs. 829 To receive the authorization response, private-use URI schemes are 830 broadly supported through Android Implicit Intends. Claimed HTTPS 831 redirect URIs through Android App Links are available on Android 6.0 832 and above. Both types of redirect URIs are registered in the 833 application's manifest. 835 A complete open source sample is included in the AppAuth for Android 836 [AppAuth.Android] library. 838 B.3. Windows Implementation Details 840 Universal Windows Platform (UWP) apps can use the Web Authentication 841 Broker API in SSO mode as an external user-agent for authorization 842 flows, and all app types can open an authorization request in the 843 user's default browser using platform APIs for opening URIs in the 844 browser. 846 The Web Authentication Broker when used in SSO mode is an external 847 user-agent with an authentication context that is shared with all 848 invocations of the broker but not the user's browser. Note that if 849 not used in SSO mode, the broker is an embedded user-agent, hence 850 only operation in SSO mode is RECOMMENDED. 852 To use the Web Authentication Broker in SSO mode, the redirect URI 853 must be of the form "msapp://{appSID}" where "appSID" is the app's 854 SID, which can be found in the app's registration information. While 855 Windows enforces the URI authority on such redirects, ensuring only 856 the app with the matching SID can receive the response on Windows, 857 the URI scheme could be claimed by apps on other platforms without 858 the same authority present, thus this redirect type should be treated 859 similar to private-use URI scheme redirects for security purposes. 861 Both traditional and Universal Windows Platform (UWP) apps can 862 perform authorization requests in the user's browser. Traditional 863 apps typically use a loopback redirect to receive the authorization 864 response, and listening on the loopback interface is allowed by 865 default firewall rules. Universal Windows Platform (UWP) apps can 866 use private-use URI scheme redirects to receive the authorization 867 response, which will bring the app to the foreground. Known on the 868 platform as "URI Activation", the URI scheme is limited to 39 869 characters in length, and may include the "." character, making short 870 reverse domain name based schemes (as recommended in Section 7.1) 871 possible. 873 An open source sample demonstrating these patterns is available 874 [SamplesForWindows]. 876 B.4. macOS Implementation Details 878 Apps can initiate an authorization request in the user's default 879 browser using platform APIs for opening URIs in the browser. 881 To receive the authorization response, private-use URI schemes are 882 are a good redirect URI choice on macOS, as the user is returned 883 right back to the app they launched the request from. These are 884 registered in the application's bundle information property list 885 using the "CFBundleURLSchemes" key. Loopback IP redirects are 886 another viable option, and listening on the loopback interface is 887 allowed by default firewall rules. 889 A complete open source sample is included in the AppAuth for iOS and 890 macOS [AppAuth.iOSmacOS] library. 892 B.5. Linux Implementation Details 894 Opening the Authorization Request in the user's default browser 895 requires a distro-specific command, "xdg-open" is one such tool. 897 The loopback redirect is the recommended redirect choice for desktop 898 apps on Linux to receive the authorization response. 900 Appendix C. Acknowledgements 902 The author would like to acknowledge the work of Marius Scurtescu, 903 and Ben Wiley Sittler whose design for using private-use URI schemes 904 in native OAuth 2.0 clients at Google formed the basis of 905 Section 7.1. 907 The following individuals contributed ideas, feedback, and wording 908 that shaped and formed the final specification: 910 Andy Zmolek, Steven E Wright, Brian Campbell, Nat Sakimura, Eric 911 Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de 912 Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill 913 Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick 914 Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn 915 Davies. 917 Authors' Addresses 919 William Denniss 920 Google 921 1600 Amphitheatre Pkwy 922 Mountain View, CA 94043 923 USA 925 Email: wdenniss@google.com 926 URI: http://wdenniss.com/appauth 928 John Bradley 929 Ping Identity 931 Phone: +1 202-630-5272 932 Email: ve7jtb@ve7jtb.com 933 URI: http://www.thread-safe.com/p/appauth.html