Internet Engineering Task Force (IETF)                        W. Denniss
Request for Comments: 8252                                        Google
BCP: 212                                                      J. Bradley
Updates: 6749                                              Ping Identity
Category: Best Current Practice                             October 2017
ISSN: 2070-1721
        
Internet Engineering Task Force (IETF)                        W. Denniss
Request for Comments: 8252                                        Google
BCP: 212                                                      J. Bradley
Updates: 6749                                              Ping Identity
Category: Best Current Practice                             October 2017
ISSN: 2070-1721
        

OAuth 2.0 for Native Apps

用于本机应用程序的OAuth 2.0

Abstract

摘要

OAuth 2.0 authorization requests from native apps should only be made through external user-agents, primarily the user's browser. This specification details the security and usability reasons why this is the case and how native apps and authorization servers can implement this best practice.

来自本机应用程序的OAuth 2.0授权请求只能通过外部用户代理(主要是用户的浏览器)发出。本规范详细说明了出现这种情况的安全性和可用性原因,以及本机应用程序和授权服务器如何实现这种最佳实践。

Status of This Memo

关于下段备忘

This memo documents an Internet Best Current Practice.

本备忘录记录了互联网最佳实践。

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841.

本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。有关BCP的更多信息,请参见RFC 7841第2节。

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8252.

有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问https://www.rfc-editor.org/info/rfc8252.

Copyright Notice

版权公告

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.

