重定向 URI（回复 URL）概述和限制
为了将用户登录，应用程序必须将登录请求发送到 Microsoft Entra 授权终结点，并将一个重定向 URI 指定为参数。 重定向 URI 是一项关键安全功能，可确保 Microsoft Entra 身份验证服务器仅向预期的接收方发送授权代码和访问令牌。 本文概述了 Microsoft 标识平台中重定向 URI 的功能和限制。
什么是重定向 URI？
重定向 URI（或回复 URL）是在为应用成功授权并为其授予访问令牌后，Microsoft Entra 身份验证服务器将用户发送到的位置。 若要让用户登录，应用程序必须发送一个登录请求并将重定向 URI 指定为参数，因此在用户成功登录后，身份验证服务器将重定向用户，并向登录请求中指定的重定向 URI 颁发访问令牌。
为何需要在应用注册中添加重定向 URI？
出于安全原因，身份验证服务器不会重定向用户或向未添加到应用注册的 URI 发送令牌。 Microsoft Entra 登录服务器只会将用户重定向到或者将令牌发送到已添加到应用注册的重定向 URI。 如果在登录请求中指定的重定向 URI 不与你在应用程序中添加的任何重定向 URI 匹配，则会收到一条错误消息，例如 AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application。
有关错误代码的详细信息，请参阅 Microsoft Entra 身份验证和授权错误代码。
是否应该向应用注册添加重定向 URI？
是否应该向应用注册添加重定向 URI 取决于应用程序使用的授权协议。 如果应用程序使用以下授权协议，则必须向应用注册添加适当的重定向 URI：
如果应用程序使用以下授权协议或功能，则无需向应用注册添加重定向 URI。
- 本机身份验证
- OAuth 2.0 设备代码流
- OAuth 2.0 代理流
- OAuth 2.0 资源所有者密码凭据流
- Windows 集成身份验证流
- 用于单一登录的 SAML 2.0 标识提供者 (IdP)
应将重定向 URI 添加到哪个平台？
如果要构建的应用程序在应用注册中包含一个或多个重定向 URI，则需要启用一个公共客户端流配置。 以下各表提供了有关以下内容的指导：根据构建应用程序的平台，应当或不应当添加的重定向 URI 的类型。
Web 应用程序重定向 URI 配置
| 应用程序的类型 | 典型语言/框架 | 要在应用注册中添加重定向 URI 的平台 |
|---|---|---|
| 传统 Web 应用程序，其中大多数应用程序逻辑在服务器上执行 | Node.js、Web、ASP.NET、Python、Java、ASP.NET Core、PHP、Ruby、Blazor Server | Web |
| 单页应用程序，其中大多数用户界面逻辑在主要使用 Web API 与 Web 服务器进行通信的 Web 浏览器中执行 | JavaScript、Angular、React、Blazor WebAssembly、Vue.js | 单页面应用程序 (SPA) |
移动和桌面应用程序重定向 URI 配置
| 应用程序的类型 | 典型语言/框架 | 要在应用注册中添加重定向 URI 的平台 |
|---|---|---|
| iOS 或 macOS 应用，不包括此表下方列出的方案 | Swift、Objective-C、Xamarin | IOS/macOS |
| Android 应用 | Java、Kotlin、Xamarin | Android |
| 原生在移动设备或台式机上运行的应用 | Node.js electron、Windows 桌面、UWP、React Native、Xamarin、Android、iOS/macOS | 移动和桌面应用程序 |
如果要使用以下方法之一构建 iOS 应用，请使用移动和桌面应用程序平台来添加重定向 URI：
- 使用旧版 SDK (ADAL) 的 iOS 应用
- 使用开源 SDK (AppAuth) 的 iOS 应用
- 使用我们不支持的跨平台技术 (Flutter) 的 iOS 应用
- 直接实施了 OAuth 协议的 iOS 应用
- 使用我们不支持的跨平台技术 (Electron) 的 macOS 应用
不需要重定向 URI 的应用程序
| 应用程序类型 | 示例/说明 | 关联的 OAuth 流 |
|---|---|---|
| 在没有键盘的设备上运行的应用程序 | 在智能电视、IoT 设备或打印机上运行的应用程序 | 设备代码流了解详细信息 |
| 直接处理用户输入的密码的应用程序，这类应用程序不将用户重定向到 Entra 托管的登录网站来让 Entra 以安全的方式处理用户密码。 | 只有当其他更安全的流（例如授权代码流）由于不安全而不可行时，才应该使用此流。 | 资源所有者密码凭据流了解详细信息 |
| 在使用 Windows 集成身份验证流（而非 Web 帐户管理器）连接到 Windows 域（已加入 AD 或 Azure AD）的计算机上运行的桌面或移动应用程序 | 在用户使用 Entra 凭据登录到 Windows 电脑系统后应自动登录的桌面或移动应用程序 | Windows 集成身份验证流了解详细信息 |
Microsoft Entra 应用程序的重定向 URI 有哪些限制？
Microsoft Entra 应用程序模型对重定向 URI 指定了以下限制：
重定向 URI 必须以方案
https开头，但某些 localhost 重定向 URI 例外。重定向 URI 区分大小写，并且必须与正在运行的应用程序的 URL 路径的大小写相匹配。
示例：
- 如果应用程序在其路径中包括
.../abc/response-oidc，请不要在重定向 URI 中指定.../ABC/response-oidc。 由于 Web 浏览器将路径视为区分大小写，因此在重定向到大小写不匹配的.../ABC/response-oidcURL 时，可能会排除与.../abc/response-oidc关联的 cookie。
- 如果应用程序在其路径中包括
未配置路径段的重定向URI会在响应中返回，并带有尾部斜杠 ('
/')。 仅当响应模式为query或fragment时才适用。示例：
https://contoso.com返回为https://contoso.com/http://localhost:7071返回为http://localhost:7071/
包含路径段的重定向 URI 不会在响应中附加尾部斜杠。
示例：
https://contoso.com/abc返回为https://contoso.com/abchttps://contoso.com/abc/response-oidc返回为https://contoso.com/abc/response-oidc
重定向 URI 不支持特殊字符 -
! $ ' ( ) , ;
重定向 URI 的最大数量和 URI 长度
出于安全原因，无法提高重定向 URI 的最大数量。 如果方案所需的重定向 URI 数目超过允许的最大限制，请考虑使用以下状态参数方法作为解决方案。 下表显示了可以在 Microsoft 标识平台中添加到应用注册的重定向 URI 的最大数目。
| 正在登录的帐户 | 重定向 URI 的最大数量 | 说明 |
|---|---|---|
| 任何组织的 Microsoft Entra 租户中的 Microsoft 工作或学校帐户 | 256 | 应用程序清单中的 signInAudience 字段设置为 AzureADMyOrg 或 AzureADMultipleOrgs |
| 个人 Microsoft 帐户以及工作和学校帐户 | 100 | 应用程序清单中的 signInAudience 字段设置为 AzureADandPersonalMicrosoftAccount |
对于要添加到应用注册中的每个重定向 URI，最多可以使用 256 个字符。
重定向应用程序对象与服务主体对象中的 URI
- 始终只将重定向 URI 添加到应用程序对象。
- 不要将重定向 URI 值添加到服务主体，因为当服务主体对象与应用程序对象同步时，可能会删除这些值。 之所以会发生这种情况，可能是因为存在触发两个对象之间的同步的更新操作。
重定向 URI 中的查询参数支持
对于仅使用工作或学校帐户登录用户的应用程序，在重定向 URI 中允许使用查询参数。
对于配置为使用 Outlook.com (Hotmail)、Messenger、OneDrive、MSN、Xbox Live 或 Microsoft 365 等个人 Microsoft 帐户登录用户的任何应用注册，不允许在重定向 URI 中使用查询参数。
| 应用注册登录受众 | 支持重定向 URI 中的查询参数 |
|---|---|
| 仅限此组织目录中的帐户（仅限 Contoso - 单租户） | 
|
| 任何组织目录中的帐户（任何 Microsoft Entra 目录 - 多租户） |
|
| 任何组织目录中的帐户（任何 Microsoft Entra 目录 - 多租户）和个人 Microsoft 帐户（例如 Skype、Xbox） | 
|
| 仅 Microsoft 个人帐户 |
|
支持的方案
HTTPS：所有基于 HTTP 的重定向 URI 均支持 HTTPS 方案 (https://)。
HTTP：仅 localhost URI 支持 HTTP 方案 (http://)，并且仅应在活动的本地应用程序开发和测试期间使用。
| 重定向 URI 示例 | 有效期 |
|---|---|
https://contoso.com |
有效 |
https://contoso.com/abc/response-oidc |
有效 |
https://localhost |
有效 |
http://contoso.com/abc/response-oidc |
无效 |
http://localhost |
有效 |
http://localhost/abc |
有效 |
Localhost 例外
RFC 8252 8.3 节和 7.3 节指出，“环回”或“localhost”重定向 URI 有两个特殊的注意事项：
httpURI 方案是可接受的，因为重定向绝不会离开设备。 因此，下面这两个 URI 都是可接受的：http://localhost/myApphttps://localhost/myApp
- 由于原生应用程序经常需要临时端口范围，因此，在匹配重定向 URI 时会忽略端口组件（例如
:5001或:443）。 因此，下面所有这些 URI 都被视为等效：http://localhost/MyApphttp://localhost:1234/MyApphttp://localhost:5000/MyApphttp://localhost:8080/MyApp
从开发的角度来看，这意味着：
不要注册多个只有端口不同的重定向 URI。 登录服务器会任意选取一个，并使用与该重定向 URI 关联的行为（例如，不管它是
web类型的、native类型的还是spa类型的重定向，都会这样做）。当你想在同一应用程序注册中使用不同的身份验证流（例如，授权代码授予和隐式流）时，这尤其重要。 若要将正确的响应行为与每个重定向 URI 相关联，登录服务器必须能够区分重定向 URI，在只有端口不同的情况下不能这样做。
若要在 localhost 上注册多个重定向 URI，以在开发过程中测试不同的流，请使用 URI 的 path 组件来区分它们。 例如，
http://localhost/MyWebApp与http://localhost/MyNativeApp不匹配。当前不支持 IPv6 环回地址 (
[::1])。
首选 127.0.0.1，而不是 localhost
若要防止应用由于配置不当的防火墙或重命名的网络接口而中断，请使用重定向 URI 中的 IP 文本环回地址 127.0.0.1，而不是使用 localhost。 例如 https://127.0.0.1。
但不能使用 Azure 门户中“重定向 URI”文本框添加基于环回且使用 http 方案的重定向 URI：
若要添加在 127.0.0.1 环回地址中使用 http 方案的重定向 URI，当前必须修改应用程序清单中的 replyUrlsWithType 属性。
重定向 URI 中对通配符的限制
类似 https://*.contoso.com 的通配符 URI 可能看起来很方便，但由于安全方面的影响，应避免使用它们。 根据 OAuth 2.0 规范（RFC 6749 第 3.1.2 部分），重定向终结点 URI 必须是绝对 URI。 因此，当配置的通配符 URI 与重定向 URI 匹配时，将去除重定向 URI 中的查询字符串和片段。
对于配置为登录个人 Microsoft 帐户以及工作或学校帐户的应用注册，目前不支持通配符 URI。 但是，对于组织的 Microsoft Entra 租户中配置为仅将工作帐户或学校帐户登录的应用，允许使用通配符 URI。
若要将具有通配符的重定向 URI 添加到用于登录工作帐户或学校帐户的应用注册，请使用 Azure 门户的应用注册中的应用程序清单编辑器。 虽然可以通过使用清单编辑器来设置带通配符的重定向 URI，但我们还是强烈建议你遵循 RFC 6749 的 3.1.2 节的要求， 只使用绝对 URI。
如果方案所需的重定向 URI 数目超过允许的最大限制，请考虑以下状态参数方法，而不要添加通配符重定向 URI。
使用状态参数
如果你有多个子域，并且你的方案要求在身份验证成功时将用户重定向到开始操作时所在的页面，则使用状态参数可能有帮助。
在此方法中：
- 为每个应用程序创建一个“共享的”重定向 URI，用于处理从授权终结点收到的安全令牌。
- 应用程序可以在状态参数中发送应用程序特定的参数（例如用户的来源子域 URL，或品牌信息等）。 使用状态参数时，请按照 RFC 6749 的第 10.12 部分中的规定提供 CSRF 保护措施。
- 特定于应用程序的参数包含应用程序为用户呈现正确体验（即构造相应的应用程序状态）所需的所有信息。 Microsoft Entra 授权终结点从状态参数中提取 HTML，因此请确保不在此参数中传递 HTML 内容。
- 当 Microsoft Entra 将响应发送到“共享”重定向 URI 时，它会将状态参数发回给应用程序。
- 然后，应用程序可以使用状态参数中的值来确定要进一步将用户发送到哪个 URL。 确保验证 CSRF 保护措施。
警告
此方法允许遭到攻击的客户端修改状态参数中发送的其他参数，从而将用户重定向到其他 URL，这就是 RFC 6819 中所述的开放重定向程序威胁。 因此，客户端必须对状态加密或通过其他一些方式进行验证（如根据令牌验证重定向 URI 中的域名），从而保护这些参数。
后续步骤
了解应用注册应用程序清单。