idnits 2.17.00 (12 Aug 2021) /tmp/idnits50489/draft-ietf-oauth-native-apps-04.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 12, 2016) is 2046 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 (~~), 1 warning (==), 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: April 15, 2017 Ping Identity 6 October 12, 2016 8 OAuth 2.0 for Native Apps 9 draft-ietf-oauth-native-apps-04 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 April 15, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 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 . . . . . . . . . . . . . . . . 8 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 8.1. Embedded User-Agents . . . . . . . . . . . . . . . . . . 9 66 8.2. Protecting the Authorization Code . . . . . . . . . . . . 10 67 8.3. Loopback Redirect Considerations . . . . . . . . . . . . 11 68 8.4. Registration of App Redirection URIs . . . . . . . . . . 11 69 8.5. OAuth Implicit Flow . . . . . . . . . . . . . . . . . . . 11 70 8.6. Phishability of In-App Browser Tabs . . . . . . . . . . . 12 71 8.7. Limitations of Non-verifiable Clients . . . . . . . . . . 12 72 8.8. Non-Browser External User Agents . . . . . . . . . . . . 12 73 8.9. Client Authentication . . . . . . . . . . . . . . . . . . 13 74 8.10. Cross-App Request Forgery Protections . . . . . . . . . . 13 75 8.11. Authorization Server Mix-Up Mitigation . . . . . . . . . 13 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 79 10.2. Informative References . . . . . . . . . . . . . . . . . 14 80 Appendix A. Server Support Checklist . . . . . . . . . . . . . . 15 81 Appendix B. Operating System Specific Implementation Details . . 15 82 B.1. iOS Implementation Details . . . . . . . . . . . . . . . 16 83 B.2. Android Implementation Details . . . . . . . . . . . . . 16 84 B.3. Windows Implementation Details . . . . . . . . . . . . . 16 85 B.4. macOS Implementation Details . . . . . . . . . . . . . . 17 86 B.5. Linux Implementation Details . . . . . . . . . . . . . . 17 87 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 17 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 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, or an external user- 95 agent. 97 This best current practice recommends 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 "app" Shorthand for "native app". 130 "app store" An ecommerce store where users can download and purchase 131 apps. 133 "authz" Abbreviation of "authorization". 135 "browser" The operating system's default browser, pre-installed as 136 part of the operating system, or installed and set as default by 137 the user. 139 "browser tab" An open page of the browser. Browser typically have 140 multiple "tabs" representing various open pages. 142 "in-app browser tab" A full page browser with limited navigation 143 capabilities that is displayed inside a host app, but retains the 144 full security properties and authentication state of the browser. 146 Has different platform-specific product names, such as 147 SFSafariViewController on iOS, and Chrome Custom Tab on Android. 149 "inter-app communication" Communication between two apps on a 150 device. 152 "claimed HTTPS URL" Some platforms allow apps to claim a HTTPS URL 153 after proving ownership of the domain name. URLs claimed in such 154 a way are then opened in the app instead of the browser. 156 "custom URI scheme" A URI scheme (as defined by [RFC3986]) that the 157 app creates and registers with the OS (and is not a standard URI 158 scheme like "https:" or "tel:"). Requests to such a scheme 159 results in the app which registered it being launched by the OS. 161 "web-view" A web browser UI component that can be embedded in apps 162 to render web pages, used to create embedded user-agents. 164 "reverse domain name notation" A naming convention based on the 165 domain name system, but where where the domain components are 166 reversed, for example "app.example.com" becomes "com.example.app". 168 4. Overview 170 The best current practice for authorizing users in native apps is to 171 perform the OAuth authorization request in a browser (an external 172 user-agent), rather than web-view (an embedded user-agent). 174 Previously it was common for native apps to use web-views for OAuth 175 authorization requests. That approach has many drawbacks, typically 176 including the host app being able to copy user credentials and 177 cookies, and the user needing to authenticate from scratch in each 178 app. See Section 8.1 for a deeper analysis of using embedded user- 179 agents for OAuth. 181 Native app authorization requests that use the browser are more 182 secure and can take advantage of the user's authentication state. 183 Being able to use the existing authentication session in the browser 184 enables single sign-on, as users don't need to authenticate to the 185 authorization server each time they use a new app (unless required by 186 authorization server policy). 188 Supporting authorization flows between a native app and the browser 189 is possible without changing the OAuth protocol itself, as the 190 authorization request and response are already defined in terms of 191 URIs, which emcompasses URIs that can be used for inter-process 192 communication. Some OAuth server implementations that assume all 193 clients are confidential web-clients will need to add an 194 understanding of native app OAuth clients and the types of redirect 195 URIs they use to support this best practice. 197 4.1. Authorization Flow for Native Apps Using the Browser 199 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 200 | User Device | 201 | | 202 | +---------------------------+ | +-----------+ 203 | | | | (5) Authz Code | | 204 | | Client App |----------------------->| Token | 205 | | |<-----------------------| Endpoint | 206 | +---------------------------+ | (6) Access Token, | | 207 | | ^ | Refresh Token +-----------+ 208 | | | | 209 | | | | 210 | | (1) | (4) | 211 | | Authz | Authz | 212 | | Request | Code | 213 | | | | 214 | | | | 215 | v | | 216 | +---------------------------+ | +---------------+ 217 | | | | (2) Authz Request | | 218 | | Browser |--------------------->| Authorization | 219 | | |<---------------------| Endpoint | 220 | +---------------------------+ | (3) Authz Code | | 221 | | +---------------+ 222 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ 224 Figure 1: Native App Authorization via External User-agent 226 Figure 1 illustrates the interaction of the native app with the 227 system browser to authorize the user via an external user-agent. 229 1) The client app opens a browser tab with the authorization request. 231 2) Authorization endpoint receives the authorization request, 232 authenticates the user and obtains authorization. Authenticating 233 the user may involve chaining to other authentication systems. 235 3) Authorization server issues an authorization code to the redirect 236 URI. 238 4) Client receives the authorization code from the redirect URI. 240 5) Client app presents the authorization code at the token endpoint. 242 6) Token endpoint validates the authorization code and issues the 243 tokens requested. 245 5. Using Inter-app URI Communication for OAuth 247 Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate 248 the authorization request and return the authorization response to 249 the requesting website, URIs can be used by native apps to initiate 250 the authorization request in the device's browser and return the 251 response to the requesting native app. 253 By applying the same principles from the web to native apps, we gain 254 similar benefits like the usability of a single sign-on session, and 255 the security of a separate authentication context. It also reduces 256 the implementation complexity by reusing the same flows as the web, 257 and increases interoperability by relying on standards-based web 258 flows that are not specific to a particular platform. 260 Native apps MUST use an external user-agent to perform OAuth 261 authentication requests. This is achieved by opening the 262 authorization request in the browser (detailed in Section 6), and 263 using a redirect URI that will return the authorization response back 264 to the native app, as defined in Section 7. 266 This best practice focuses on the browser as the RECOMMENDED external 267 user-agent for native apps. Other external user-agents, such as a 268 native app provided by the authorization server may meet the criteria 269 set out in this best practice, including using the same redirection 270 URI properties, but their use is out of scope for this specification. 271 options for inter-app communication, offering similar security 273 6. Initiating the Authorization Request from a Native App 275 The authorization request is created as per OAuth 2.0 [RFC6749], and 276 opened in the user's browser using platform-specific APIs for that 277 purpose. 279 The function of the redirect URI for a native app authorization 280 request is similar to that of a web-based authorization request. 281 Rather than returning the authorization response to the OAuth 282 client's server, the redirect URI used by a native app returns the 283 response to the app. The various options for a redirect URI that 284 will return the code to the native app are documented in Section 7. 285 Any redirect URI that allows the app to receive the URI and inspect 286 its parameters is viable. 288 Some platforms support a browser feature known as in-app browser 289 tabs, where an app can present a tab of the browser within the app 290 context without switching apps, but still retain key benefits of the 291 browser such as a shared authentication state and security context. 292 On platforms where they are supported, it is RECOMMENDED for 293 usability reasons that apps use in-app browser tabs for the 294 Authorization Request. 296 7. Receiving the Authorization Response in a Native App 298 There are several redirect URI options available to native apps for 299 receiving the authorization response from the browser, the 300 availability and user experience of which varies by platform. 302 To fully support this best practice, authorization servers MUST 303 support the following three redirect URI options. Native apps MAY 304 use whichever redirect option suits their needs best, taking into 305 account platform specific implementation details. 307 7.1. App-declared Custom URI Scheme Redirection 309 Many mobile and desktop computing platforms support inter-app 310 communication via URIs by allowing apps to register custom URI 311 schemes, like "com.example.app:". When the browser or another app 312 attempts to load a URI with a custom scheme, the app that registered 313 it is launched to handle the request. 315 To perform an OAuth 2.0 Authorization Request on a supported 316 platform, the native app launches the browser with a normal OAuth 2.0 317 Authorization Request, but provides a redirection URI that utilizes a 318 custom URI scheme registered with the operating system by the calling 319 app. 321 When the authentication server completes the request, it redirects to 322 the client's redirection URI like it would any redirect URI, but as 323 the redirection URI uses a custom scheme, this results in the OS 324 launching the native app passing in the URI. The native app then 325 processes the authorization response like any OAuth client. 327 7.1.1. Custom URI Scheme Namespace Considerations 329 When choosing a URI scheme to associate with the app, apps MUST use a 330 URI scheme based on a domain name under their control, expressed in 331 reverse order, as recommended by Section 3.8 of [RFC7595] for 332 private-use URI schemes. 334 For example, an app that controls the domain name "app.example.com" 335 can use "com.example.app:/" as their custom scheme. Some 336 authorization servers assign client identifiers based on domain 337 names, for example "client1234.usercontent.example.net", which can 338 also be used as the domain name for the custom scheme, when reversed 339 in the same manner, for example "net.example.usercontent.client1234". 341 URI schemes not based on a domain name (for example "myapp:/") MUST 342 NOT be used, as they are not collision resistant, and don't comply 343 with Section 3.8 of [RFC7595]. 345 Care must be taken when there are multiple apps by the same publisher 346 that each URI scheme is unique within that group. On platforms that 347 use app identifiers that are also based on reverse order domain 348 names, those can be re-used as the custom URI scheme for the OAuth 349 redirect. 351 In addition to the collision resistant properties, basing the URI 352 scheme off a domain name that is under the control of the app can 353 help to prove ownership in the event of a dispute where two apps 354 claim the same custom scheme (such as if an app is acting 355 maliciously). For example, if two apps claimed "com.example.app:", 356 the owner of "example.com" could petition the app store operator to 357 remove the counterfeit app. This petition is harder to prove if a 358 generic URI scheme was used. 360 7.2. App-claimed HTTPS URI Redirection 362 Some operating systems allow apps to claim HTTPS URLs in their 363 domains. When the browser encounters a claimed URL, instead of the 364 page being loaded in the browser, the native app is launched instead 365 with the URL supplied as input. 367 App-claimed HTTPS redirect URIs have some advantages in that the 368 identity of the destination app is guaranteed by the operating 369 system. Due to this reason, they SHOULD be used over the other 370 redirect choices for native apps where possible. 372 App-claimed HTTPS redirect URIs function exactly as normal HTTPS 373 redirects from the perspective of the authorization server, though it 374 is RECOMMENDED that the authorization server is able to distinguish 375 between public native app clients that use app-claimed HTTPS redirect 376 URIs and confidential web clients. A flag in the client registration 377 information that indicates a public native app client is one such 378 method for distinguishing client types. 380 7.3. Loopback URI Redirection 382 Desktop operating systems allow native apps to listen on a local port 383 for HTTP redirects. This can be used by native apps to receive OAuth 384 authorization responses on compatible platforms. 386 Loopback redirect URIs take the form of the loopback IP, any port 387 (dynamically provided by the client), and a path component. 388 Specifically: "http://127.0.0.1:{port}/{path}", and 389 "http://[::1]:{port}/{path}". 391 For loopback IP redirect URIs, the authorization server MUST allow 392 any port to be specified at the time of the request, to accommodate 393 clients that obtain an available port from the operating system at 394 the time of the request. Other than that, the redirect is be treated 395 like any other. 397 8. Security Considerations 399 8.1. Embedded User-Agents 401 Embedded user-agents, commonly implemented with web-views, are an 402 alternative method for authorizing native apps. They are however 403 unsafe for use by third-parties by definition. They involve the user 404 signing in with their full login credentials, only to have them 405 downscoped to less powerful OAuth credentials. 407 Even when used by trusted first-party apps, embedded user-agents 408 violate the principle of least privilege by obtaining more powerful 409 credentials than they need, potentially increasing the attack 410 surface. 412 In typical web-view based implementations of embedded user-agents, 413 the host application can: log every keystroke entered in the form to 414 capture usernames and passwords; automatically submit forms and 415 bypass user-consent; copy session cookies and use them to perform 416 authenticated actions as the user. 418 Encouraging users to enter credentials in an embedded web-view 419 without the usual address bar and visible certificate validation 420 features that browsers have makes it impossible for the user to know 421 if they are signing in to the legitimate site, and even when they 422 are, it trains them that it's OK to enter credentials without 423 validating the site first. 425 Aside from the security concerns, web-views do not share the 426 authentication state with other apps or the browser, requiring the 427 user to login for every authorization request and leading to a poor 428 user experience. 430 Native apps MUST NOT use embedded user-agents for OAuth to third- 431 parties. 433 Authorization servers MAY take steps to detect and block 434 authorization requests in third-party embedded user-agents. 436 8.2. Protecting the Authorization Code 438 The redirect URI options documented in Section 7 share the benefit 439 that only a native app on the same device can receive the 440 authorization code, however code interception by a native app other 441 than the intended recipient may be possible. 443 A limitation of using custom URI schemes for redirect URIs is that 444 multiple apps can typically register the same scheme, which makes it 445 indeterminate as to which app will receive the Authorization Code 446 Grant. This is not an issue for HTTPS redirection URIs (i.e. 447 standard web URLs) due to the fact the HTTPS URI scheme is enforced 448 by the authority (as defined by [RFC3986]), the domain name system, 449 which does not allow multiple entities to own the same domain. 451 If multiple apps register the same scheme, it is possible that the 452 authorization code will be sent to the wrong app (generally the 453 operating system makes no guarantee of which app will handle the URI 454 when multiple register the same scheme). PKCE [RFC7636] details how 455 this limitation can be used to execute a code interception attack 456 (see Figure 1). This attack vector applies to public clients 457 (clients that are unable to maintain a client secret) which is 458 typical of most native apps. 460 While Section 7.1.1 details ways that this can be mitigated through 461 policy enforcement (through being able to report and have removed any 462 offending apps), we can also protect the authorization code grant 463 from being used in cases where it was intercepted. 465 The Proof Key for Code Exchange by OAuth Public Clients (PKCE 466 [RFC7636]) standard was created specifically to mitigate against this 467 attack. It is a Proof of Possession extension to OAuth 2.0 that 468 protects the code grant from being used if it is intercepted. It 469 achieves this by having the client generate a secret verifier which 470 it passes in the initial authorization request, and which it must 471 present later when redeeming the authorization code grant. An app 472 that intercepted the authorization code would not be in possession of 473 this secret, rendering the code useless. 475 Both the client and the Authorization Server MUST support PKCE 476 [RFC7636] to use custom URI schemes, or loopback IP redirects. 477 Authorization Servers SHOULD reject authorization requests using a 478 custom scheme, or loopback IP as part of the redirection URI if the 479 required PKCE parameters are not present, returning the error message 480 as defined in Section 4.4.1 of PKCE [RFC7636]. It is RECOMMENDED to 481 use PKCE [RFC7636] for app-claimed HTTPS redirect URIs, even though 482 these are not generally subject to interception, to protect against 483 attacks on inter-app communication. 485 8.3. Loopback Redirect Considerations 487 Loopback interface redirect URIs use the "http" scheme (i.e. without 488 TLS). This is acceptable for loopback interface redirect URIs as the 489 HTTP request never leaves the device. 491 Clients should open the loopback port only when starting the 492 authorization request, and close it once the response is returned. 494 While redirect URIs using localhost (i.e. "http://localhost:{port}/" 495 function similarly to loopback IP redirects described in Section 7.3, 496 the use of "localhost" is NOT RECOMMENDED. Opening a port on the 497 loopback interface is more secure as only apps on the local device 498 can connect to it. It is also less susceptible to misconfigured 499 routing, and interference by client side firewalls. 501 8.4. Registration of App Redirection URIs 503 As recommended in Section 3.1.2.2 of OAuth 2.0 [RFC6749], the 504 authorization server SHOULD require the client to pre-register the 505 complete redirection URI. This applies and is RECOMMENDED for all 506 redirection URIs used by native apps. 508 For Custom URI scheme based redirects, authorization servers SHOULD 509 enforce the requirement in Section 7.1.1 that clients use reverse 510 domain name based schemes. 512 Authorization servers MAY request the inclusion of other platform- 513 specific information, such as the app package or bundle name, or 514 other information used to associate the app that may be useful for 515 verifying the calling app's identity, on operating systems that 516 support such functions. 518 8.5. OAuth Implicit Flow 520 The OAuth 2.0 Implicit Flow as defined in Section 4.2 of OAuth 2.0 521 [RFC6749] generally works with the practice of performing the 522 authorization request in the browser, and receiving the authorization 523 response via URI-based inter-app communication. However, as the 524 Implicit Flow cannot be protected by PKCE (which is a recommended in 525 Section 7.1.1), the use of the Implicit Flow with native apps is NOT 526 RECOMMENDED. 528 Tokens granted via the implicit flow also cannot be refreshed without 529 user interaction making the code flow, with refresh tokens the more 530 practical option for native app authorizations that require 531 refreshing. 533 8.6. Phishability of In-App Browser Tabs 535 While in-app browser tabs provide a secure authentication context, as 536 the user initiates the flow from a native app, it is possible for 537 that native app to completely fake an in-app browser tab. 539 This can't be prevented directly - once the user is in the native 540 app, that app is fully in control of what it can render, however 541 there are several mitigating factors. 543 Importantly, such an attack that uses a web-view to fake an in-app 544 browser tab will always start with no authentication state. If all 545 native apps use the techniques described in this best practice, users 546 will not need to sign-in frequently and thus should be suspicious of 547 any sign-in request when they should have already been signed-in. 549 This is the case even for authorization servers that require 550 occasional or frequent re-authentication, as such servers can 551 preserve some user identifiable information from the old session, 552 like the email address or profile picture and display that on the re- 553 authentication. 555 Users who are particularly concerned about their security may also 556 take the additional step of opening the request in the browser from 557 the in-app browser tab, and completing the authorization there, as 558 most implementations of the in-app browser tab pattern offer such 559 functionality. 561 8.7. Limitations of Non-verifiable Clients 563 As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization 564 server SHOULD NOT process authorization requests automatically 565 without user consent or interaction, except when the identity of the 566 client can be assured. Measures such as claimed HTTPS redirects can 567 be used by native apps to prove their identity to the authorization 568 server, and some operating systems may offer alternative platform- 569 specific identity features which may be used, as appropriate. 571 8.8. Non-Browser External User Agents 573 This best practice recommends a particular type of external user- 574 agent, the user's browser. Other external user-agents patterns may 575 also be viable for secure and usable OAuth. This document makes no 576 comment on those patterns. 578 8.9. Client Authentication 580 Secrets that are statically included as part of an app distributed to 581 multiple users should not be treated as confidential secrets, as one 582 user may inspect their copy and learn the shared secret. For this 583 reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT 584 RECOMMENDED for authorization servers to require client 585 authentication of native apps using a shared secret, as this serves 586 little value beyond client identification which is already provided 587 by the "client_id" request parameter. 589 Authorization servers that still require a shared secret for native 590 app clients MUST treat the client as a public client, and not treat 591 the secret as proof of the client's identity. In those cases, it is 592 NOT RECOMMENDED to automatically issue tokens on the basis that the 593 user has previously granted access to the same client, as there is no 594 guarantee that the client is not counterfeit. 596 8.10. Cross-App Request Forgery Protections 598 Section 5.3.5 of [RFC6819] recommends using the 'state' parameter to 599 link client requests and responses to prevent CSRF attacks. 601 It is similarly RECOMMENDED for native apps to include a high entropy 602 secure random number in the 'state' parameter of the authorization 603 request, and reject any incoming authorization responses without a 604 state value that matches a pending outgoing authorization request. 606 8.11. Authorization Server Mix-Up Mitigation 608 To protect against a compromised or malicious authorization server 609 attacking another authorization server used by the same app, it is 610 RECOMMENDED that a unique redirect URI is used for each different 611 authorization server used by the app (for example, by varying the 612 path component), and that authorization responses are rejected if the 613 redirect URI they were received on doesn't match the redirect URI in 614 a pending outgoing authorization request. 616 Authorization servers SHOULD allow the registration of a specific 617 redirect URI, including path components, and reject authorization 618 requests that specify a redirect URI that doesn't exactly match the 619 one that was registered. 621 9. IANA Considerations 623 [RFC Editor: please do not remove this section.] 625 Section 7.1 specifies how private-use URI schemes are used for inter- 626 app communication in OAuth protocol flows. This document requires in 627 Section 7.1.1 that such schemes are based on domain names owned or 628 assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per 629 section 6 of [RFC7595], registration of domain based URI schemes with 630 IANA is not required. Therefore, this document has no IANA actions. 632 10. References 634 10.1. Normative References 636 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 637 Requirement Levels", BCP 14, RFC 2119, 638 DOI 10.17487/RFC2119, March 1997, 639 . 641 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 642 Resource Identifier (URI): Generic Syntax", STD 66, 643 RFC 3986, DOI 10.17487/RFC3986, January 2005, 644 . 646 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 647 RFC 6749, DOI 10.17487/RFC6749, October 2012, 648 . 650 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 651 and Registration Procedures for URI Schemes", BCP 35, 652 RFC 7595, DOI 10.17487/RFC7595, June 2015, 653 . 655 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 656 for Code Exchange by OAuth Public Clients", RFC 7636, 657 DOI 10.17487/RFC7636, September 2015, 658 . 660 10.2. Informative References 662 [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 663 Threat Model and Security Considerations", RFC 6819, 664 DOI 10.17487/RFC6819, January 2013, 665 . 667 [AppAuth.iOSmacOS] 668 Wright, S., Denniss, W., and others, "AppAuth for iOS and 669 macOS", February 2016, . 672 [AppAuth.Android] 673 McGinniss, I., Denniss, W., and others, "AppAuth for 674 Android", February 2016, . 677 [SamplesForWindows] 678 Denniss, W., "OAuth for Apps: Samples for Windows", July 679 2016, . 682 Appendix A. Server Support Checklist 684 OAuth servers that support native apps should: 686 1. Support custom URI-scheme redirect URIs. This is required to 687 support mobile operating systems. See Section 7.1. 689 2. Support HTTPS redirect URIs for use with public native app 690 clients. This is used by apps on advanced mobile operating 691 systems that allow app-claimed HTTPS URIs. See Section 7.2. 693 3. Support loopback IP redirect URIs. This is required to support 694 desktop operating systems. See Section 7.3. 696 4. Not assume native app clients can keep a secret. If secrets are 697 distributed to multiple installs of the same native app, they 698 should not be treated as confidential. See Section 8.9. 700 5. Support PKCE. Recommended to protect authorization code grants 701 transmitted to public clients over inter-app communication 702 channels. See Section 8.2 704 Appendix B. Operating System Specific Implementation Details 706 Most of this document defines best practices in an generic manner, 707 referencing techniques commonly available in a variety of 708 environments. This non-normative section contains OS-specific 709 implementation details for the generic pattern, that are considered 710 accurate at the time of publishing, but may change over time. 712 It is expected that this OS-specific information will change, but 713 that the overall principles described in this document for using 714 external user-agents will remain valid. 716 B.1. iOS Implementation Details 718 Apps can initiate an authorization request in the browser without the 719 user leaving the app, through the SFSafariViewController class which 720 implements the browser-view pattern. Safari can be used to handle 721 requests on old versions of iOS without SFSafariViewController. 723 To receive the authorization response, both custom URI scheme 724 redirects and claimed HTTPS links (known as Universal Links) are 725 viable choices, and function the same whether the request is loaded 726 in SFSafariViewController or the Safari app. Apps can claim Custom 727 URI schemes with the "CFBundleURLTypes" key in the application's 728 property list file "Info.plist", and HTTPS links using the Universal 729 Links feature with an entitlement file and an association file on the 730 domain. 732 Universal Links are the preferred choice on iOS 9 and above due to 733 the ownership proof that is provided by the operating system. 735 A complete open source sample is included in the AppAuth for iOS and 736 macOS [AppAuth.iOSmacOS] library. 738 B.2. Android Implementation Details 740 Apps can initiate an authorization request in the browser without the 741 user leaving the app, through the Android Custom Tab feature which 742 implements the browser-view pattern. The user's default browser can 743 be used to handle requests when no browser supports Custom Tabs. 745 Android browser vendors should support the Custom Tabs protocol (by 746 providing an implementation of the "CustomTabsService" class), to 747 provide the in-app browser tab user experience optimization to their 748 users. Chrome is one such browser that implements Custom Tabs. 750 To receive the authorization response, custom URI schemes are broadly 751 supported through Android Implicit Intends. Claimed HTTPS redirect 752 URIs through Android App Links are available on Android 6.0 and 753 above. Both types of redirect URIs are registered in the 754 application's manifest. 756 A complete open source sample is included in the AppAuth for Android 757 [AppAuth.Android] library. 759 B.3. Windows Implementation Details 761 Apps can initiate an authorization request in the user's default 762 browser using platform APIs for this purpose. 764 The custom URI scheme redirect is a good choice for Universal Windows 765 Platform (UWP) apps as it will open the app returning the user right 766 back where they were. Known on UWP as URI Activation, the scheme is 767 limited to 39 characters, but may include the "." character, making 768 short reverse domain name based schemes (as recommended in 769 Section 7.1.1) possible. 771 The loopback redirect is the common choice for traditional desktop 772 apps, listening on a loopback interface port is permitted by default 773 Windows firewall rules. 775 A complete open source sample is available [SamplesForWindows]. 777 B.4. macOS Implementation Details 779 Apps can initiate an authorization request in the user's default 780 browser using platform APIs for this purpose. 782 To receive the authorization response, custom URI schemes are are a 783 good redirect URI choice on macOS, as the user is returned right back 784 to the app they launched the request from. These are registered in 785 the application's bundle information property list using the 786 "CFBundleURLSchemes" key. Loopback IP redirects are another viable 787 option, and listening on the loopback interface is allowed by default 788 firewall rules. 790 A complete open source sample is included in the AppAuth for iOS and 791 macOS [AppAuth.iOSmacOS] library. 793 B.5. Linux Implementation Details 795 Opening the Authorization Request in the user's default browser 796 requires a distro-specific command, "xdg-open" is one such tool. 798 The loopback redirect is the recommended redirect choice for desktop 799 apps on Linux to receive the authorization response. 801 Appendix C. Acknowledgements 803 The author would like to acknowledge the work of Marius Scurtescu, 804 and Ben Wiley Sittler whose design for using custom URI schemes in 805 native OAuth 2.0 clients formed the basis of Section 7.1. 807 The following individuals contributed ideas, feedback, and wording 808 that shaped and formed the final specification: 810 Andy Zmolek, Steven E Wright, Brian Campbell, Paul Madsen, Nat 811 Sakimura, Iain McGinniss, Rahul Ravikumar, Eric Sachs, Breno de 812 Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill 813 Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Paul 814 Grassi, David Waite, Naveen Agarwal, and Adam Dawes. 816 Authors' Addresses 818 William Denniss 819 Google 820 1600 Amphitheatre Pkwy 821 Mountain View, CA 94043 822 USA 824 Email: wdenniss@google.com 825 URI: http://wdenniss.com/appauth 827 John Bradley 828 Ping Identity 830 Phone: +1 202-630-5272 831 Email: ve7jtb@ve7jtb.com 832 URI: http://www.thread-safe.com/p/appauth.html