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