idnits 2.17.00 (12 Aug 2021) /tmp/idnits52498/draft-ietf-oauth-native-apps-10.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 (April 26, 2017) is 1850 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: October 28, 2017 Ping Identity 6 April 26, 2017 8 OAuth 2.0 for Native Apps 9 draft-ietf-oauth-native-apps-10 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 October 28, 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 . . . 7 60 7. Receiving the Authorization Response in a Native App . . . . 7 61 7.1. Private-use URI Scheme Redirection . . . . . . . . . . . 7 62 7.2. Claimed HTTPS URI Redirection . . . . . . . . . . . . . . 8 63 7.3. Loopback Interface Redirection . . . . . . . . . . . . . 9 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 8.1. Protecting the Authorization Code . . . . . . . . . . . . 9 66 8.2. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 10 67 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 10 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 . . . . . . . . . . . 12 72 8.8. Cross-App Request Forgery Protections . . . . . . . . . . 13 73 8.9. Authorization Server Mix-Up Mitigation . . . . . . . . . 13 74 8.10. Non-Browser External User-Agents . . . . . . . . . . . . 13 75 8.11. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 10.1. Normative References . . . . . . . . . . . . . . . . . . 15 79 10.2. Informative References . . . . . . . . . . . . . . . . . 15 80 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 16 81 Appendix B. Operating System Specific Implementation Details . . 16 82 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 17 83 B.2. Android Implementation Details . . . . . . . . . . . . . 17 84 B.3. Windows Implementation Details . . . . . . . . . . . . . 18 85 B.4. macOS Implementation Details . . . . . . . . . . . . . . 18 86 B.5. Linux Implementation Details . . . . . . . . . . . . . . 19 87 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 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 application that is installed by the user to their 121 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 "OAuth" In this document, OAuth refers to OAuth 2.0 [RFC6749]. 128 "external user-agent" A user-agent capable of handling the 129 authorization request that is a separate entity or security domain 130 to the native app making the request (such as a browser), such 131 that the app cannot access the cookie storage, nor inspect or 132 modify page content. 134 "embedded user-agent" A user-agent hosted inside the native app 135 itself (such as via a web-view), with which the app has control 136 over to the extent it is capable of accessing the cookie storage 137 and/or modify the page content. 139 "app" Shorthand for "native app". 141 "app store" An ecommerce store where users can download and purchase 142 apps. 144 "browser" The operating system's default browser, pre-installed as 145 part of the operating system, or installed and set as default by 146 the user. 148 "browser tab" An open page of the browser. Browser typically have 149 multiple "tabs" representing various open pages. 151 "in-app browser tab" A full page browser with limited navigation 152 capabilities that is displayed inside a host app, but retains the 153 full security properties and authentication state of the browser. 154 Has different platform-specific product names, such as 155 SFSafariViewController on iOS, and Custom Tabs on Android. 157 "inter-app communication" Communication between two apps on a 158 device. 160 "claimed HTTPS URI" Some platforms allow apps to claim a HTTPS 161 scheme URI after proving ownership of the domain name. URIs 162 claimed in such a way are then opened in the app instead of the 163 browser. 165 "private-use URI scheme" A private-use URI scheme defined by the app 166 and registered with the operating system. URI requests to such 167 schemes trigger the app which registered it to be launched to 168 handle the request. 170 "web-view" A web browser UI component that can be embedded in apps 171 to render web pages, used to create embedded user-agents. 173 "reverse domain name notation" A naming convention based on the 174 domain name system, but where the domain components are reversed, 175 for example "app.example.com" becomes "com.example.app". 177 4. Overview 179 The best current practice for authorizing users in native apps is to 180 perform the OAuth authorization request in an external user-agent 181 (typically the browser), rather than an embedded user-agent (such as 182 one implemented with web-views). 184 Previously it was common for native apps to use embedded user-agents 185 (commonly implemented with web-views) for OAuth authorization 186 requests. That approach has many drawbacks, including the host app 187 being able to copy user credentials and cookies, and the user needing 188 to authenticate from scratch in each app. See Section 8.11 for a 189 deeper analysis of using embedded user-agents for OAuth. 191 Native app authorization requests that use the browser are more 192 secure and can take advantage of the user's authentication state. 193 Being able to use the existing authentication session in the browser 194 enables single sign-on, as users don't need to authenticate to the 195 authorization server each time they use a new app (unless required by 196 authorization server policy). 198 Supporting authorization flows between a native app and the browser 199 is possible without changing the OAuth protocol itself, as the 200 authorization request and response are already defined in terms of 201 URIs, which emcompasses URIs that can be used for inter-process 202 communication. Some OAuth server implementations that assume all 203 clients are confidential web-clients will need to add an 204 understanding of public native app clients and the types of redirect 205 URIs they use to support this best practice. 207 4.1. Authorization Flow for Native Apps Using the Browser 209 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 210 | User Device | 211 | | 212 | +---------------------------+ | +-----------+ 213 | | | | (5) Authz Code | | 214 | | Client App |----------------------->| Token | 215 | | |<-----------------------| Endpoint | 216 | +---------------------------+ | (6) Access Token, | | 217 | | ^ | Refresh Token +-----------+ 218 | | | | 219 | | | | 220 | | (1) | (4) | 221 | | Authz | Authz | 222 | | Request | Code | 223 | | | | 224 | | | | 225 | v | | 226 | +---------------------------+ | +---------------+ 227 | | | | (2) Authz Request | | 228 | | Browser |--------------------->| Authorization | 229 | | |<---------------------| Endpoint | 230 | +---------------------------+ | (3) Authz Code | | 231 | | +---------------+ 232 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 234 Figure 1: Native App Authorization via External User-agent 236 Figure 1 illustrates the interaction of the native app with the 237 system browser to authorize the user via an external user-agent. 239 (1) The client app opens a browser tab with the authorization 240 request. 242 (2) Authorization endpoint receives the authorization request, 243 authenticates the user and obtains authorization. 244 Authenticating the user may involve chaining to other 245 authentication systems. 247 (3) Authorization server issues an authorization code to the 248 redirect URI. 250 (4) Client receives the authorization code from the redirect URI. 252 (5) Client app presents the authorization code at the token 253 endpoint. 255 (6) Token endpoint validates the authorization code and issues the 256 tokens requested. 258 5. Using Inter-app URI Communication for OAuth 260 Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 261 the authorization request and return the authorization response to 262 the requesting website, URIs can be used by native apps to initiate 263 the authorization request in the device's browser and return the 264 response to the requesting native app. 266 By applying the same principles from the web to native apps, we gain 267 benefits seen on the web, like the usability of a single sign-on 268 session and the security of a separate authentication context. It 269 also reduces the implementation complexity by reusing similar flows 270 as the web, and increases interoperability by relying on standards- 271 based web flows that are not specific to a particular platform. 273 Native apps MUST use an external user-agent to perform OAuth 274 authentication requests. This is achieved by opening the 275 authorization request in the browser (detailed in Section 6), and 276 using a redirect URI that will return the authorization response back 277 to the native app, as defined in Section 7. 279 This best practice focuses on the browser as the RECOMMENDED external 280 user-agent for native apps. Other external user-agents, such as a 281 native app provided by the authorization server may meet the criteria 282 set out in this best practice, including using the same redirection 283 URI properties, but their use is out of scope for this specification. 285 6. Initiating the Authorization Request from a Native App 287 The authorization request is created as per OAuth 2.0 [RFC6749], and 288 opened in the user's browser using platform-specific APIs for that 289 purpose. 291 The function of the redirect URI for a native app authorization 292 request is similar to that of a web-based authorization request. 293 Rather than returning the authorization response to the OAuth 294 client's server, the redirect URI used by a native app returns the 295 response to the app. The various options for a redirect URI that 296 will return the code to the native app are documented in Section 7. 297 Any redirect URI that allows the app to receive the URI and inspect 298 its parameters is viable. 300 Some platforms support a browser feature known as in-app browser 301 tabs, where an app can present a tab of the browser within the app 302 context without switching apps, but still retain key benefits of the 303 browser such as a shared authentication state and security context. 304 On platforms where they are supported, it is RECOMMENDED for 305 usability reasons that apps use in-app browser tabs for the 306 Authorization Request. 308 7. Receiving the Authorization Response in a Native App 310 There are several redirect URI options available to native apps for 311 receiving the authorization response from the browser, the 312 availability and user experience of which varies by platform. 314 To fully support this best practice, authorization servers MUST 315 support the following three redirect URI options. Native apps MAY 316 use whichever redirect option suits their needs best, taking into 317 account platform specific implementation details. 319 7.1. Private-use URI Scheme Redirection 321 Many mobile and desktop computing platforms support inter-app 322 communication via URIs by allowing apps to register private-use URI 323 schemes (sometimes colloquially referred to as custom URL schemes) 324 like "com.example.app". When the browser or another app attempts to 325 load a URI with a custom scheme, the app that registered it is 326 launched to handle the request. 328 To perform an OAuth 2.0 authorization request with a private-use URI 329 scheme redirect, the native app launches the browser with a standard 330 authorization request, but one where the redirection URI utilizes a 331 custom URI scheme it registered with the operating system. 333 When choosing a URI scheme to associate with the app, apps MUST use a 334 URI scheme based on a domain name under their control, expressed in 335 reverse order, as recommended by Section 3.8 of [RFC7595] for 336 private-use URI schemes. 338 For example, an app that controls the domain name "app.example.com" 339 can use "com.example.app" as their scheme. Some authorization 340 servers assign client identifiers based on domain names, for example 341 "client1234.usercontent.example.net", which can also be used as the 342 domain name for the scheme when reversed in the same manner. A 343 scheme such as "myapp" however would not meet this requirement, as it 344 is not based on a domain name. 346 Care must be taken when there are multiple apps by the same publisher 347 that each scheme is unique within that group. On platforms that use 348 app identifiers that are also based on reverse order domain names, 349 those can be reused as the private-use URI scheme for the OAuth 350 redirect to help avoid this problem. 352 Following the requirements of [RFC3986] Section 3.2, as there is no 353 naming authority for private-use URI scheme redirects, only a single 354 slash ("/") appears after the scheme component. A complete example 355 of a redirect URI utilizing a private-use URI scheme: 357 com.example.app:/oauth2redirect/example-provider 359 When the authentication server completes the request, it redirects to 360 the client's redirection URI like it would any redirect URI. As the 361 redirection URI uses a custom scheme it results in the operating 362 system launching the native app, passing in the URI as a launch 363 parameter. The native app then processes the authorization response 364 like normal. 366 7.2. Claimed HTTPS URI Redirection 368 Some operating systems allow apps to claim HTTPS scheme URIs in 369 domains they control. When the browser encounters a claimed URI, 370 instead of the page being loaded in the browser, the native app is 371 launched with the URI supplied as a launch parameter. 373 Such URIs can be used as OAuth redirect URIs. They are 374 indistinguishable from OAuth redirects of web-based clients. An 375 example is: 377 https://app.example.com/oauth2redirect/example-provider 379 App-claimed HTTPS redirect URIs have some advantages in that the 380 identity of the destination app is guaranteed by the operating 381 system. Due to this reason, they SHOULD be used over the other 382 redirect choices for native apps where possible. 384 Claimed HTTPS redirect URIs function as normal HTTPS redirects from 385 the perspective of the authorization server, though as stated in 386 Section 8.4, it REQUIRED that the authorization server is able to 387 distinguish between public native app clients that use app-claimed 388 HTTPS redirect URIs and confidential web clients. 390 7.3. Loopback Interface Redirection 392 Native apps that are able to open a port on the loopback network 393 interface without needing special permissions (typically, those on 394 desktop operating systems) can use the loopback network interface to 395 receive the OAuth redirect. 397 Loopback redirect URIs use the HTTP scheme and are constructed with 398 the loopback IP literal and whatever port the client is listening on. 399 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 400 "http://[::1]:{port}/{path}" for IPv6. A complete example of such a 401 redirect with a randomly assigned port: 403 http://127.0.0.1:61023/oauth2redirect/example-provider 405 The authorization server MUST allow any port to be specified at the 406 time of the request for loopback IP redirect URIs, to accommodate 407 clients that obtain an available ephemeral port from the operating 408 system at the time of the request. 410 8. Security Considerations 412 8.1. Protecting the Authorization Code 414 The redirect URI options documented in Section 7 share the benefit 415 that only a native app on the same device can receive the 416 authorization code which limits the attack surface, however code 417 interception by a native app other than the intended app may still be 418 possible. 420 A limitation of using private-use URI schemes for redirect URIs is 421 that multiple apps can typically register the same scheme, which 422 makes it indeterminate as to which app will receive the Authorization 423 Code. PKCE [RFC7636] details how this limitation can be used to 424 execute a code interception attack (see Figure 1). 426 Loopback IP based redirect URIs may be susceptible to interception by 427 other apps listening on the same loopback interface. 429 As most forms of inter-app URI-based communication sends data over 430 insecure local channels, eavesdropping and interception of the 431 authorization response is a risk for native apps. App-claimed HTTPS 432 redirects are hardened against this type of attack due to the 433 presence of the URI authority, but they are still public clients and 434 the URI is still transmitted over local channels with unknown 435 security properties. 437 The Proof Key for Code Exchange by OAuth Public Clients (PKCE 438 [RFC7636]) standard was created specifically to mitigate against this 439 attack. It is a Proof of Possession extension to OAuth 2.0 that 440 protects the code grant from being used if it is intercepted. It 441 achieves this by having the client generate a secret verifier, a hash 442 of which it passes in the initial authorization request, and which it 443 must present in full when redeeming the authorization code grant. An 444 app that intercepted the authorization code would not be in 445 possession of this secret, rendering the code useless. 447 Public native app clients MUST protect the authorization request with 448 PKCE [RFC7636]. Authorization servers MUST support PKCE [RFC7636] 449 for public native app clients. Authorization servers SHOULD reject 450 authorization requests from native apps that don't use PKCE by 451 returning an error message as defined in Section 4.4.1 of PKCE 452 [RFC7636]. 454 8.2. OAuth Implicit Flow 456 The OAuth 2.0 Implicit Flow as defined in Section 4.2 of OAuth 2.0 457 [RFC6749] generally works with the practice of performing the 458 authorization request in the browser, and receiving the authorization 459 response via URI-based inter-app communication. However, as the 460 Implicit Flow cannot be protected by PKCE (which is a required in 461 Section 8.1), the use of the Implicit Flow with native apps is NOT 462 RECOMMENDED. 464 Tokens granted via the implicit flow also cannot be refreshed without 465 user interaction, making the code flow - which can issue refresh 466 tokens - the more practical option for native app authorizations that 467 require refreshing. 469 8.3. Loopback Redirect Considerations 471 Loopback interface redirect URIs use the "http" scheme (i.e. without 472 TLS). This is acceptable for loopback interface redirect URIs as the 473 HTTP request never leaves the device. 475 Clients should open the network port only when starting the 476 authorization request, and close it once the response is returned. 478 Clients should listen on the loopback network interface only, to 479 avoid interference by other network actors. 481 While redirect URIs using localhost (i.e. 482 "http://localhost:{port}/") function similarly to loopback IP 483 redirects described in Section 7.3, the use of "localhost" is NOT 484 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 485 rather than localhost avoids inadvertently listening on network 486 interfaces other than the loopback interface. It is also less 487 susceptible to client side firewalls, and misconfigured host name 488 resolution on the user's device. 490 8.4. Registration of Native App Clients 492 Native apps, except when using a mechanism like Dynamic Client 493 Registration [RFC7591] to provision per-instance secrets, are 494 classified as public clients, as defined by Section 2.1 of OAuth 2.0 495 [RFC6749] and MUST be registered with the authorization server as 496 such. Authorization servers MUST record the client type in the 497 client registration details in order to identify and process requests 498 accordingly. 500 Authorization servers MUST require clients to register their complete 501 redirect URI (including the path component), and reject authorization 502 requests that specify a redirect URI that doesn't exactly match the 503 one that was registered, with the exception of loopback redirects, 504 where an exact match is required except for the port URI component. 506 For private-use URI scheme based redirects, authorization servers 507 SHOULD enforce the requirement in Section 7.1 that clients use 508 reverse domain name based schemes. At a minimum, any scheme that 509 doesn't contain a period character ("."), SHOULD be rejected. 511 In addition to the collision resistant properties, requiring a URI 512 scheme based on a domain name that is under the control of the app 513 can help to prove ownership in the event of a dispute where two apps 514 claim the same private-use URI scheme (where one app is acting 515 maliciously). For example, if two apps claimed "com.example.app", 516 the owner of "example.com" could petition the app store operator to 517 remove the counterfeit app. Such a petition is harder to prove if a 518 generic URI scheme was used. 520 Authorization servers MAY request the inclusion of other platform- 521 specific information, such as the app package or bundle name, or 522 other information used to associate the app that may be useful for 523 verifying the calling app's identity, on operating systems that 524 support such functions. 526 8.5. Client Authentication 528 Secrets that are statically included as part of an app distributed to 529 multiple users should not be treated as confidential secrets, as one 530 user may inspect their copy and learn the shared secret. For this 531 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 532 RECOMMENDED for authorization servers to require client 533 authentication of public native apps clients using a shared secret, 534 as this serves little value beyond client identification which is 535 already provided by the "client_id" request parameter. 537 Authorization servers that still require a statically included shared 538 secret for native app clients MUST treat the client as a public 539 client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not 540 accept the secret as proof of the client's identity. Without 541 additional measures, such clients are subject to client impersonation 542 (see Section 8.6). 544 8.6. Client Impersonation 546 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 547 server SHOULD NOT process authorization requests automatically 548 without user consent or interaction, except when the identity of the 549 client can be assured. This includes the case where the user has 550 previously approved an authorization request for a given client id - 551 unless the identity of the client can be proven, the request SHOULD 552 be processed as if no previous request had been approved. 554 Measures such as claimed HTTPS redirects MAY be accepted by 555 authorization servers as identity proof. Some operating systems may 556 offer alternative platform-specific identity features which MAY be 557 accepted, as appropriate. 559 8.7. Phishability of In-App Browser Tabs 561 While in-app browser tabs provide a secure authentication context, as 562 the user initiates the flow from a native app, it is possible for 563 that native app to completely fake an in-app browser tab. 565 This can't be prevented directly - once the user is in the native 566 app, that app is fully in control of what it can render - however 567 there are several mitigating factors. 569 Importantly, such an attack that uses a web-view to fake an in-app 570 browser tab will always start with no authentication state. If all 571 native apps use the techniques described in this best practice, users 572 will not need to sign-in frequently and thus should be suspicious of 573 any sign-in request when they should have already been signed-in. 575 This is the case even for authorization servers that require 576 occasional or frequent re-authentication, as such servers can 577 preserve some user identifiable information from the old session, 578 like the email address or profile picture and display that 579 information during re-authentication. 581 Users who are particularly concerned about their security may also 582 take the additional step of opening the request in the browser from 583 the in-app browser tab, and completing the authorization there, as 584 most implementations of the in-app browser tab pattern offer such 585 functionality. 587 8.8. Cross-App Request Forgery Protections 589 Section 5.3.5 of [RFC6819] recommends using the "state" parameter to 590 link client requests and responses to prevent CSRF attacks. 592 It is similarly RECOMMENDED for native apps to include a high entropy 593 secure random number in the "state" parameter of the authorization 594 request, and reject any incoming authorization responses without a 595 state value that matches a pending outgoing authorization request. 597 8.9. Authorization Server Mix-Up Mitigation 599 To protect against a compromised or malicious authorization server 600 attacking another authorization server used by the same app, it is 601 REQUIRED that a unique redirect URI is used for each authorization 602 server used by the app (for example, by varying the path component), 603 and that authorization responses are rejected if the redirect URI 604 they were received on doesn't match the redirect URI in a outgoing 605 authorization request. 607 The native app MUST store the redirect URI used in the authorization 608 request with the authorization session data (i.e. along with "state" 609 and other related data), and MUST verify that the URI on which the 610 authorization response was received exactly matches it. 612 The requirements of Section 8.4 that authorization servers reject 613 requests with URIs that don't match what was registered are also 614 required to prevent such attacks. 616 8.10. Non-Browser External User-Agents 618 This best practice recommends a particular type of external user- 619 agent, the user's browser. Other external user-agent patterns may 620 also be viable for secure and usable OAuth. This document makes no 621 comment on those patterns. 623 8.11. Embedded User-Agents 625 OAuth 2.0 [RFC6749] Section 9 documents two approaches for native 626 apps to interact with the authorization endpoint. This best current 627 practice requires that native apps MUST NOT use embedded user-agents 628 to perform authorization requests, and allows that authorization 629 endpoints MAY take steps to detect and block authorization requests 630 in embedded user-agents. The security considerations for these 631 requirements are detailed herein. 633 Embedded user-agents are an alternative method for authorizing native 634 apps. These embedded user agents are unsafe for use by third-parties 635 to the authorization server by definition, as the app that hosts the 636 embedded user-agent can access the user's full authentication 637 credential, not just the OAuth authorization grant that was intended 638 for the app. 640 In typical web-view based implementations of embedded user-agents, 641 the host application can: log every keystroke entered in the form to 642 capture usernames and passwords; automatically submit forms and 643 bypass user-consent; copy session cookies and use them to perform 644 authenticated actions as the user. 646 Even when used by trusted apps belonging to the same party as the 647 authorization server, embedded user-agents violate the principle of 648 least privilege by having access to more powerful credentials than 649 they need, potentially increasing the attack surface. 651 Encouraging users to enter credentials in an embedded user-agent 652 without the usual address bar and visible certificate validation 653 features that browsers have makes it impossible for the user to know 654 if they are signing in to the legitimate site, and even when they 655 are, it trains them that it's OK to enter credentials without 656 validating the site first. 658 Aside from the security concerns, embedded user-agents do not share 659 the authentication state with other apps or the browser, requiring 660 the user to login for every authorization request which is often 661 considered an inferior user experience. 663 9. IANA Considerations 665 [RFC Editor: please do NOT remove this section.] 667 This document has no IANA actions. 669 Section 7.1 specifies how private-use URI schemes are used for inter- 670 app communication in OAuth protocol flows. This document requires in 671 Section 7.1 that such schemes are based on domain names owned or 672 assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per 673 Section 6 of [RFC7595], registration of domain based URI schemes with 674 IANA is not required. 676 10. References 678 10.1. Normative References 680 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 681 Requirement Levels", BCP 14, RFC 2119, 682 DOI 10.17487/RFC2119, March 1997, 683 . 685 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 686 Resource Identifier (URI): Generic Syntax", STD 66, 687 RFC 3986, DOI 10.17487/RFC3986, January 2005, 688 . 690 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 691 RFC 6749, DOI 10.17487/RFC6749, October 2012, 692 . 694 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 695 and Registration Procedures for URI Schemes", BCP 35, 696 RFC 7595, DOI 10.17487/RFC7595, June 2015, 697 . 699 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 700 for Code Exchange by OAuth Public Clients", RFC 7636, 701 DOI 10.17487/RFC7636, September 2015, 702 . 704 10.2. Informative References 706 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 707 Threat Model and Security Considerations", RFC 6819, 708 DOI 10.17487/RFC6819, January 2013, 709 . 711 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 712 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 713 RFC 7591, DOI 10.17487/RFC7591, July 2015, 714 . 716 [AppAuth.iOSmacOS] 717 Wright, S., Denniss, W., and others, "AppAuth for iOS and 718 macOS", February 2016, . 721 [AppAuth.Android] 722 McGinniss, I., Denniss, W., and others, "AppAuth for 723 Android", February 2016, . 726 [SamplesForWindows] 727 Denniss, W., "OAuth for Apps: Samples for Windows", July 728 2016, . 731 Appendix A. Server Support Checklist 733 OAuth servers that support native apps must: 735 1. Support private-use URI scheme redirect URIs. This is required 736 to support mobile operating systems. See Section 7.1. 738 2. Support HTTPS scheme redirect URIs for use with public native app 739 clients. This is used by apps on advanced mobile operating 740 systems that allow app-claimed URIs. See Section 7.2. 742 3. Support loopback IP redirect URIs. This is required to support 743 desktop operating systems. See Section 7.3. 745 4. Not assume native app clients can keep a secret. If secrets are 746 distributed to multiple installs of the same native app, they 747 should not be treated as confidential. See Section 8.5. 749 5. Support PKCE [RFC7636]. Required to protect authorization code 750 grants sent to public clients over inter-app communication 751 channels. See Section 8.1 753 Appendix B. Operating System Specific Implementation Details 755 This document primarily defines best practices in an generic manner, 756 referencing techniques commonly available in a variety of 757 environments. This non-normative section documents operating system 758 specific implementation details of the best practice. 760 The implementation details herein are considered accurate at the time 761 of publishing but will likely change over time. It is hoped that 762 such change won't invalidate the generic principles in the rest of 763 the document, and those principles should take precedence in the 764 event of a conflict. 766 B.1. iOS Implementation Details 768 Apps can initiate an authorization request in the browser without the 769 user leaving the app, through the SFSafariViewController class which 770 implements the in-app browser tab pattern. Safari can be used to 771 handle requests on old versions of iOS without 772 SFSafariViewController. 774 To receive the authorization response, both private-use URI scheme 775 redirects (referred to as Custom URL Schemes) and claimed HTTPS links 776 (known as Universal Links) are viable choices, and function the same 777 whether the request is loaded in SFSafariViewController or the Safari 778 app. Apps can claim Custom URI schemes with the "CFBundleURLTypes" 779 key in the application's property list file "Info.plist", and HTTPS 780 links using the Universal Links feature with an entitlement file and 781 an association file on the domain. 783 Universal Links are the preferred choice on iOS 9 and above due to 784 the ownership proof that is provided by the operating system. 786 A complete open source sample is included in the AppAuth for iOS and 787 macOS [AppAuth.iOSmacOS] library. 789 B.2. Android Implementation Details 791 Apps can initiate an authorization request in the browser without the 792 user leaving the app, through the Android Custom Tab feature which 793 implements the in-app browser tab pattern. The user's default 794 browser can be used to handle requests when no browser supports 795 Custom Tabs. 797 Android browser vendors should support the Custom Tabs protocol (by 798 providing an implementation of the "CustomTabsService" class), to 799 provide the in-app browser tab user experience optimization to their 800 users. Chrome is one such browser that implements Custom Tabs. 802 To receive the authorization response, private-use URI schemes are 803 broadly supported through Android Implicit Intends. Claimed HTTPS 804 redirect URIs through Android App Links are available on Android 6.0 805 and above. Both types of redirect URIs are registered in the 806 application's manifest. 808 A complete open source sample is included in the AppAuth for Android 809 [AppAuth.Android] library. 811 B.3. Windows Implementation Details 813 Universal Windows Platform (UWP) apps can use the Web Authentication 814 Broker API in SSO mode as an external user-agent for authorization 815 flows, and all app types can open an authorization request in the 816 user's default browser using platform APIs for opening URIs in the 817 browser. 819 The Web Authentication Broker when used in SSO mode is an external 820 user-agent with an authentication context that is shared with all 821 invocations of the broker but not the user's browser. Note that if 822 not used in SSO mode, the broker is an embedded user-agent, hence 823 only operation in SSO mode is RECOMMENDED. 825 To use the Web Authentication Broker in SSO mode, the redirect URI 826 must be of the form "msapp://{appSID}" where "appSID" is the app's 827 SID, which can be found in the app's registration information. While 828 Windows enforces the URI authority on such redirects, ensuring only 829 the app with the matching SID can receive the response on Windows, 830 the URI scheme could be claimed by apps on other platforms without 831 the same authority present, thus this redirect type should be treated 832 similar to private-use URI scheme redirects for security purposes. 834 Both traditional and Universal Windows Platform (UWP) apps can 835 perform authorization requests in the user's browser. Traditional 836 apps typically use a loopback redirect to receive the authorization 837 response, and listening on the loopback interface is allowed by 838 default firewall rules. Universal Windows Platform (UWP) apps can 839 use private-use URI scheme redirects to receive the authorization 840 response, which will bring the app to the foreground. Known on the 841 platform as "URI Activation", the URI scheme is limited to 39 842 characters in length, and may include the "." character, making short 843 reverse domain name based schemes (as recommended in Section 7.1) 844 possible. 846 An open source sample demonstrating these patterns is available 847 [SamplesForWindows]. 849 B.4. macOS Implementation Details 851 Apps can initiate an authorization request in the user's default 852 browser using platform APIs for opening URIs in the browser. 854 To receive the authorization response, private-use URI schemes are 855 are a good redirect URI choice on macOS, as the user is returned 856 right back to the app they launched the request from. These are 857 registered in the application's bundle information property list 858 using the "CFBundleURLSchemes" key. Loopback IP redirects are 859 another viable option, and listening on the loopback interface is 860 allowed by default firewall rules. 862 A complete open source sample is included in the AppAuth for iOS and 863 macOS [AppAuth.iOSmacOS] library. 865 B.5. Linux Implementation Details 867 Opening the Authorization Request in the user's default browser 868 requires a distro-specific command, "xdg-open" is one such tool. 870 The loopback redirect is the recommended redirect choice for desktop 871 apps on Linux to receive the authorization response. 873 Appendix C. Acknowledgements 875 The author would like to acknowledge the work of Marius Scurtescu, 876 and Ben Wiley Sittler whose design for using private-use URI schemes 877 in native OAuth 2.0 clients formed the basis of Section 7.1. 879 The following individuals contributed ideas, feedback, and wording 880 that shaped and formed the final specification: 882 Andy Zmolek, Steven E Wright, Brian Campbell, Paul Madsen, Nat 883 Sakimura, Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de 884 Medeiros, Adam Dawes, Naveen Agarwal, Hannes Tschofenig, Ashish Jain, 885 Erik Wahlstrom, Bill Fisher, Sudhi Umarji, Michael B. Jones, Vittorio 886 Bertocci, Dick Hardt, David Waite, and Ignacio Fiorentino. 888 Authors' Addresses 890 William Denniss 891 Google 892 1600 Amphitheatre Pkwy 893 Mountain View, CA 94043 894 USA 896 Email: wdenniss@google.com 897 URI: http://wdenniss.com/appauth 899 John Bradley 900 Ping Identity 902 Phone: +1 202-630-5272 903 Email: ve7jtb@ve7jtb.com 904 URI: http://www.thread-safe.com/p/appauth.html