版权所有(c)2017 IETF信托基金和确定为文件作者的人员。版权所有。

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(https://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本,并提供简化BSD许可证中所述的无担保。

Table of Contents

目录

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   3
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Authorization Flow for Native Apps Using the Browser  . .   5
   5.  Using Inter-App URI Communication for OAuth . . . . . . . . .   6
   6.  Initiating the Authorization Request from a Native App  . . .   6
   7.  Receiving the Authorization Response in a Native App  . . . .   7
     7.1.  Private-Use URI Scheme Redirection  . . . . . . . . . . .   8
     7.2.  Claimed "https" Scheme URI Redirection  . . . . . . . . .   9
     7.3.  Loopback Interface Redirection  . . . . . . . . . . . . .   9
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
     8.1.  Protecting the Authorization Code . . . . . . . . . . . .  10
     8.2.  OAuth Implicit Grant Authorization Flow . . . . . . . . .  11
     8.3.  Loopback Redirect Considerations  . . . . . . . . . . . .  11
     8.4.  Registration of Native App Clients  . . . . . . . . . . .  12
     8.5.  Client Authentication . . . . . . . . . . . . . . . . . .  12
     8.6.  Client Impersonation  . . . . . . . . . . . . . . . . . .  13
     8.7.  Fake External User-Agents . . . . . . . . . . . . . . . .  13
     8.8.  Malicious External User-Agents  . . . . . . . . . . . . .  14
     8.9.  Cross-App Request Forgery Protections . . . . . . . . . .  14
     8.10. Authorization Server Mix-Up Mitigation  . . . . . . . . .  14
     8.11. Non-Browser External User-Agents  . . . . . . . . . . . .  15
     8.12. Embedded User-Agents  . . . . . . . . . . . . . . . . . .  15
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  16
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  16
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  16
     10.2.  Informative References . . . . . . . . . . . . . . . . .  17
   Appendix A.  Server Support Checklist . . . . . . . . . . . . . .  18
   Appendix B.  Platform-Specific Implementation Details . . . . . .  18
     B.1.  iOS Implementation Details  . . . . . . . . . . . . . . .  18
     B.2.  Android Implementation Details  . . . . . . . . . . . . .  19
     B.3.  Windows Implementation Details  . . . . . . . . . . . . .  19
     B.4.  macOS Implementation Details  . . . . . . . . . . . . . .  20
     B.5.  Linux Implementation Details  . . . . . . . . . . . . . .  21
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  21
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21
        
   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   3
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Overview  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Authorization Flow for Native Apps Using the Browser  . .   5
   5.  Using Inter-App URI Communication for OAuth . . . . . . . . .   6
   6.  Initiating the Authorization Request from a Native App  . . .   6
   7.  Receiving the Authorization Response in a Native App  . . . .   7
     7.1.  Private-Use URI Scheme Redirection  . . . . . . . . . . .   8
     7.2.  Claimed "https" Scheme URI Redirection  . . . . . . . . .   9
     7.3.  Loopback Interface Redirection  . . . . . . . . . . . . .   9
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
     8.1.  Protecting the Authorization Code . . . . . . . . . . . .  10
     8.2.  OAuth Implicit Grant Authorization Flow . . . . . . . . .  11
     8.3.  Loopback Redirect Considerations  . . . . . . . . . . . .  11
     8.4.  Registration of Native App Clients  . . . . . . . . . . .  12
     8.5.  Client Authentication . . . . . . . . . . . . . . . . . .  12
     8.6.  Client Impersonation  . . . . . . . . . . . . . . . . . .  13
     8.7.  Fake External User-Agents . . . . . . . . . . . . . . . .  13
     8.8.  Malicious External User-Agents  . . . . . . . . . . . . .  14
     8.9.  Cross-App Request Forgery Protections . . . . . . . . . .  14
     8.10. Authorization Server Mix-Up Mitigation  . . . . . . . . .  14
     8.11. Non-Browser External User-Agents  . . . . . . . . . . . .  15
     8.12. Embedded User-Agents  . . . . . . . . . . . . . . . . . .  15
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  16
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  16
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  16
     10.2.  Informative References . . . . . . . . . . . . . . . . .  17
   Appendix A.  Server Support Checklist . . . . . . . . . . . . . .  18
   Appendix B.  Platform-Specific Implementation Details . . . . . .  18
     B.1.  iOS Implementation Details  . . . . . . . . . . . . . . .  18
     B.2.  Android Implementation Details  . . . . . . . . . . . . .  19
     B.3.  Windows Implementation Details  . . . . . . . . . . . . .  19
     B.4.  macOS Implementation Details  . . . . . . . . . . . . . .  20
     B.5.  Linux Implementation Details  . . . . . . . . . . . . . .  21
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  21
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21
        
1. Introduction
1. 介绍

Section 9 of the OAuth 2.0 authorization framework [RFC6749] documents two approaches for native apps to interact with the authorization endpoint: an embedded user-agent and an external user-agent.

OAuth 2.0授权框架[RFC6749]的第9节记录了本机应用程序与授权端点交互的两种方法:嵌入式用户代理和外部用户代理。

This best current practice requires that only external user-agents like the browser are used for OAuth by native apps. It documents how native apps can implement authorization flows using the browser as the preferred external user-agent as well as the requirements for authorization servers to support such usage.

当前的最佳实践要求本地应用程序仅将浏览器等外部用户代理用于OAuth。它记录了本机应用程序如何使用浏览器作为首选外部用户代理来实现授权流,以及支持此类使用的授权服务器的要求。

This practice is also known as the "AppAuth pattern", in reference to open-source libraries [AppAuth] that implement it.

这种做法也称为“AppAuth模式”,是指实现它的开源库[AppAuth]。

2. Notational Conventions
2. 符号约定

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可”和“可选”在所有大写字母出现时(如图所示)应按照BCP 14[RFC2119][RFC8174]所述进行解释。

3. Terminology
3. 术语

In addition to the terms defined in referenced specifications, this document uses the following terms:

除参考规范中定义的术语外,本文件还使用以下术语:

"native app" An app or application that is installed by the user to their device, as distinct from a web app that runs in the browser context only. Apps implemented using web-based technology but distributed as a native app, so-called "hybrid apps", are considered equivalent to native apps for the purpose of this specification.

“本机应用程序”用户安装到其设备上的应用程序或应用程序,与仅在浏览器上下文中运行的web应用程序不同。在本规范中,使用基于web的技术实现但作为本机应用程序分发的应用程序,即所谓的“混合应用程序”,被视为等同于本机应用程序。

"app" A "native app" unless further specified.

“应用程序”是“本机应用程序”,除非另有规定。

"app store" An e-commerce store where users can download and purchase apps.

“应用商店”是一个电子商务商店,用户可以在这里下载和购买应用。

"OAuth" Authorization protocol specified by the OAuth 2.0 Authorization Framework [RFC6749].

OAuth 2.0授权框架[RFC6749]指定的“OAuth”授权协议。

"external user-agent" A user-agent capable of handling the authorization request that is a separate entity or security domain to the native app making the request, such that the app cannot access the cookie storage, nor inspect or modify page content.

“外部用户代理”能够处理授权请求的用户代理,该授权请求是发出请求的本机应用程序的独立实体或安全域,因此该应用程序无法访问cookie存储,也无法检查或修改页面内容。

"embedded user-agent" A user-agent hosted by the native app making the authorization request that forms a part of the app or shares the same security domain such that the app can access the cookie storage and/or inspect or modify page content.

“嵌入式用户代理”由本机应用托管的用户代理,发出授权请求,构成应用的一部分或共享相同的安全域,以便应用可以访问cookie存储和/或检查或修改页面内容。

"browser" The default application launched by the operating system to handle "http" and "https" scheme URI content.

“浏览器”操作系统启动的默认应用程序,用于处理“http”和“https”方案URI内容。

"in-app browser tab" A programmatic instantiation of the browser that is displayed inside a host app but that retains the full security properties and authentication state of the browser. It has different platform-specific product names, several of which are detailed in Appendix B.

“应用内浏览器选项卡”浏览器的编程实例化,显示在主机应用内,但保留浏览器的完整安全属性和身份验证状态。它具有不同的特定于平台的产品名称,附录B中详细介绍了其中的几个名称。

"web-view" A web browser UI (user interface) component that is embedded in apps to render web pages under the control of the app.

“web视图”嵌入在应用程序中的web浏览器UI(用户界面)组件,用于在应用程序的控制下呈现网页。

"inter-app communication" Communication between two apps on a device.

“应用程序间通信”设备上两个应用程序之间的通信。

"claimed "https" scheme URI" Some platforms allow apps to claim an "https" scheme URI after proving ownership of the domain name. URIs claimed in such a way are then opened in the app instead of the browser.

声明的“https”方案URI一些平台允许应用程序在证明域名所有权后声明“https”方案URI。然后,以这种方式声明的URI将在应用程序而不是浏览器中打开。

"private-use URI scheme" As used by this document, a URI scheme defined by the app (following the requirements of Section 3.8 of [RFC7595]) and registered with the operating system. URI requests to such schemes launch the app that registered it to handle the request.

本文件中使用的“专用URI方案”,由应用程序定义的URI方案(遵循[RFC7595]第3.8节的要求),并在操作系统中注册。对此类方案的URI请求会启动注册该方案的应用程序来处理该请求。

"reverse domain name notation" A naming convention based on the domain name system, but one where the domain components are reversed, for example, "app.example.com" becomes "com.example.app".

“反向域名表示法”是一种基于域名系统的命名约定,但其中的域组件是反向的,例如,“app.example.com”变为“com.example.app”。

4. Overview
4. 概述

For authorizing users in native apps, the best current practice is to perform the OAuth authorization request in an external user-agent (typically the browser) rather than an embedded user-agent (such as one implemented with web-views).

对于在本机应用程序中授权用户,当前最佳做法是在外部用户代理(通常是浏览器)而不是嵌入式用户代理(例如使用web视图实现的代理)中执行OAuth授权请求。

Previously, it was common for native apps to use embedded user-agents (commonly implemented with web-views) for OAuth authorization requests. That approach has many drawbacks, including the host app being able to copy user credentials and cookies as well as the user needing to authenticate from scratch in each app. See Section 8.12

以前,本机应用程序通常使用嵌入式用户代理(通常通过web视图实现)进行OAuth授权请求。这种方法有许多缺点,包括主机应用程序能够复制用户凭据和cookie,以及用户需要在每个应用程序中从头开始进行身份验证。见第8.12节

for a deeper analysis of the drawbacks of using embedded user-agents for OAuth.

为了更深入地分析OAuth使用嵌入式用户代理的缺点。

Native app authorization requests that use the browser are more secure and can take advantage of the user's authentication state. Being able to use the existing authentication session in the browser enables single sign-on, as users don't need to authenticate to the authorization server each time they use a new app (unless required by the authorization server policy).

使用浏览器的本机应用程序授权请求更安全,可以利用用户的身份验证状态。能够在浏览器中使用现有的身份验证会话可以启用单点登录,因为用户无需在每次使用新应用时向授权服务器进行身份验证(除非授权服务器策略要求)。

Supporting authorization flows between a native app and the browser is possible without changing the OAuth protocol itself, as the OAuth authorization request and response are already defined in terms of URIs. This encompasses URIs that can be used for inter-app communication. Some OAuth server implementations that assume all clients are confidential web clients will need to add an understanding of public native app clients and the types of redirect URIs they use to support this best practice.

支持本地应用程序和浏览器之间的授权流是可能的,而无需更改OAuth协议本身,因为OAuth授权请求和响应已经根据URI定义。这包括可用于应用程序间通信的URI。一些OAuth服务器实现假定所有客户端都是机密的web客户端,因此需要了解公共本机应用程序客户端以及它们用于支持此最佳实践的重定向URI的类型。

4.1. Authorization Flow for Native Apps Using the Browser
4.1. 使用浏览器的本机应用的授权流
  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
  |          User Device          |
  |                               |
  | +--------------------------+  | (5) Authorization  +---------------+
  | |                          |  |     Code           |               |
  | |        Client App        |---------------------->|     Token     |
  | |                          |<----------------------|    Endpoint   |
  | +--------------------------+  | (6) Access Token,  |               |
  |   |             ^             |     Refresh Token  +---------------+
  |   |             |             |
  |   |             |             |
  |   | (1)         | (4)         |
  |   | Authorizat- | Authoriza-  |
  |   | ion Request | tion Code   |
  |   |             |             |
  |   |             |             |
  |   v             |             |
  | +---------------------------+ | (2) Authorization  +---------------+
  | |                           | |     Request        |               |
  | |          Browser          |--------------------->| Authorization |
  | |                           |<---------------------|    Endpoint   |
  | +---------------------------+ | (3) Authorization  |               |
  |                               |     Code           +---------------+
  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
        
  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
  |          User Device          |
  |                               |
  | +--------------------------+  | (5) Authorization  +---------------+
  | |                          |  |     Code           |               |
  | |        Client App        |---------------------->|     Token     |
  | |                          |<----------------------|    Endpoint   |
  | +--------------------------+  | (6) Access Token,  |               |
  |   |             ^             |     Refresh Token  +---------------+
  |   |             |             |
  |   |             |             |
  |   | (1)         | (4)         |
  |   | Authorizat- | Authoriza-  |
  |   | ion Request | tion Code   |
  |   |             |             |
  |   |             |             |
  |   v             |             |
  | +---------------------------+ | (2) Authorization  +---------------+
  | |                           | |     Request        |               |
  | |          Browser          |--------------------->| Authorization |
  | |                           |<---------------------|    Endpoint   |
  | +---------------------------+ | (3) Authorization  |               |
  |                               |     Code           +---------------+
  +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
        

Figure 1: Native App Authorization via an External User-Agent

图1:通过外部用户代理的本机应用程序授权

Figure 1 illustrates the interaction between a native app and the browser to authorize the user.

图1演示了本机应用程序和浏览器之间的交互,以授权用户。

(1) Client app opens a browser tab with the authorization request.

(1) 客户端应用打开带有授权请求的浏览器选项卡。

(2) Authorization endpoint receives the authorization request, authenticates the user, and obtains authorization. Authenticating the user may involve chaining to other authentication systems.

(2) 授权端点接收授权请求,对用户进行身份验证,并获得授权。认证用户可能涉及链接到其他认证系统。

(3) Authorization server issues an authorization code to the redirect URI.

(3) 授权服务器向重定向URI发出授权代码。

(4) Client receives the authorization code from the redirect URI.

(4) 客户端从重定向URI接收授权代码。

(5) Client app presents the authorization code at the token endpoint.

(5) 客户端应用程序在令牌端点显示授权代码。

(6) Token endpoint validates the authorization code and issues the tokens requested.

(6) 令牌端点验证授权代码并发出请求的令牌。

5. Using Inter-App URI Communication for OAuth
5. 为OAuth使用应用程序间URI通信

Just as URIs are used for OAuth 2.0 [RFC6749] on the web to initiate the authorization request and return the authorization response to the requesting website, URIs can be used by native apps to initiate the authorization request in the device's browser and return the response to the requesting native app.

正如web上的OAuth 2.0[RFC6749]使用URI来启动授权请求并将授权响应返回到请求的网站一样,本机应用程序也可以使用URI在设备浏览器中启动授权请求并将响应返回到请求的本机应用程序。

By adopting the same methods used on the web for OAuth, benefits seen in the web context like the usability of a single sign-on session and the security of a separate authentication context are likewise gained in the native app context. Reusing the same approach also reduces the implementation complexity and increases interoperability by relying on standards-based web flows that are not specific to a particular platform.

通过采用web上用于OAuth的相同方法,在本机应用程序上下文中同样可以获得在web上下文中看到的好处,如单个登录会话的可用性和单独身份验证上下文的安全性。重用相同的方法还可以通过依赖非特定于特定平台的基于标准的web流来降低实现复杂性并提高互操作性。

To conform to this best practice, native apps MUST use an external user-agent to perform OAuth authorization requests. This is achieved by opening the authorization request in the browser (detailed in Section 6) and using a redirect URI that will return the authorization response back to the native app (defined in Section 7).

为了符合此最佳实践,本机应用程序必须使用外部用户代理来执行OAuth授权请求。这是通过在浏览器中打开授权请求(详见第6节)并使用重定向URI来实现的,重定向URI将授权响应返回到本机应用程序(见第7节)。

6. Initiating the Authorization Request from a Native App
6. 从本机应用启动授权请求

Native apps needing user authorization create an authorization request URI with the authorization code grant type per Section 4.1 of OAuth 2.0 [RFC6749], using a redirect URI capable of being received by the native app.

需要用户授权的本机应用程序使用本机应用程序能够接收的重定向URI,按照OAuth 2.0[RFC6749]第4.1节的规定,使用授权代码授权类型创建授权请求URI。

The function of the redirect URI for a native app authorization request is similar to that of a web-based authorization request. Rather than returning the authorization response to the OAuth client's server, the redirect URI used by a native app returns the response to the app. Several options for a redirect URI that will return the authorization response to the native app in different platforms are documented in Section 7. Any redirect URI that allows the app to receive the URI and inspect its parameters is viable.

本机应用程序授权请求的重定向URI的功能类似于基于web的授权请求。本机应用程序使用的重定向URI不是将授权响应返回给OAuth客户端的服务器,而是将响应返回给应用程序。第7节介绍了将授权响应返回到不同平台中本机应用程序的重定向URI的几个选项。任何允许应用程序接收URI并检查其参数的重定向URI都是可行的。

Public native app clients MUST implement the Proof Key for Code Exchange (PKCE [RFC7636]) extension to OAuth, and authorization servers MUST support PKCE for such clients, for the reasons detailed in Section 8.1.

公共本机应用程序客户端必须实现对OAuth的代码交换验证密钥(PKCE[RFC7636])扩展,授权服务器必须支持此类客户端的PKCE,原因详见第8.1节。

After constructing the authorization request URI, the app uses platform-specific APIs to open the URI in an external user-agent. Typically, the external user-agent used is the default browser, that is, the application configured for handling "http" and "https" scheme URIs on the system; however, different browser selection criteria and other categories of external user-agents MAY be used.

构建授权请求URI后,应用程序使用特定于平台的API在外部用户代理中打开URI。通常,使用的外部用户代理是默认浏览器,即配置用于处理系统上的“http”和“https”方案URI的应用程序;但是,可以使用不同的浏览器选择标准和其他类别的外部用户代理。

This best practice focuses on the browser as the RECOMMENDED external user-agent for native apps. An external user-agent designed specifically for user authorization and capable of processing authorization requests and responses like a browser MAY also be used. Other external user-agents, such as a native app provided by the authorization server may meet the criteria set out in this best practice, including using the same redirection URI properties, but their use is out of scope for this specification.

此最佳实践侧重于将浏览器作为本机应用程序的推荐外部用户代理。还可以使用专门为用户授权设计的外部用户代理,该外部用户代理能够像浏览器一样处理授权请求和响应。其他外部用户代理(如授权服务器提供的本机应用程序)可能符合本最佳实践中规定的标准,包括使用相同的重定向URI属性,但它们的使用超出本规范的范围。

Some platforms support a browser feature known as "in-app browser tabs", where an app can present a tab of the browser within the app context without switching apps, but still retain key benefits of the browser such as a shared authentication state and security context. On platforms where they are supported, it is RECOMMENDED, for usability reasons, that apps use in-app browser tabs for the authorization request.

一些平台支持称为“应用程序内浏览器选项卡”的浏览器功能,其中应用程序可以在应用程序上下文中显示浏览器选项卡,而无需切换应用程序,但仍保留浏览器的关键优势,如共享身份验证状态和安全上下文。在支持应用程序的平台上,出于可用性原因,建议应用程序使用应用程序内浏览器选项卡进行授权请求。

7. Receiving the Authorization Response in a Native App
7. 在本机应用程序中接收授权响应

There are several redirect URI options available to native apps for receiving the authorization response from the browser, the availability and user experience of which varies by platform.

本机应用程序有几个重定向URI选项可用于从浏览器接收授权响应,其可用性和用户体验因平台而异。

To fully support this best practice, authorization servers MUST offer at least the three redirect URI options described in the following subsections to native apps. Native apps MAY use whichever redirect option suits their needs best, taking into account platform-specific implementation details.

要完全支持此最佳实践,授权服务器必须至少提供以下小节中描述的三个重定向URI选项,以将其重定向到本机应用程序。本机应用程序可以使用最适合其需要的重定向选项,并考虑特定于平台的实现细节。

7.1. Private-Use URI Scheme Redirection
7.1. 专用URI方案重定向

Many mobile and desktop computing platforms support inter-app communication via URIs by allowing apps to register private-use URI schemes (sometimes colloquially referred to as "custom URL schemes") like "com.example.app". When the browser or another app attempts to load a URI with a private-use URI scheme, the app that registered it is launched to handle the request.

许多移动和桌面计算平台通过URI支持应用间通信,允许应用注册私用URI方案(有时通俗地称为“自定义URL方案”),如“com.example.app”。当浏览器或其他应用程序尝试加载具有专用URI方案的URI时,将启动注册该URI的应用程序来处理请求。

To perform an OAuth 2.0 authorization request with a private-use URI scheme redirect, the native app launches the browser with a standard authorization request, but one where the redirection URI utilizes a private-use URI scheme it registered with the operating system.

要使用专用URI方案重定向执行OAuth 2.0授权请求,本机应用程序将使用标准授权请求启动浏览器,但重定向URI使用其在操作系统中注册的专用URI方案。

When choosing a URI scheme to associate with the app, apps MUST use a URI scheme based on a domain name under their control, expressed in reverse order, as recommended by Section 3.8 of [RFC7595] for private-use URI schemes.

当选择与应用程序关联的URI方案时,应用程序必须使用基于其控制下的域名的URI方案,并按照[RFC7595]第3.8节对私用URI方案的建议以相反顺序表示。

For example, an app that controls the domain name "app.example.com" can use "com.example.app" as their scheme. Some authorization servers assign client identifiers based on domain names, for example, "client1234.usercontent.example.net", which can also be used as the domain name for the scheme when reversed in the same manner. A scheme such as "myapp", however, would not meet this requirement, as it is not based on a domain name.

例如,控制域名“app.example.com”的应用程序可以使用“com.example.app”作为其方案。一些授权服务器基于域名分配客户端标识符,例如,“client1234.usercontent.example.net”,当以相同方式反转时,该域名也可以用作方案的域名。然而,像“myapp”这样的方案不能满足这一要求,因为它不是基于域名的。

When there are multiple apps by the same publisher, care must be taken so that each scheme is unique within that group. On platforms that use app identifiers based on reverse-order domain names, those identifiers can be reused as the private-use URI scheme for the OAuth redirect to help avoid this problem.

当同一发布者有多个应用程序时,必须注意使每个方案在该组中都是唯一的。在使用基于逆序域名的应用程序标识符的平台上,这些标识符可以作为OAuth重定向的专用URI方案重用,以帮助避免此问题。

Following the requirements of Section 3.2 of [RFC3986], as there is no naming authority for private-use URI scheme redirects, only a single slash ("/") appears after the scheme component. A complete example of a redirect URI utilizing a private-use URI scheme is:

根据[RFC3986]第3.2节的要求,由于私用URI方案重定向没有命名权限,因此在方案组件后仅显示一个斜杠(“/”)。使用专用URI方案的重定向URI的完整示例如下:

     com.example.app:/oauth2redirect/example-provider
        
     com.example.app:/oauth2redirect/example-provider
        

When the authorization server completes the request, it redirects to the client's redirection URI as it would normally. As the redirection URI uses a private-use URI scheme, it results in the operating system launching the native app, passing in the URI as a launch parameter. Then, the native app uses normal processing for the authorization response.

当授权服务器完成请求时,它会像往常一样重定向到客户端的重定向URI。由于重定向URI使用私有使用URI方案,因此会导致操作系统启动本机应用程序,并将URI作为启动参数传入。然后,本机应用程序对授权响应使用正常处理。

7.2. Claimed "https" Scheme URI Redirection
7.2. 声明的“https”方案URI重定向

Some operating systems allow apps to claim "https" scheme [RFC7230] URIs in the domains they control. When the browser encounters a claimed URI, instead of the page being loaded in the browser, the native app is launched with the URI supplied as a launch parameter.

一些操作系统允许应用程序在其控制的域中声明“https”方案[RFC7230]URI。当浏览器遇到一个声明的URI时,本机应用程序将以作为启动参数提供的URI启动,而不是在浏览器中加载页面。

Such URIs can be used as redirect URIs by native apps. They are indistinguishable to the authorization server from a regular web-based client redirect URI. An example is:

这样的URI可以被本机应用程序用作重定向URI。授权服务器无法将它们与常规的基于web的客户端重定向URI区分开来。例如:

     https://app.example.com/oauth2redirect/example-provider
        
     https://app.example.com/oauth2redirect/example-provider
        

As the redirect URI alone is not enough to distinguish public native app clients from confidential web clients, it is REQUIRED in Section 8.4 that the client type be recorded during client registration to enable the server to determine the client type and act accordingly.

由于重定向URI本身不足以区分公共本机应用程序客户端和机密web客户端,因此第8.4节要求在客户端注册期间记录客户端类型,以使服务器能够确定客户端类型并采取相应行动。

App-claimed "https" scheme redirect URIs have some advantages compared to other native app redirect options in that the identity of the destination app is guaranteed to the authorization server by the operating system. For this reason, native apps SHOULD use them over the other options where possible.

应用程序声称的“https”方案重定向URI与其他本机应用程序重定向选项相比具有一些优势,因为操作系统可以向授权服务器保证目标应用程序的身份。因此,本机应用程序应尽可能使用它们而不是其他选项。

7.3. Loopback Interface Redirection
7.3. 环回接口重定向

Native apps that are able to open a port on the loopback network interface without needing special permissions (typically, those on desktop operating systems) can use the loopback interface to receive the OAuth redirect.

能够在环回网络接口上打开端口而不需要特殊权限的本机应用程序(通常是桌面操作系统上的应用程序)可以使用环回接口接收OAuth重定向。

Loopback redirect URIs use the "http" scheme and are constructed with the loopback IP literal and whatever port the client is listening on.

环回重定向URI使用“http”方案,并使用环回IP文本和客户端正在侦听的任何端口构造。

That is, "http://127.0.0.1:{port}/{path}" for IPv4, and "http://[::1]:{port}/{path}" for IPv6. An example redirect using the IPv4 loopback interface with a randomly assigned port:

就是,http://127.0.0.1:IPv4为“{port}/{path}”,IPv6为“http://[::1]:{port}/{path}”。使用带有随机分配端口的IPv4环回接口的重定向示例:

     http://127.0.0.1:51004/oauth2redirect/example-provider
        
     http://127.0.0.1:51004/oauth2redirect/example-provider
        

An example redirect using the IPv6 loopback interface with a randomly assigned port:

使用带有随机分配端口的IPv6环回接口的重定向示例:

     http://[::1]:61023/oauth2redirect/example-provider
        
     http://[::1]:61023/oauth2redirect/example-provider
        

The authorization server MUST allow any port to be specified at the time of the request for loopback IP redirect URIs, to accommodate clients that obtain an available ephemeral port from the operating system at the time of the request.

授权服务器必须允许在请求环回IP重定向URI时指定任何端口,以容纳在请求时从操作系统获得可用临时端口的客户端。

Clients SHOULD NOT assume that the device supports a particular version of the Internet Protocol. It is RECOMMENDED that clients attempt to bind to the loopback interface using both IPv4 and IPv6 and use whichever is available.

客户端不应假定设备支持特定版本的Internet协议。建议客户端尝试同时使用IPv4和IPv6绑定到环回接口,并使用任何可用的接口。

8. Security Considerations
8. 安全考虑
8.1. Protecting the Authorization Code
8.1. 保护授权码

The redirect URI options documented in Section 7 share the benefit that only a native app on the same device or the app's own website can receive the authorization code, which limits the attack surface. However, code interception by a different native app running on the same device may be possible.

第7节中记录的重定向URI选项有一个共同的好处,即只有同一设备上的本机应用程序或应用程序自己的网站才能接收授权代码,这限制了攻击面。但是,在同一设备上运行的不同本机应用程序可能会拦截代码。

A limitation of using private-use URI schemes for redirect URIs is that multiple apps can typically register the same scheme, which makes it indeterminate as to which app will receive the authorization code. Section 1 of PKCE [RFC7636] details how this limitation can be used to execute a code interception attack.

对重定向URI使用专用URI方案的一个限制是,多个应用程序通常可以注册同一个方案,这使得不确定哪个应用程序将接收授权代码。PKCE[RFC7636]的第1节详细说明了如何使用此限制来执行代码拦截攻击。

Loopback IP-based redirect URIs may be susceptible to interception by other apps accessing the same loopback interface on some operating systems.

基于环回IP的重定向URI可能容易被访问某些操作系统上相同环回接口的其他应用程序截获。

App-claimed "https" scheme redirects are less susceptible to URI interception due to the presence of the URI authority, but the app is still a public client; further, the URI is sent using the operating system's URI dispatch handler with unknown security properties.

应用程序声称“https”方案重定向不太容易受到URI拦截的影响,因为存在URI授权,但该应用程序仍然是公共客户端;此外,URI是使用具有未知安全属性的操作系统URI调度处理程序发送的。

The PKCE [RFC7636] protocol was created specifically to mitigate this attack. It is a proof-of-possession extension to OAuth 2.0 that protects the authorization code from being used if it is intercepted. To provide protection, this extension has the client generate a secret verifier; it passes a hash of this verifier in the initial authorization request, and must present the unhashed verifier when redeeming the authorization code. An app that intercepted the authorization code would not be in possession of this secret, rendering the code useless.

PKCE[RFC7636]协议是专门为缓解这种攻击而创建的。它是对OAuth 2.0的一个拥有证明扩展,可以保护授权代码在被截获时不被使用。为了提供保护,该扩展让客户端生成一个秘密验证器;它在初始授权请求中传递此验证器的散列,并且在兑换授权代码时必须显示未删除的验证器。截获授权代码的应用程序将不会拥有此机密,从而使代码无效。

Section 6 requires that both clients and servers use PKCE for public native app clients. Authorization servers SHOULD reject authorization requests from native apps that don't use PKCE by returning an error message, as defined in Section 4.4.1 of PKCE [RFC7636].

第6节要求客户端和服务器对公共本机应用程序客户端使用PKCE。授权服务器应通过返回错误消息拒绝来自不使用PKCE的本机应用程序的授权请求,如PKCE[RFC7636]第4.4.1节所定义。

8.2. OAuth Implicit Grant Authorization Flow
8.2. OAuth隐式授权流

The OAuth 2.0 implicit grant authorization flow (defined in Section 4.2 of OAuth 2.0 [RFC6749]) generally works with the practice of performing the authorization request in the browser and receiving the authorization response via URI-based inter-app communication. However, as the implicit flow cannot be protected by PKCE [RFC7636] (which is required in Section 8.1), the use of the Implicit Flow with native apps is NOT RECOMMENDED.

OAuth 2.0隐式授权流(定义见OAuth 2.0[RFC6749]第4.2节)通常与在浏览器中执行授权请求并通过基于URI的应用程序间通信接收授权响应的实践一起工作。但是,由于PKCE[RFC7636](第8.1节要求)无法保护隐式流,因此不建议在本机应用程序中使用隐式流。

Access tokens granted via the implicit flow also cannot be refreshed without user interaction, making the authorization code grant flow -- which can issue refresh tokens -- the more practical option for native app authorizations that require refreshing of access tokens.

通过隐式流授予的访问令牌也不能在没有用户交互的情况下刷新,这使得授权代码授予流(可以发出刷新令牌)成为需要刷新访问令牌的本机应用程序授权的更实用的选项。

8.3. Loopback Redirect Considerations
8.3. 环回重定向注意事项

Loopback interface redirect URIs use the "http" scheme (i.e., without Transport Layer Security (TLS)). This is acceptable for loopback interface redirect URIs as the HTTP request never leaves the device.

环回接口重定向URI使用“http”方案(即,没有传输层安全性(TLS))。这对于环回接口重定向URI是可以接受的,因为HTTP请求永远不会离开设备。

Clients should open the network port only when starting the authorization request and close it once the response is returned.

客户端应仅在启动授权请求时打开网络端口,并在返回响应后将其关闭。

Clients should listen on the loopback network interface only, in order to avoid interference by other network actors.

客户端应仅监听环回网络接口,以避免其他网络参与者的干扰。

   While redirect URIs using localhost (i.e.,
   "http://localhost:{port}/{path}") function similarly to loopback IP
   redirects described in Section 7.3, the use of localhost is NOT
   RECOMMENDED.  Specifying a redirect URI with the loopback IP literal
   rather than localhost avoids inadvertently listening on network
        
   While redirect URIs using localhost (i.e.,
   "http://localhost:{port}/{path}") function similarly to loopback IP
   redirects described in Section 7.3, the use of localhost is NOT
   RECOMMENDED.  Specifying a redirect URI with the loopback IP literal
   rather than localhost avoids inadvertently listening on network
        

interfaces other than the loopback interface. It is also less susceptible to client-side firewalls and misconfigured host name resolution on the user's device.

环回接口以外的接口。它也不太容易受到客户端防火墙和用户设备上配置错误的主机名解析的影响。

8.4. Registration of Native App Clients
8.4. 注册本机应用程序客户端

Except when using a mechanism like Dynamic Client Registration [RFC7591] to provision per-instance secrets, native apps are classified as public clients, as defined by Section 2.1 of OAuth 2.0 [RFC6749]; they MUST be registered with the authorization server as such. Authorization servers MUST record the client type in the client registration details in order to identify and process requests accordingly.

除非使用动态客户端注册[RFC7591]等机制来提供每个实例的机密,否则本机应用程序被归类为公共客户端,如OAuth 2.0[RFC6749]第2.1节所定义;它们必须在授权服务器上注册。授权服务器必须在客户端注册详细信息中记录客户端类型,以便相应地识别和处理请求。

Authorization servers MUST require clients to register their complete redirect URI (including the path component) and reject authorization requests that specify a redirect URI that doesn't exactly match the one that was registered; the exception is loopback redirects, where an exact match is required except for the port URI component.

授权服务器必须要求客户端注册其完整的重定向URI(包括路径组件),并拒绝指定与注册的重定向URI不完全匹配的重定向URI的授权请求;环回重定向是个例外,除了端口URI组件外,需要精确匹配。

For private-use URI scheme-based redirects, authorization servers SHOULD enforce the requirement in Section 7.1 that clients use schemes that are reverse domain name based. At a minimum, any private-use URI scheme that doesn't contain a period character (".") SHOULD be rejected.

对于基于私有URI方案的重定向,授权服务器应强制执行第7.1节中的要求,即客户端使用基于反向域名的方案。至少应拒绝任何不包含句点字符(“.”)的专用URI方案。

In addition to the collision-resistant properties, requiring a URI scheme based on a domain name that is under the control of the app can help to prove ownership in the event of a dispute where two apps claim the same private-use URI scheme (where one app is acting maliciously). For example, if two apps claimed "com.example.app", the owner of "example.com" could petition the app store operator to remove the counterfeit app. Such a petition is harder to prove if a generic URI scheme was used.

除了抗冲突属性外,如果两个应用程序声明相同的专用URI方案(其中一个应用程序恶意行事),则要求基于应用程序控制下的域名的URI方案有助于在发生争议时证明所有权。例如,如果两个应用声称“com.example.app”,则“example.com”的所有者可以请求应用商店运营商删除假冒应用。如果使用了通用URI方案,那么这样的申请就更难证明了。

Authorization servers MAY request the inclusion of other platform-specific information, such as the app package or bundle name, or other information that may be useful for verifying the calling app's identity on operating systems that support such functions.

授权服务器可以请求包含其他特定于平台的信息,例如应用程序包或捆绑包名称,或者其他可能有助于在支持此类功能的操作系统上验证调用应用程序的身份的信息。

8.5. Client Authentication
8.5. 客户端身份验证

Secrets that are statically included as part of an app distributed to multiple users should not be treated as confidential secrets, as one user may inspect their copy and learn the shared secret. For this reason, and those stated in Section 5.3.1 of [RFC6819], it is NOT RECOMMENDED for authorization servers to require client

作为分发给多个用户的应用程序的一部分静态包含的机密不应视为机密机密,因为一个用户可能会检查其副本并了解共享机密。因此,以及[RFC6819]第5.3.1节中所述的原因,不建议授权服务器要求客户端

authentication of public native apps clients using a shared secret, as this serves little value beyond client identification which is already provided by the "client_id" request parameter.

使用共享秘密对公共本机应用程序客户端进行身份验证,因为除了“client_id”请求参数已经提供的客户端标识之外,这没有什么价值。

Authorization servers that still require a statically included shared secret for native app clients MUST treat the client as a public client (as defined by Section 2.1 of OAuth 2.0 [RFC6749]), and not accept the secret as proof of the client's identity. Without additional measures, such clients are subject to client impersonation (see Section 8.6).

对于仍需要为本机应用程序客户端静态包含共享机密的授权服务器,必须将该客户端视为公共客户端(如OAuth 2.0[RFC6749]第2.1节所定义),并且不接受该机密作为客户端身份的证明。在没有其他措施的情况下,此类客户会受到客户模拟的影响(见第8.6节)。

8.6. Client Impersonation
8.6. 客户端模拟

As stated in Section 10.2 of OAuth 2.0 [RFC6749], the authorization server SHOULD NOT process authorization requests automatically without user consent or interaction, except when the identity of the client can be assured. This includes the case where the user has previously approved an authorization request for a given client id -- unless the identity of the client can be proven, the request SHOULD be processed as if no previous request had been approved.

如OAuth 2.0[RFC6749]第10.2节所述,授权服务器不应在没有用户同意或交互的情况下自动处理授权请求,除非可以确保客户端的身份。这包括用户先前已批准给定客户id的授权请求的情况——除非可以证明客户的身份,否则应将该请求视为之前未批准任何请求进行处理。

Measures such as claimed "https" scheme redirects MAY be accepted by authorization servers as identity proof. Some operating systems may offer alternative platform-specific identity features that MAY be accepted, as appropriate.

授权服务器可能会接受声称的“https”方案重定向等措施作为身份证明。某些操作系统可能会提供可接受的特定于平台的替代标识功能(视情况而定)。

8.7. Fake External User-Agents
8.7. 假外部用户代理

The native app that is initiating the authorization request has a large degree of control over the user interface and can potentially present a fake external user-agent, that is, an embedded user-agent made to appear as an external user-agent.

发起授权请求的本机应用程序对用户界面具有很大程度的控制权,并且可能会呈现虚假的外部用户代理,即嵌入的用户代理,以显示为外部用户代理。

When all good actors are using external user-agents, the advantage is that it is possible for security experts to detect bad actors, as anyone faking an external user-agent is provably bad. On the other hand, if good and bad actors alike are using embedded user-agents, bad actors don't need to fake anything, making them harder to detect. Once a malicious app is detected, it may be possible to use this knowledge to blacklist the app's signature in malware scanning software, take removal action (in the case of apps distributed by app stores) and other steps to reduce the impact and spread of the malicious app.

当所有好的参与者都使用外部用户代理时,其优点是安全专家可以检测到坏的参与者,因为任何伪造外部用户代理的人都是可证明的坏的。另一方面,如果好的和坏的参与者都在使用嵌入式用户代理,那么坏的参与者就不需要伪造任何东西,从而使他们更难被发现。一旦检测到恶意应用程序,可能会利用此知识在恶意软件扫描软件中将该应用程序的签名列入黑名单,采取删除操作(对于应用商店分发的应用程序)和其他步骤,以减少恶意应用程序的影响和传播。

Authorization servers can also directly protect against fake external user-agents by requiring an authentication factor only available to true external user-agents.

授权服务器还可以通过要求仅对真正的外部用户代理可用的身份验证因子来直接防止伪造的外部用户代理。

Users who are particularly concerned about their security when using in-app browser tabs may also take the additional step of opening the request in the full browser from the in-app browser tab and complete the authorization there, as most implementations of the in-app browser tab pattern offer such functionality.

当使用应用内浏览器选项卡时,特别关注其安全性的用户还可以采取额外的步骤,从应用内浏览器选项卡在完整浏览器中打开请求,并在那里完成授权,因为大多数应用内浏览器选项卡模式的实现都提供了此类功能。

8.8. Malicious External User-Agents
8.8. 恶意外部用户代理

If a malicious app is able to configure itself as the default handler for "https" scheme URIs in the operating system, it will be able to intercept authorization requests that use the default browser and abuse this position of trust for malicious ends such as phishing the user.

如果恶意应用能够将自身配置为操作系统中“https”方案URI的默认处理程序,则它将能够拦截使用默认浏览器的授权请求,并将此信任位置用于恶意目的,例如对用户进行钓鱼。

This attack is not confined to OAuth; a malicious app configured in this way would present a general and ongoing risk to the user beyond OAuth usage by native apps. Many operating systems mitigate this issue by requiring an explicit user action to change the default handler for "http" and "https" scheme URIs.

这种攻击并不局限于OAuth;以这种方式配置的恶意应用程序将给用户带来一般和持续的风险,超出本机应用程序使用OAuth的范围。许多操作系统通过要求显式用户操作来更改“http”和“https”方案URI的默认处理程序来缓解此问题。

8.9. Cross-App Request Forgery Protections
8.9. 跨应用程序请求伪造保护

Section 5.3.5 of [RFC6819] recommends using the "state" parameter to link client requests and responses to prevent CSRF (Cross-Site Request Forgery) attacks.

[RFC6819]第5.3.5节建议使用“状态”参数链接客户端请求和响应,以防止CSRF(跨站点请求伪造)攻击。

To mitigate CSRF-style attacks over inter-app URI communication channels (so called "cross-app request forgery"), it is similarly RECOMMENDED that native apps include a high-entropy secure random number in the "state" parameter of the authorization request and reject any incoming authorization responses without a state value that matches a pending outgoing authorization request.

为了缓解应用程序间URI通信通道上的CSRF式攻击(所谓的“跨应用程序请求伪造”),同样建议本机应用程序在“状态”中包含一个高熵安全随机数参数,并拒绝没有与挂起的传出授权请求匹配的状态值的任何传入授权响应。

8.10. Authorization Server Mix-Up Mitigation
8.10. 授权服务器混淆缓解

To protect against a compromised or malicious authorization server attacking another authorization server used by the same app, it is REQUIRED that a unique redirect URI is used for each authorization server used by the app (for example, by varying the path component), and that authorization responses are rejected if the redirect URI they were received on doesn't match the redirect URI in an outgoing authorization request.

为了防止受损或恶意授权服务器攻击同一应用程序使用的另一个授权服务器,需要为该应用程序使用的每个授权服务器使用唯一的重定向URI(例如,通过改变路径组件),如果接收到的重定向URI与传出授权请求中的重定向URI不匹配,则会拒绝授权响应。

The native app MUST store the redirect URI used in the authorization request with the authorization session data (i.e., along with "state" and other related data) and MUST verify that the URI on which the authorization response was received exactly matches it.

本机应用程序必须将授权请求中使用的重定向URI与授权会话数据(即,连同“状态”和其他相关数据)一起存储,并且必须验证接收授权响应的URI是否与之完全匹配。

The requirement of Section 8.4, specifically that authorization servers reject requests with URIs that don't match what was registered, is also required to prevent such attacks.

第8.4节的要求,特别是授权服务器拒绝URI与注册内容不匹配的请求,也是防止此类攻击所必需的。

8.11. Non-Browser External User-Agents
8.11. 非浏览器外部用户代理

This best practice recommends a particular type of external user-agent: the user's browser. Other external user-agent patterns may also be viable for secure and usable OAuth. This document makes no comment on those patterns.

此最佳实践建议使用特定类型的外部用户代理:用户浏览器。其他外部用户代理模式也可以用于安全和可用的OAuth。本文档对这些模式没有任何评论。

8.12. Embedded User-Agents
8.12. 嵌入式用户代理

Section 9 of OAuth 2.0 [RFC6749] documents two approaches for native apps to interact with the authorization endpoint. This best current practice requires that native apps MUST NOT use embedded user-agents to perform authorization requests and allows that authorization endpoints MAY take steps to detect and block authorization requests in embedded user-agents. The security considerations for these requirements are detailed herein.

OAuth 2.0[RFC6749]的第9节记录了本机应用程序与授权端点交互的两种方法。此最佳当前实践要求本机应用程序不得使用嵌入式用户代理执行授权请求,并允许授权端点采取步骤检测和阻止嵌入式用户代理中的授权请求。本文详细介绍了这些要求的安全注意事项。

Embedded user-agents are an alternative method for authorizing native apps. These embedded user-agents are unsafe for use by third parties to the authorization server by definition, as the app that hosts the embedded user-agent can access the user's full authentication credential, not just the OAuth authorization grant that was intended for the app.

嵌入式用户代理是授权本机应用程序的另一种方法。根据定义,这些嵌入式用户代理对于授权服务器的第三方来说是不安全的,因为托管嵌入式用户代理的应用程序可以访问用户的完整身份验证凭据,而不仅仅是用于该应用程序的OAuth授权。

In typical web-view-based implementations of embedded user-agents, the host application can record every keystroke entered in the login form to capture usernames and passwords, automatically submit forms to bypass user consent, and copy session cookies and use them to perform authenticated actions as the user.

在嵌入式用户代理的典型基于web视图的实现中,主机应用程序可以记录登录表单中输入的每个击键以捕获用户名和密码,自动提交表单以绕过用户同意,复制会话cookie并使用它们作为用户执行经验证的操作。

Even when used by trusted apps belonging to the same party as the authorization server, embedded user-agents violate the principle of least privilege by having access to more powerful credentials than they need, potentially increasing the attack surface.

即使由与授权服务器属于同一方的受信任应用程序使用,嵌入式用户代理也违反了最小权限原则,因为它们可以访问比它们需要的更强大的凭据,这可能会增加攻击面。

Encouraging users to enter credentials in an embedded user-agent without the usual address bar and visible certificate validation features that browsers have makes it impossible for the user to know if they are signing in to the legitimate site; even when they are, it trains them that it's OK to enter credentials without validating the site first.

鼓励用户在嵌入式用户代理中输入凭据,而不使用浏览器通常的地址栏和可见的证书验证功能,这使得用户无法知道他们是否登录到合法站点;即使是这样,它也会训练他们在不首先验证站点的情况下输入凭据是可以的。

Aside from the security concerns, embedded user-agents do not share the authentication state with other apps or the browser, requiring the user to log in for every authorization request, which is often considered an inferior user experience.

除了安全问题外,嵌入式用户代理不与其他应用程序或浏览器共享身份验证状态,要求用户登录每个授权请求,这通常被认为是一种低劣的用户体验。

9. IANA Considerations
9. IANA考虑

This document does not require any IANA actions.

本文件不要求IANA采取任何行动。

Section 7.1 specifies how private-use URI schemes are used for inter-app communication in OAuth protocol flows. This document requires in Section 7.1 that such schemes are based on domain names owned or assigned to the app, as recommended in Section 3.8 of [RFC7595]. Per Section 6 of [RFC7595], registration of domain-based URI schemes with IANA is not required.

第7.1节规定了在OAuth协议流中如何将专用URI方案用于应用程序间通信。本文件第7.1节要求此类方案基于[RFC7595]第3.8节中建议的应用程序拥有或分配的域名。根据[RFC7595]第6节,不需要向IANA注册基于域的URI方案。

10. References
10. 工具书类
10.1. Normative References
10.1. 规范性引用文件

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997年3月<https://www.rfc-editor.org/info/rfc2119>.

[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.

[RFC3986]Berners Lee,T.,Fielding,R.,和L.Masinter,“统一资源标识符(URI):通用语法”,STD 66,RFC 3986,DOI 10.17487/RFC3986,2005年1月<https://www.rfc-editor.org/info/rfc3986>.

[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.

[RFC6749]Hardt,D.,Ed.“OAuth 2.0授权框架”,RFC 6749,DOI 10.17487/RFC6749,2012年10月<https://www.rfc-editor.org/info/rfc6749>.

[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <https://www.rfc-editor.org/info/rfc7230>.

[RFC7230]Fielding,R.,Ed.和J.Reschke,Ed.,“超文本传输协议(HTTP/1.1):消息语法和路由”,RFC 7230,DOI 10.17487/RFC7230,2014年6月<https://www.rfc-editor.org/info/rfc7230>.

[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015, <https://www.rfc-editor.org/info/rfc7595>.

[RFC7595]Thaler,D.,Ed.,Hansen,T.和T.Hardie,“URI方案的指南和注册程序”,BCP 35,RFC 7595,DOI 10.17487/RFC7595,2015年6月<https://www.rfc-editor.org/info/rfc7595>.

[RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015, <https://www.rfc-editor.org/info/rfc7636>.

[RFC7636]Sakimura,N.,Ed.,Bradley,J.,和N.Agarwal,“OAuth公共客户代码交换的证明密钥”,RFC 7636,DOI 10.17487/RFC76362015年9月<https://www.rfc-editor.org/info/rfc7636>.

[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8174]Leiba,B.,“RFC 2119关键词中大写与小写的歧义”,BCP 14,RFC 8174,DOI 10.17487/RFC8174,2017年5月<https://www.rfc-editor.org/info/rfc8174>.

10.2. Informative References
10.2. 资料性引用

[RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, DOI 10.17487/RFC6819, January 2013, <https://www.rfc-editor.org/info/rfc6819>.

[RFC6819]Lodderstet,T.,Ed.,McGloin,M.,和P.Hunt,“OAuth 2.0威胁模型和安全考虑”,RFC 6819,DOI 10.17487/RFC6819,2013年1月<https://www.rfc-editor.org/info/rfc6819>.

[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/info/rfc7591>.

[RFC7591]Richer,J.,Ed.,Jones,M.,Bradley,J.,Machulak,M.,和P.Hunt,“OAuth 2.0动态客户端注册协议”,RFC 7591,DOI 10.17487/RFC7591,2015年7月<https://www.rfc-editor.org/info/rfc7591>.

[AppAuth] OpenID Connect Working Group, "AppAuth", September 2017, <https://openid.net/code/AppAuth>.

[AppAuth]OpenID Connect工作组,“AppAuth”,2017年9月<https://openid.net/code/AppAuth>.

[AppAuth.iOSmacOS] Wright, S., Denniss, W., et al., "AppAuth for iOS and macOS", February 2016, <https://openid.net/code/AppAuth-iOS>.

[AppAuth.iOSmacOS]Wright,S.,Denniss,W.,et al.,“AppAuth for iOS和macOS”,2016年2月<https://openid.net/code/AppAuth-iOS>.

[AppAuth.Android] McGinniss, I., Denniss, W., et al., "AppAuth for Android", February 2016, <https://openid.net/code/AppAuth-Android>.

[AppAuth.Android]麦金尼斯,I.,丹尼斯,W.,等,“AppAuth for Android”,2016年2月<https://openid.net/code/AppAuth-Android>.

[SamplesForWindows] Denniss, W., "OAuth for Apps: Samples for Windows", July 2016, <https://openid.net/code/sample-oauth-apps-for-windows>.

[SamplesForWindows]Denniss,W.,“OAuth for Apps:Samples for Windows”,2016年7月<https://openid.net/code/sample-oauth-apps-for-windows>.

Appendix A. Server Support Checklist
附录A.服务器支持检查表

OAuth servers that support native apps must:

支持本机应用程序的OAuth服务器必须:

1. Support private-use URI scheme redirect URIs. This is required to support mobile operating systems. See Section 7.1.

1. 支持私有使用URI方案重定向URI。这是支持移动操作系统所必需的。见第7.1节。

2. Support "https" scheme redirect URIs for use with public native app clients. This is used by apps on advanced mobile operating systems that allow app-claimed "https" scheme URIs. See Section 7.2.

2. 支持用于公共本机应用程序客户端的“https”方案重定向URI。高级移动操作系统上的应用程序可以使用此选项,这些操作系统允许应用程序声明的“https”方案URI。见第7.2节。

3. Support loopback IP redirect URIs. This is required to support desktop operating systems. See Section 7.3.

3. 支持环回IP重定向URI。这是支持桌面操作系统所必需的。见第7.3节。

4. Not assume that native app clients can keep a secret. If secrets are distributed to multiple installs of the same native app, they should not be treated as confidential. See Section 8.5.

4. 不要假设本机应用程序客户端可以保守秘密。如果机密被分发到同一本机应用程序的多个安装中,则不应将其视为机密。见第8.5节。

5. Support PKCE [RFC7636]. Required to protect authorization code grants sent to public clients over inter-app communication channels. See Section 8.1

5. 支持PKCE[RFC7636]。需要保护通过应用程序间通信通道发送给公共客户端的授权码授权。见第8.1节

Appendix B. Platform-Specific Implementation Details
附录B.特定于平台的实施细节

This document primarily defines best practices in a generic manner, referencing techniques commonly available in a variety of environments. This non-normative section documents implementation details of the best practice for various operating systems.

本文档主要以通用方式定义最佳实践,参考了各种环境中常用的技术。本非规范性章节记录了各种操作系统最佳实践的实施细节。

The implementation details herein are considered accurate at the time of publishing but will likely change over time. It is hoped that such a change won't invalidate the generic principles in the rest of the document and that those principles should take precedence in the event of a conflict.

本文中的实施细节在发布时被认为是准确的,但可能会随着时间的推移而改变。希望这样的更改不会使本文件其余部分中的通用原则无效,并且在发生冲突时应优先考虑这些原则。

B.1. iOS Implementation Details
B.1. iOS实施细节

Apps can initiate an authorization request in the browser, without the user leaving the app, through the "SFSafariViewController" class or its successor "SFAuthenticationSession", which implement the in-app browser tab pattern. Safari can be used to handle requests on old versions of iOS without in-app browser tab functionality.

应用程序可以通过“SFSafariViewController”类或其后续类“SFAuthenticationSession”在浏览器中发起授权请求,而无需用户离开应用程序,后者实现应用程序内浏览器选项卡模式。Safari可用于处理旧版本iOS上的请求,而无需应用程序内浏览器选项卡功能。

To receive the authorization response, both private-use URI scheme (referred to as "custom URL scheme") redirects and claimed "https" scheme URIs (known as "Universal Links") are viable choices. Apps can claim private-use URI schemes with the "CFBundleURLTypes" key in

为了接收授权响应,私有使用URI方案(称为“自定义URL方案”)重定向和声称的“https”方案URI(称为“通用链接”)都是可行的选择。应用程序可以声明具有“CbundleUrlTypes”密钥的私有URI方案

the application's property list file, "Info.plist", and "https" scheme URIs using the Universal Links feature with an entitlement file in the app and an association file hosted on the domain.

应用程序的属性列表文件“Info.plist”和“https”方案URI使用通用链接功能,应用程序中有一个授权文件,域上有一个关联文件。

Claimed "https" scheme URIs are the preferred redirect choice on iOS 9 and above due to the ownership proof that is provided by the operating system.

由于操作系统提供的所有权证明,声称的“https”方案URI是iOS 9及以上版本的首选重定向选择。

A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library.

AppAuth for iOS和macOS[AppAuth.iOSmacOS]库中包含了一个完整的开源示例。

B.2. Android Implementation Details
B.2. Android实现细节

Apps can initiate an authorization request in the browser, without the user leaving the app, through the Android Custom Tab feature, which implements the in-app browser tab pattern. The user's default browser can be used to handle requests when no browser supports Custom Tabs.

应用程序可以通过Android自定义选项卡功能在浏览器中发起授权请求,而无需用户离开应用程序,该功能实现了应用程序内浏览器选项卡模式。当没有浏览器支持自定义选项卡时,用户的默认浏览器可用于处理请求。

Android browser vendors should support the Custom Tabs protocol (by providing an implementation of the "CustomTabsService" class), to provide the in-app browser tab user-experience optimization to their users. Chrome is one such browser that implements Custom Tabs.

Android浏览器供应商应支持自定义选项卡协议(通过提供“CustomTabsService”类的实现),为其用户提供应用内浏览器选项卡用户体验优化。Chrome就是这样一种实现自定义选项卡的浏览器。

To receive the authorization response, private-use URI schemes are broadly supported through Android Implicit Intents. Claimed "https" scheme redirect URIs through Android App Links are available on Android 6.0 and above. Both types of redirect URIs are registered in the application's manifest.

为了接收授权响应,私有URI方案通过Android隐式意图得到广泛支持。声称的“https”方案通过Android应用程序链接重定向URI在Android 6.0及以上版本上可用。这两种类型的重定向URI都注册在应用程序的清单中。

A complete open-source sample is included in the AppAuth for Android [AppAuth.Android] library.

AppAuth for Android[AppAuth.Android]库中包含了一个完整的开源示例。

B.3. Windows Implementation Details
B.3. Windows实施详细信息

Both traditional and Universal Windows Platform (UWP) apps can perform authorization requests in the user's browser. Traditional apps typically use a loopback redirect to receive the authorization response, and listening on the loopback interface is allowed by default firewall rules. When creating the loopback network socket, apps SHOULD set the "SO_EXCLUSIVEADDRUSE" socket option to prevent other apps binding to the same socket.

传统和通用Windows平台(UWP)应用程序都可以在用户浏览器中执行授权请求。传统应用通常使用环回重定向来接收授权响应,默认防火墙规则允许监听环回接口。创建环回网络套接字时,应用程序应设置“SO_ExclusiveAdruse”套接字选项,以防止其他应用程序绑定到同一套接字。

UWP apps can use private-use URI scheme redirects to receive the authorization response from the browser, which will bring the app to the foreground. Known on the platform as "URI Activation", the URI

UWP应用程序可以使用专用URI方案重定向从浏览器接收授权响应,这将使应用程序进入前台。在平台上称为“URI激活”,URI

scheme is limited to 39 characters in length, and it may include the "." character, making short reverse domain name based schemes (as required in Section 7.1) possible.

方案长度限制为39个字符,并且可能包含“.”字符,使得基于短反向域名的方案(如第7.1节所要求)成为可能。

UWP apps can alternatively use the Web Authentication Broker API in Single Sign-on (SSO) mode, which is an external user-agent designed for authorization flows. Cookies are shared between invocations of the broker but not the user's preferred browser, meaning the user will need to log in again, even if they have an active session in their browser; but the session created in the broker will be available to subsequent apps that use the broker. Personalizations the user has made to their browser, such as configuring a password manager, may not be available in the broker. To qualify as an external user-agent, the broker MUST be used in SSO mode.

UWP应用程序也可以在单点登录(SSO)模式下使用Web身份验证代理API,该模式是为授权流设计的外部用户代理。Cookie在代理调用之间共享,但不是用户的首选浏览器,这意味着用户将需要再次登录,即使他们的浏览器中有活动会话;但在代理中创建的会话将可用于使用代理的后续应用程序。用户对其浏览器所做的个性化设置(如配置密码管理器)可能在代理中不可用。要成为外部用户代理,必须在SSO模式下使用代理。

To use the Web Authentication Broker in SSO mode, the redirect URI must be of the form "msapp://{appSID}" where "{appSID}" is the app's security identifier (SID), which can be found in the app's registration information or by calling the "GetCurrentApplicationCallbackUri" method. While Windows enforces the URI authority on such redirects, ensuring that only the app with the matching SID can receive the response on Windows, the URI scheme could be claimed by apps on other platforms without the same authority present; thus, this redirect type should be treated similarly to private-use URI scheme redirects for security purposes.

要在SSO模式下使用Web身份验证代理,重定向URI的格式必须为“msapp://{appSID}”,其中“{appSID}”是应用程序的安全标识符(SID),可以在应用程序的注册信息中或通过调用“GetCurrentApplicationCallbackUri”方法找到。虽然Windows对此类重定向强制执行URI权限,确保只有具有匹配SID的应用才能在Windows上接收响应,但URI方案可能会被其他平台上没有相同权限的应用声明;因此,出于安全目的,应将此重定向类型类似于专用URI方案重定向。

An open-source sample demonstrating these patterns is available [SamplesForWindows].

[SamplesForWindows]提供了一个演示这些模式的开源示例。

B.4. macOS Implementation Details
B.4. macOS实施细节

Apps can initiate an authorization request in the user's default browser using platform APIs for opening URIs in the browser.

应用程序可以使用平台API在浏览器中打开URI,在用户的默认浏览器中启动授权请求。

To receive the authorization response, private-use URI schemes are a good redirect URI choice on macOS, as the user is returned right back to the app they launched the request from. These are registered in the application's bundle information property list using the "CFBundleURLSchemes" key. Loopback IP redirects are another viable option, and listening on the loopback interface is allowed by default firewall rules.

为了接收授权响应,在macOS上,私用URI方案是一个很好的重定向URI选择,因为用户会直接返回到他们启动请求的应用程序。使用“CbundleUrlSchemes”键在应用程序的捆绑包信息属性列表中注册。环回IP重定向是另一个可行的选择,默认防火墙规则允许监听环回接口。

A complete open-source sample is included in the AppAuth for iOS and macOS [AppAuth.iOSmacOS] library.

AppAuth for iOS和macOS[AppAuth.iOSmacOS]库中包含了一个完整的开源示例。

B.5. Linux Implementation Details
B.5. Linux实现细节

Opening the authorization request in the user's default browser requires a distro-specific command: "xdg-open" is one such tool.

在用户的默认浏览器中打开授权请求需要一个特定于发行版的命令:“xdg open”就是这样一个工具。

The loopback redirect is the recommended redirect choice for desktop apps on Linux to receive the authorization response. Apps SHOULD NOT set the "SO_REUSEPORT" or "SO_REUSEADDR" socket options in order to prevent other apps binding to the same socket.

环回重定向是Linux上桌面应用程序接收授权响应的推荐重定向选择。应用程序不应设置“SO_REUSEPORT”或“SO_ReuseAdr”套接字选项,以防止其他应用程序绑定到同一套接字。

Acknowledgements

致谢

The authors would like to acknowledge the work of Marius Scurtescu and Ben Wiley Sittler, whose design for using private-use URI schemes in native app OAuth 2.0 clients at Google formed the basis of Section 7.1.

作者要感谢Marius Scurtescu和Ben Wiley Sittler的工作,他们在谷歌原生应用OAuth 2.0客户端中使用私有URI方案的设计构成了第7.1节的基础。

The following individuals contributed ideas, feedback, and wording that shaped and formed the final specification:

以下人员提供了形成最终规范的想法、反馈和措辞:

Andy Zmolek, Steven E. Wright, Brian Campbell, Nat Sakimura, Eric Sachs, Paul Madsen, Iain McGinniss, Rahul Ravikumar, Breno de Medeiros, Hannes Tschofenig, Ashish Jain, Erik Wahlstrom, Bill Fisher, Sudhi Umarji, Michael B. Jones, Vittorio Bertocci, Dick Hardt, David Waite, Ignacio Fiorentino, Kathleen Moriarty, and Elwyn Davies.

安迪·兹莫莱克、史蒂文·赖特、布赖恩·坎贝尔、纳特·樱村、埃里克·萨克斯、保罗·马德森、伊恩·麦金尼斯、拉胡尔·拉维库马尔、布伦诺·德梅德罗斯、汉内斯·茨霍芬尼、阿什·贾因、埃里克·沃尔斯特罗姆、比尔·费舍尔、苏迪·乌马吉、迈克尔·琼斯、维托里奥·贝尔托西、迪克·哈特、大卫·韦特、伊格纳西奥·佛罗伦萨、凯瑟琳·莫里亚蒂和埃尔温·戴维斯。

Authors' Addresses

作者地址

William Denniss Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 United States of America

威廉·丹尼斯谷歌1600圆形剧场美国加利福尼亚州山景城Pkwy,邮编94043

   Email: rfc8252@wdenniss.com
   URI:   http://wdenniss.com/appauth
        
   Email: rfc8252@wdenniss.com
   URI:   http://wdenniss.com/appauth
        

John Bradley Ping Identity

约翰·布拉德利·平身份

   Phone: +1 202-630-5272
   Email: rfc8252@ve7jtb.com
   URI:   http://www.thread-safe.com/p/appauth.html
        
   Phone: +1 202-630-5272
   Email: rfc8252@ve7jtb.com
   URI:   http://www.thread-safe.com/p/appauth.html