idnits 2.17.1 draft-ietf-oauth-native-apps-12.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. -- The draft header indicates that this document updates RFC6749, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 9, 2017) is 2503 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) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) 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 Updates: 6749 (if approved) J. Bradley 5 Intended status: Best Current Practice Ping Identity 6 Expires: December 11, 2017 June 9, 2017 8 OAuth 2.0 for Native Apps 9 draft-ietf-oauth-native-apps-12 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 December 11, 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. Fake External User-Agent . . . . . . . . . . . . . . . . 13 72 8.8. Malicious External User-Agent . . . . . . . . . . . . . . 13 73 8.9. Cross-App Request Forgery Protections . . . . . . . . . . 14 74 8.10. Authorization Server Mix-Up Mitigation . . . . . . . . . 14 75 8.11. Non-Browser External User-Agents . . . . . . . . . . . . 14 76 8.12. Embedded User-Agents . . . . . . . . . . . . . . . . . . 14 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 78 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 10.1. Normative References . . . . . . . . . . . . . . . . . . 16 80 10.2. Informative References . . . . . . . . . . . . . . . . . 16 81 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 17 82 Appendix B. Operating System Specific Implementation Details . . 17 83 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 18 84 B.2. Android Implementation Details . . . . . . . . . . . . . 18 85 B.3. Windows Implementation Details . . . . . . . . . . . . . 19 86 B.4. macOS Implementation Details . . . . . . . . . . . . . . 19 87 B.5. Linux Implementation Details . . . . . . . . . . . . . . 20 88 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 20 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 91 1. Introduction 93 The OAuth 2.0 [RFC6749] authorization framework documents two 94 approaches in Section 9 for native apps to interact with the 95 authorization endpoint: an embedded user-agent, and an external user- 96 agent. 98 This best current practice requires that only external user-agents 99 like the browser are used for OAuth by native apps. It documents how 100 native apps can implement authorization flows using the browser as 101 the preferred external user-agent, and the requirements for 102 authorization servers to support such usage. 104 This practice is also known as the AppAuth pattern, in reference to 105 open source libraries [AppAuth] that implement it. 107 2. Notational Conventions 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in Key 112 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 113 these words are used without being spelled in uppercase then they are 114 to be interpreted with their normal natural language meanings. 116 3. Terminology 118 In addition to the terms defined in referenced specifications, this 119 document uses the following terms: 121 "native app" An app or application that is installed by the user to 122 their device, as distinct from a web app that runs in the browser 123 context only. Apps implemented using web-based technology but 124 distributed as a native app, so-called hybrid apps, are considered 125 equivalent to native apps for the purpose of this specification. 127 "app" In this document, "app" means a "native app" unless further 128 specified. 130 "app store" An ecommerce store where users can download and purchase 131 apps. 133 "OAuth" In this document, OAuth refers to the OAuth 2.0 134 Authorization Framework [RFC6749]. 136 "external user-agent" A user-agent capable of handling the 137 authorization request that is a separate entity or security domain 138 to the native app making the request (such as a browser), such 139 that the app cannot access the cookie storage, nor inspect or 140 modify page content. 142 "embedded user-agent" A user-agent hosted inside the native app 143 itself (such as via a web-view), with which the app has control 144 over to the extent it is capable of accessing the cookie storage 145 and/or modifying the page content. 147 "browser" The default application launched by the operating system 148 to handle "http" and "https" scheme URI content. 150 "in-app browser tab" A programmatic instantiation of the browser 151 that is displayed inside a host app, but retains the full security 152 properties and authentication state of the browser. Has different 153 platform-specific product names, such as SFSafariViewController on 154 iOS, and Custom Tabs on Android. 156 "inter-app communication" Communication between two apps on a 157 device. 159 "claimed HTTPS URI" Some platforms allow apps to claim a HTTPS 160 scheme URI after proving ownership of the domain name. URIs 161 claimed in such a way are then opened in the app instead of the 162 browser. 164 "private-use URI scheme" A private-use URI scheme defined by the app 165 and registered with the operating system. URI requests to such 166 schemes trigger the app which registered it to be launched to 167 handle the request. 169 "web-view" A web browser UI (user interface) component that can be 170 embedded in apps to render web pages, used to create embedded 171 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.12 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 encompasses URIs that can be used for inter-app 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 | +--------------------------+ | (5) Authorization +---------------+ 213 | | | | Code | | 214 | | Client App |---------------------->| Token | 215 | | |<----------------------| Endpoint | 216 | +--------------------------+ | (6) Access Token, | | 217 | | ^ | Refresh Token +---------------+ 218 | | | | 219 | | | | 220 | | (1) | (4) | 221 | | Authorizat- | Authoriza- | 222 | | ion Request | tion Code | 223 | | | | 224 | | | | 225 | v | | 226 | +---------------------------+ | (2) Authorization +---------------+ 227 | | | | Request | | 228 | | Browser |--------------------->| Authorization | 229 | | |<---------------------| Endpoint | 230 | +---------------------------+ | (3) Authorization | | 231 | | Code +---------------+ 232 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 234 Figure 1: Native App Authorization via External User-agent 236 Figure 1 illustrates the interaction of the native app with a browser 237 external user-agent to authorize the user. 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 adopting the same methods used on the web for OAuth, benefits seen 267 in the web context like the usability of a single sign-on session and 268 the security of a separate authentication context are likewise gained 269 in the native app context. Re-using the same approach also reduces 270 the implementation complexity and increases interoperability by 271 relying on standards-based web flows that are not specific to a 272 particular platform. 274 To conform to this best practice, native apps MUST use an external 275 user-agent to perform OAuth authentication requests. This is 276 achieved by opening the authorization request in the browser 277 (detailed in Section 6), and using a redirect URI that will return 278 the authorization response back to the native app, as defined in 279 Section 7. 281 6. Initiating the Authorization Request from a Native App 283 Native apps needing user authorization create an authorization 284 request URI with the authorization code grant type per Section 4.1 of 285 OAuth 2.0 [RFC6749], using a redirect URI capable of being received 286 by the native app. 288 The function of the redirect URI for a native app authorization 289 request is similar to that of a web-based authorization request. 290 Rather than returning the authorization response to the OAuth 291 client's server, the redirect URI used by a native app returns the 292 response to the app. Several options for a redirect URI that will 293 return the authorization response to the native app in different 294 platforms are documented in Section 7. Any redirect URI that allows 295 the app to receive the URI and inspect its parameters is viable. 297 Public native app clients MUST implement the Proof Key for Code 298 Exchange (PKCE [RFC7636]) extension to OAuth, and authorization 299 servers MUST support PKCE for such clients, for the reasons detailed 300 in Section 8.1. 302 After constructing the authorization request URI, the app uses 303 platform-specific APIs to open the URI in an external user-agent. 304 Typically the external user-agent used is the default browser, that 305 is, the application configured for handling "http" and "https" scheme 306 URIs on the system, but different browser selection criteria and 307 other categories of external user-agents MAY be used. 309 This best practice focuses on the browser as the RECOMMENDED external 310 user-agent for native apps. An external user-agent designed 311 specifically for processing authorization requests capable of 312 processing the request and redirect URIs in the same way MAY also be 313 used. Other external user-agents, such as a native app provided by 314 the authorization server may meet the criteria set out in this best 315 practice, including using the same redirection URI properties, but 316 their use is out of scope for this specification. 318 Some platforms support a browser feature known as in-app browser 319 tabs, where an app can present a tab of the browser within the app 320 context without switching apps, but still retain key benefits of the 321 browser such as a shared authentication state and security context. 322 On platforms where they are supported, it is RECOMMENDED for 323 usability reasons that apps use in-app browser tabs for the 324 authorization request. 326 7. Receiving the Authorization Response in a Native App 328 There are several redirect URI options available to native apps for 329 receiving the authorization response from the browser, the 330 availability and user experience of which varies by platform. 332 To fully support this best practice, authorization servers MUST offer 333 at least the following three redirect URI options to native apps. 334 Native apps MAY use whichever redirect option suits their needs best, 335 taking into account platform specific implementation details. 337 7.1. Private-use URI Scheme Redirection 339 Many mobile and desktop computing platforms support inter-app 340 communication via URIs by allowing apps to register private-use URI 341 schemes (sometimes colloquially referred to as custom URL schemes) 342 like "com.example.app". When the browser or another app attempts to 343 load a URI with a custom scheme, the app that registered it is 344 launched to handle the request. 346 To perform an OAuth 2.0 authorization request with a private-use URI 347 scheme redirect, the native app launches the browser with a standard 348 authorization request, but one where the redirection URI utilizes a 349 custom URI scheme it registered with the operating system. 351 When choosing a URI scheme to associate with the app, apps MUST use a 352 URI scheme based on a domain name under their control, expressed in 353 reverse order, as recommended by Section 3.8 of [RFC7595] for 354 private-use URI schemes. 356 For example, an app that controls the domain name "app.example.com" 357 can use "com.example.app" as their scheme. Some authorization 358 servers assign client identifiers based on domain names, for example 359 "client1234.usercontent.example.net", which can also be used as the 360 domain name for the scheme when reversed in the same manner. A 361 scheme such as "myapp" however would not meet this requirement, as it 362 is not based on a domain name. 364 Care must be taken when there are multiple apps by the same publisher 365 that each scheme is unique within that group. On platforms that use 366 app identifiers that are also based on reverse order domain names, 367 those can be reused as the private-use URI scheme for the OAuth 368 redirect to help avoid this problem. 370 Following the requirements of [RFC3986] Section 3.2, as there is no 371 naming authority for private-use URI scheme redirects, only a single 372 slash ("/") appears after the scheme component. A complete example 373 of a redirect URI utilizing a private-use URI scheme: 375 com.example.app:/oauth2redirect/example-provider 377 When the authentication server completes the request, it redirects to 378 the client's redirection URI as it would normally. As the 379 redirection URI uses a custom scheme it results in the operating 380 system launching the native app, passing in the URI as a launch 381 parameter. The native app then processes the authorization response 382 like normal. 384 7.2. Claimed HTTPS URI Redirection 386 Some operating systems allow apps to claim HTTPS scheme [RFC7230] 387 URIs in domains they control. When the browser encounters a claimed 388 URI, instead of the page being loaded in the browser, the native app 389 is launched with the URI supplied as a launch parameter. 391 Such URIs can be used as redirect URIs by native apps. They are 392 indistinguishable to the authorization server from a regular web- 393 based client redirect URI. An example is: 395 https://app.example.com/oauth2redirect/example-provider 397 As the redirect URI alone is not enough to distinguish public native 398 app clients from confidential web clients, it is REQUIRED in 399 Section 8.4 that the client type be recorded during client 400 registration to enable the server to determine the client type and 401 act accordingly. 403 App-claimed HTTPS redirect URIs have some advantages compared to 404 other native app redirect options in that the identity of the 405 destination app is guaranteed to the authorization server by the 406 operating system. For this reason, native apps SHOULD use them over 407 the other options where possible. 409 7.3. Loopback Interface Redirection 411 Native apps that are able to open a port on the loopback network 412 interface without needing special permissions (typically, those on 413 desktop operating systems) can use the loopback interface to receive 414 the OAuth redirect. 416 Loopback redirect URIs use the HTTP scheme and are constructed with 417 the loopback IP literal and whatever port the client is listening on. 418 That is, "http://127.0.0.1:{port}/{path}" for IPv4, and 419 "http://[::1]:{port}/{path}" for IPv6. An example redirect using the 420 IPv4 loopback interface with a randomly assigned port: 422 http://127.0.0.1:50719/oauth2redirect/example-provider 424 An example redirect using the IPv6 loopback interface with a randomly 425 assigned port: 427 http://[::1]:61023/oauth2redirect/example-provider 429 The authorization server MUST allow any port to be specified at the 430 time of the request for loopback IP redirect URIs, to accommodate 431 clients that obtain an available ephemeral port from the operating 432 system at the time of the request. 434 Clients SHOULD NOT assume the device supports a particular version of 435 the Internet Protocol. It is RECOMMENDED that clients attempt to 436 bind to the loopback interface using both IPv4 and IPv6, and use 437 whichever is available. 439 8. Security Considerations 441 8.1. Protecting the Authorization Code 443 The redirect URI options documented in Section 7 share the benefit 444 that only a native app on the same device can receive the 445 authorization code which limits the attack surface, however code 446 interception by a different native app running on the same device may 447 be possible. 449 A limitation of using private-use URI schemes for redirect URIs is 450 that multiple apps can typically register the same scheme, which 451 makes it indeterminate as to which app will receive the Authorization 452 Code. Section 1 of PKCE [RFC7636] details how this limitation can be 453 used to execute a code interception attack. 455 Loopback IP based redirect URIs may be susceptible to interception by 456 other apps accessing the same loopback interface on some operating 457 systems. 459 App-claimed HTTPS redirects are less susceptible to URI interception 460 due to the presence of the URI authority, but they are still public 461 clients and the URI is sent using the operating system's URI dispatch 462 handler with unknown security properties. 464 The Proof Key for Code Exchange by OAuth Public Clients (PKCE 465 [RFC7636]) standard was created specifically to mitigate against this 466 attack. It is a proof of possession extension to OAuth 2.0 that 467 protects the code grant from being used if it is intercepted. It 468 achieves this by having the client generate a secret verifier, a hash 469 of which it passes in the initial authorization request, and which it 470 must present in full when redeeming the authorization code grant. An 471 app that intercepted the authorization code would not be in 472 possession of this secret, rendering the code useless. 474 Section 6 requires that both clients and servers use PKCE for public 475 native app clients. Authorization servers SHOULD reject 476 authorization requests from native apps that don't use PKCE by 477 returning an error message as defined in Section 4.4.1 of PKCE 478 [RFC7636]. 480 8.2. OAuth Implicit Grant Authorization Flow 482 The OAuth 2.0 implicit grant authorization flow as defined in 483 Section 4.2 of OAuth 2.0 [RFC6749] generally works with the practice 484 of performing the authorization request in the browser, and receiving 485 the authorization response via URI-based inter-app communication. 486 However, as the implicit flow cannot be protected by PKCE [RFC7636] 487 (which is a required in Section 8.1), the use of the Implicit Flow 488 with native apps is NOT RECOMMENDED. 490 Tokens granted via the implicit flow also cannot be refreshed without 491 user interaction, making the authorization code grant flow - which 492 can issue refresh tokens - the more practical option for native app 493 authorizations that require refreshing. 495 8.3. Loopback Redirect Considerations 497 Loopback interface redirect URIs use the "http" scheme (i.e., without 498 TLS). This is acceptable for loopback interface redirect URIs as the 499 HTTP request never leaves the device. 501 Clients should open the network port only when starting the 502 authorization request, and close it once the response is returned. 504 Clients should listen on the loopback network interface only, to 505 avoid interference by other network actors. 507 While redirect URIs using localhost (i.e., 508 "http://localhost:{port}/") function similarly to loopback IP 509 redirects described in Section 7.3, the use of "localhost" is NOT 510 RECOMMENDED. Specifying a redirect URI with the loopback IP literal 511 rather than localhost avoids inadvertently listening on network 512 interfaces other than the loopback interface. It is also less 513 susceptible to client side firewalls, and misconfigured host name 514 resolution on the user's device. 516 8.4. Registration of Native App Clients 518 Native apps, except when using a mechanism like Dynamic Client 519 Registration [RFC7591] to provision per-instance secrets, are 520 classified as public clients, as defined by Section 2.1 of OAuth 2.0 521 [RFC6749] and MUST be registered with the authorization server as 522 such. Authorization servers MUST record the client type in the 523 client registration details in order to identify and process requests 524 accordingly. 526 Authorization servers MUST require clients to register their complete 527 redirect URI (including the path component), and reject authorization 528 requests that specify a redirect URI that doesn't exactly match the 529 one that was registered, with the exception of loopback redirects, 530 where an exact match is required except for the port URI component. 532 For private-use URI scheme based redirects, authorization servers 533 SHOULD enforce the requirement in Section 7.1 that clients use 534 reverse domain name based schemes. At a minimum, any scheme that 535 doesn't contain a period character ("."), SHOULD be rejected. 537 In addition to the collision resistant properties, requiring a URI 538 scheme based on a domain name that is under the control of the app 539 can help to prove ownership in the event of a dispute where two apps 540 claim the same private-use URI scheme (where one app is acting 541 maliciously). For example, if two apps claimed "com.example.app", 542 the owner of "example.com" could petition the app store operator to 543 remove the counterfeit app. Such a petition is harder to prove if a 544 generic URI scheme was used. 546 Authorization servers MAY request the inclusion of other platform- 547 specific information, such as the app package or bundle name, or 548 other information used to associate the app that may be useful for 549 verifying the calling app's identity, on operating systems that 550 support such functions. 552 8.5. 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 shared secret. For this 557 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 558 RECOMMENDED for authorization servers to require client 559 authentication of public native apps clients using a shared secret, 560 as this serves little value beyond client identification which is 561 already provided by the "client_id" request parameter. 563 Authorization servers that still require a statically included shared 564 secret for native app clients MUST treat the client as a public 565 client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not 566 accept the secret as proof of the client's identity. Without 567 additional measures, such clients are subject to client impersonation 568 (see Section 8.6). 570 8.6. Client Impersonation 572 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 573 server SHOULD NOT process authorization requests automatically 574 without user consent or interaction, except when the identity of the 575 client can be assured. This includes the case where the user has 576 previously approved an authorization request for a given client id - 577 unless the identity of the client can be proven, the request SHOULD 578 be processed as if no previous request had been approved. 580 Measures such as claimed HTTPS redirects MAY be accepted by 581 authorization servers as identity proof. Some operating systems may 582 offer alternative platform-specific identity features which MAY be 583 accepted, as appropriate. 585 8.7. Fake External User-Agent 587 The native app which is initiating the authorization request has a 588 large degree of control over the user interface and can potentially 589 present a fake external user-agent, that is, an embedded user-agent 590 made to appear as an external user agent. 592 The advantage when all good actors are using external user-agents is 593 that it is possible for security experts to detect bad actors, as 594 anyone faking an external user-agent is provably bad. If good and 595 bad actors alike are using embedded user-agents, bad actors don't 596 need to fake anything, making them harder to detect. Once malicious 597 apps are detected, it may be possible to use this knowledge to 598 blacklist the apps signatures in malware scanning software, take 599 removal action in the case of apps distributed by app stores, and 600 other steps to reduce the impact and spread of the malicious app. 602 Authorization servers can also directly protect against fake external 603 user-agents by requiring an authentication factor only available to 604 true external user-agents. 606 Users who are particularly concerned about their security when using 607 in-app browser tabs may also take the additional step of opening the 608 request in the full browser from the in-app browser tab, and complete 609 the authorization there, as most implementations of the in-app 610 browser tab pattern offer such functionality. 612 8.8. Malicious External User-Agent 614 If a malicious app is able to configure itself as the default handler 615 for "https" scheme URIs in the operating system, it will be able to 616 intercept authorization requests that use the default browser and 617 abuse this position of trust for malicious ends such as phishing the 618 user. 620 Many operating systems mitigate this issue by requiring an explicit 621 user action to change the default handler for HTTP URIs. This attack 622 is not confined to OAuth for Native Apps, a malicious app configured 623 in this way would present a general and ongoing risk to the user 624 beyond OAuth usage. 626 8.9. Cross-App Request Forgery Protections 628 Section 5.3.5 of [RFC6819] recommends using the "state" parameter to 629 link client requests and responses to prevent CSRF (Cross Site 630 Request Forgery) attacks. 632 To mitigate CSRF style attacks using inter-app URI communication, it 633 is similarly RECOMMENDED that native apps include a high entropy 634 secure random number in the "state" parameter of the authorization 635 request, and reject any incoming authorization responses without a 636 state value that matches a pending outgoing authorization request. 638 8.10. Authorization Server Mix-Up Mitigation 640 To protect against a compromised or malicious authorization server 641 attacking another authorization server used by the same app, it is 642 REQUIRED that a unique redirect URI is used for each authorization 643 server used by the app (for example, by varying the path component), 644 and that authorization responses are rejected if the redirect URI 645 they were received on doesn't match the redirect URI in a outgoing 646 authorization request. 648 The native app MUST store the redirect URI used in the authorization 649 request with the authorization session data (i.e., along with "state" 650 and other related data), and MUST verify that the URI on which the 651 authorization response was received exactly matches it. 653 The requirements of Section 8.4 that authorization servers reject 654 requests with URIs that don't match what was registered are also 655 required to prevent such attacks. 657 8.11. Non-Browser External User-Agents 659 This best practice recommends a particular type of external user- 660 agent, the user's browser. Other external user-agent patterns may 661 also be viable for secure and usable OAuth. This document makes no 662 comment on those patterns. 664 8.12. Embedded User-Agents 666 OAuth 2.0 [RFC6749] Section 9 documents two approaches for native 667 apps to interact with the authorization endpoint. This best current 668 practice requires that native apps MUST NOT use embedded user-agents 669 to perform authorization requests, and allows that authorization 670 endpoints MAY take steps to detect and block authorization requests 671 in embedded user-agents. The security considerations for these 672 requirements are detailed herein. 674 Embedded user-agents are an alternative method for authorizing native 675 apps. These embedded user agents are unsafe for use by third-parties 676 to the authorization server by definition, as the app that hosts the 677 embedded user-agent can access the user's full authentication 678 credential, not just the OAuth authorization grant that was intended 679 for the app. 681 In typical web-view based implementations of embedded user-agents, 682 the host application can: log every keystroke entered in the form to 683 capture usernames and passwords; automatically submit forms and 684 bypass user-consent; copy session cookies and use them to perform 685 authenticated actions as the user. 687 Even when used by trusted apps belonging to the same party as the 688 authorization server, embedded user-agents violate the principle of 689 least privilege by having access to more powerful credentials than 690 they need, potentially increasing the attack surface. 692 Encouraging users to enter credentials in an embedded user-agent 693 without the usual address bar and visible certificate validation 694 features that browsers have makes it impossible for the user to know 695 if they are signing in to the legitimate site, and even when they 696 are, it trains them that it's OK to enter credentials without 697 validating the site first. 699 Aside from the security concerns, embedded user-agents do not share 700 the authentication state with other apps or the browser, requiring 701 the user to login for every authorization request which is often 702 considered an inferior user experience. 704 9. IANA Considerations 706 [RFC Editor: please do NOT remove this section.] 708 This document has no IANA actions. 710 Section 7.1 specifies how private-use URI schemes are used for inter- 711 app communication in OAuth protocol flows. This document requires in 712 Section 7.1 that such schemes are based on domain names owned or 713 assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per 714 Section 6 of [RFC7595], registration of domain based URI schemes with 715 IANA is not required. 717 10. References 719 10.1. Normative References 721 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 722 Requirement Levels", BCP 14, RFC 2119, 723 DOI 10.17487/RFC2119, March 1997, 724 . 726 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 727 Resource Identifier (URI): Generic Syntax", STD 66, 728 RFC 3986, DOI 10.17487/RFC3986, January 2005, 729 . 731 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 732 RFC 6749, DOI 10.17487/RFC6749, October 2012, 733 . 735 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 736 Protocol (HTTP/1.1): Message Syntax and Routing", 737 RFC 7230, DOI 10.17487/RFC7230, June 2014, 738 . 740 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 741 and Registration Procedures for URI Schemes", BCP 35, 742 RFC 7595, DOI 10.17487/RFC7595, June 2015, 743 . 745 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 746 for Code Exchange by OAuth Public Clients", RFC 7636, 747 DOI 10.17487/RFC7636, September 2015, 748 . 750 10.2. Informative References 752 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 753 Threat Model and Security Considerations", RFC 6819, 754 DOI 10.17487/RFC6819, January 2013, 755 . 757 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 758 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 759 RFC 7591, DOI 10.17487/RFC7591, July 2015, 760 . 762 [AppAuth] Denniss, W., Wright, S., McGinniss, I., Ravikumar, R., and 763 others, "AppAuth", May 22, . 765 [AppAuth.iOSmacOS] 766 Wright, S., Denniss, W., and others, "AppAuth for iOS and 767 macOS", February 2016, . 770 [AppAuth.Android] 771 McGinniss, I., Denniss, W., and others, "AppAuth for 772 Android", February 2016, . 775 [SamplesForWindows] 776 Denniss, W., "OAuth for Apps: Samples for Windows", July 777 2016, . 780 Appendix A. Server Support Checklist 782 OAuth servers that support native apps must: 784 1. Support private-use URI scheme redirect URIs. This is required 785 to support mobile operating systems. See Section 7.1. 787 2. Support HTTPS scheme redirect URIs for use with public native app 788 clients. This is used by apps on advanced mobile operating 789 systems that allow app-claimed URIs. See Section 7.2. 791 3. Support loopback IP redirect URIs. This is required to support 792 desktop operating systems. See Section 7.3. 794 4. Not assume native app clients can keep a secret. If secrets are 795 distributed to multiple installs of the same native app, they 796 should not be treated as confidential. See Section 8.5. 798 5. Support PKCE [RFC7636]. Required to protect authorization code 799 grants sent to public clients over inter-app communication 800 channels. See Section 8.1 802 Appendix B. Operating System Specific Implementation Details 804 This document primarily defines best practices in a generic manner, 805 referencing techniques commonly available in a variety of 806 environments. This non-normative section documents operating system 807 specific implementation details of the best practice. 809 The implementation details herein are considered accurate at the time 810 of publishing but will likely change over time. It is hoped that 811 such change won't invalidate the generic principles in the rest of 812 the document, and those principles should take precedence in the 813 event of a conflict. 815 B.1. iOS Implementation Details 817 Apps can initiate an authorization request in the browser without the 818 user leaving the app, through the SFSafariViewController class which 819 implements the in-app browser tab pattern. Safari can be used to 820 handle requests on old versions of iOS without 821 SFSafariViewController. 823 To receive the authorization response, both private-use URI scheme 824 redirects (referred to as Custom URL Schemes) and claimed HTTPS links 825 (known as Universal Links) are viable choices, and function the same 826 whether the request is loaded in SFSafariViewController or the Safari 827 app. Apps can claim Custom URI schemes with the "CFBundleURLTypes" 828 key in the application's property list file "Info.plist", and HTTPS 829 links using the Universal Links feature with an entitlement file and 830 an association file on the domain. 832 Universal Links are the preferred choice on iOS 9 and above due to 833 the ownership proof that is provided by the operating system. 835 A complete open source sample is included in the AppAuth for iOS and 836 macOS [AppAuth.iOSmacOS] library. 838 B.2. Android Implementation Details 840 Apps can initiate an authorization request in the browser without the 841 user leaving the app, through the Android Custom Tab feature which 842 implements the in-app browser tab pattern. The user's default 843 browser can be used to handle requests when no browser supports 844 Custom Tabs. 846 Android browser vendors should support the Custom Tabs protocol (by 847 providing an implementation of the "CustomTabsService" class), to 848 provide the in-app browser tab user experience optimization to their 849 users. Chrome is one such browser that implements Custom Tabs. 851 To receive the authorization response, private-use URI schemes are 852 broadly supported through Android Implicit Intents. Claimed HTTPS 853 redirect URIs through Android App Links are available on Android 6.0 854 and above. Both types of redirect URIs are registered in the 855 application's manifest. 857 A complete open source sample is included in the AppAuth for Android 858 [AppAuth.Android] library. 860 B.3. Windows Implementation Details 862 Both traditional and Universal Windows Platform (UWP) apps can 863 perform authorization requests in the user's browser. Traditional 864 apps typically use a loopback redirect to receive the authorization 865 response, and listening on the loopback interface is allowed by 866 default firewall rules. When creating the loopback network socket, 867 apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent 868 other apps binding to the same socket. 870 UWP apps can use private-use URI scheme redirects to receive the 871 authorization response from the browser, which will bring the app to 872 the foreground. Known on the platform as "URI Activation", the URI 873 scheme is limited to 39 characters in length, and may include the "." 874 character, making short reverse domain name based schemes (as 875 recommended in Section 7.1) possible. 877 UWP apps can alternatively use the Web Authentication Broker API in 878 SSO (Single Sign-on) mode, which is an external user agent designed 879 for authorization flows. Cookies are shared between invocations of 880 the broker but not the user's preferred browser, meaning the user 881 will need to sign-in again even if they have an active session in 882 their browser, but the session created in the broker will be 883 available to subsequent apps that use the broker. Personalisations 884 the user has made to their browser, such as configuring a password 885 manager may not available in the broker. To qualify as an external 886 user-agent, the broker MUST be used in SSO mode. 888 To use the Web Authentication Broker in SSO mode, the redirect URI 889 must be of the form "msapp://{appSID}" where "appSID" is the app's 890 SID, which can be found in the app's registration information. While 891 Windows enforces the URI authority on such redirects, ensuring only 892 the app with the matching SID can receive the response on Windows, 893 the URI scheme could be claimed by apps on other platforms without 894 the same authority present, thus this redirect type should be treated 895 similar to private-use URI scheme redirects for security purposes. 897 An open source sample demonstrating these patterns is available 898 [SamplesForWindows]. 900 B.4. macOS Implementation Details 902 Apps can initiate an authorization request in the user's default 903 browser using platform APIs for opening URIs in the browser. 905 To receive the authorization response, private-use URI schemes are a 906 good redirect URI choice on macOS, as the user is returned right back 907 to the app they launched the request from. These are registered in 908 the application's bundle information property list using the 909 "CFBundleURLSchemes" key. Loopback IP redirects are another viable 910 option, and listening on the loopback interface is allowed by default 911 firewall rules. 913 A complete open source sample is included in the AppAuth for iOS and 914 macOS [AppAuth.iOSmacOS] library. 916 B.5. Linux Implementation Details 918 Opening the Authorization Request in the user's default browser 919 requires a distro-specific command, "xdg-open" is one such tool. 921 The loopback redirect is the recommended redirect choice for desktop 922 apps on Linux to receive the authorization response. Apps SHOULD NOT 923 set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options, to prevent 924 other apps binding to the same socket. 926 Appendix C. Acknowledgements 928 The author would like to acknowledge the work of Marius Scurtescu, 929 and Ben Wiley Sittler whose design for using private-use URI schemes 930 in native OAuth 2.0 clients at Google formed the basis of 931 Section 7.1. 933 The following individuals contributed ideas, feedback, and wording 934 that shaped and formed the final specification: 936 Andy Zmolek, Steven E Wright, Brian Campbell, Nat Sakimura, Eric 937 Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de 938 Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill 939 Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick 940 Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn 941 Davies. 943 Authors' Addresses 945 William Denniss 946 Google 947 1600 Amphitheatre Pkwy 948 Mountain View, CA 94043 949 USA 951 Email: wdenniss@google.com 952 URI: http://wdenniss.com/appauth 953 John Bradley 954 Ping Identity 956 Phone: +1 202-630-5272 957 Email: ve7jtb@ve7jtb.com 958 URI: http://www.thread-safe.com/p/appauth.html