重定向 URI（回复 URL）概述和限制

构建与Microsoft标识平台集成的应用程序时，了解如何配置重定向 URI 至关重要。 本文提供了重定向 URI 最佳做法、支持的配置和限制的综合指南。 无论是开发 Web、移动应用程序还是桌面应用程序，本文都将帮助你正确配置重定向 URI 以满足安全要求。

重定向 URI（或回复 URL）是在为应用成功授权并为其授予访问令牌后，Microsoft Entra 身份验证服务器将用户发送到的位置。 若要让用户登录，应用程序必须发送一个登录请求并将重定向 URI 指定为参数，因此在用户成功登录后，身份验证服务器将重定向用户，并向登录请求中指定的重定向 URI 颁发访问令牌。

例如，在生产 Web 应用程序中，重定向 URI 通常是运行应用的公共终结点，比如 https://contoso.com/auth-response。 在开发过程中，通常还会添加在本地运行应用的终结点，例如 https://127.0.0.1/auth-response 或 http://localhost/auth-response。 请确保生产应用中未公开任何非必要的开发环境/重定向 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：

• OAuth 2.0 授权代码流
• OAuth 2.0 客户端凭据流
• OAuth 2.0 隐式授权流
• OpenID Connect

如果应用程序使用以下授权协议或功能，则无需向应用注册添加重定向 URI。

• OAuth 2.0 设备代码流
• OAuth 2.0 代理流
• OAuth 2.0 资源所有者密码凭据流
• Windows 集成身份验证流
• 用于单一登录的 SAML 2.0 标识提供者 (IdP)

如果要构建的应用程序在应用注册中包含一个或多个重定向 URI，则需要启用一个公共客户端流配置。 以下各表提供了有关以下内容的指导：根据构建应用程序的平台，应当或不应当添加的重定向 URI 的类型。

如果要使用以下方法之一构建 iOS 应用，请使用移动和桌面应用程序平台来添加重定向 URI：

• 使用旧版 SDK (ADAL) 的 iOS 应用
• 使用开源 SDK (AppAuth) 的 iOS 应用
• 使用我们不支持的跨平台技术 (Flutter) 的 iOS 应用
• 直接实施了 OAuth 协议的 iOS 应用
• 使用我们不支持的跨平台技术 (Electron) 的 macOS 应用

Microsoft Entra 应用程序模型对重定向 URI 指定了以下限制：

• 重定向 URI 必须以方案 https 开头，但某些 localhost 重定向 URI 例外。

• 重定向 URI 区分大小写，并且必须与正在运行的应用程序的 URL 路径的大小写相匹配。

  示例：

  • 如果应用程序在其路径中包括 .../abc/response-oidc，请不要在重定向 URI 中指定 .../ABC/response-oidc。 由于 Web 浏览器将路径视为区分大小写，因此在重定向到大小写不匹配的 .../abc/response-oidc URL 时，可能会排除与 .../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/abc
  • https://contoso.com/abc/response-oidc 返回为 https://contoso.com/abc/response-oidc

• 重定向 URI 不支持特殊字符 - ! $ ' ( ) , ;

• 重定向 URI 不支持 国际化域名

出于安全原因，无法提高重定向 URI 的最大数量。 如果方案所需的重定向 URI 数目超过允许的最大限制，请考虑使用以下状态参数方法作为解决方案。 下表显示了可以在 Microsoft 标识平台中添加到应用注册的重定向 URI 的最大数目。

对于要添加到应用注册中的每个重定向 URI，最多可以使用 256 个字符。

• 始终只将重定向 URI 添加到应用程序对象。
• 不要将重定向 URI 值添加到服务主体，因为当服务主体对象与应用程序对象同步时，可能会删除这些值。 之所以会发生这种情况，可能是因为存在触发两个对象之间的同步的更新操作。

对于仅使用工作或学校帐户登录用户的应用程序，在重定向 URI 中允许使用查询参数。

应用注册登录受众	支持重定向 URI 中的查询参数
仅限此组织目录中的帐户（仅限 Contoso - 单租户）
任何组织目录中的帐户（任何 Microsoft Entra 目录 - 多租户）

HTTPS：所有基于 HTTP 的重定向 URI 均支持 HTTPS 方案 ()。

HTTP：仅 localhost URI 支持 HTTP 方案 ()，并且仅应在活动的本地应用程序开发和测试期间使用。

RFC 8252 8.3 节和 7.3 节指出，“环回”或“localhost”重定向 URI 有两个特殊的注意事项：

1. http URI 方案是可接受的，因为重定向绝不会离开设备。 因此，下面这两个 URI 都是可接受的：
   • http://localhost/myApp
   • https://localhost/myApp
2. 由于原生应用程序经常需要临时端口范围，因此，在匹配重定向 URI 时会忽略端口组件（例如 :5001 或 :443）。 因此，下面所有这些 URI 都被视为等效：
   • http://localhost/MyApp
   • http://localhost:1234/MyApp
   • http://localhost:5000/MyApp
   • http://localhost:8080/MyApp

从开发的角度来看，这意味着：

• 不要注册多个只有端口不同的重定向 URI。 登录服务器会任意选取一个，并使用与该重定向 URI 关联的行为（例如，不管它是 web 类型的、native 类型的还是 spa 类型的重定向，都会这样做）。

  当你想在同一应用程序注册中使用不同的身份验证流（例如，授权代码授予和隐式流）时，这尤其重要。 若要将正确的响应行为与每个重定向 URI 相关联，登录服务器必须能够区分重定向 URI，在只有端口不同的情况下不能这样做。

• 若要在 localhost 上注册多个重定向 URI，以在开发过程中测试不同的流，请使用 URI 的 path 组件来区分它们。 例如，http://localhost/MyWebApp 与 http://localhost/MyNativeApp 不匹配。

• 当前不支持 IPv6 环回地址 ([::1])。

若要防止应用由于配置不当的防火墙或重命名的网络接口而中断，请使用重定向 URI 中的 IP 文本环回地址 127.0.0.1，而不是使用 localhost。 例如 https://127.0.0.1。

但不能使用 Azure 门户中“重定向 URI”文本框添加基于环回且使用 方案的重定向 URIhttp：

若要添加在 http 环回地址中使用 127.0.0.1 方案的重定向 URI，当前必须修改应用程序清单中的 replyUrlsWithType 属性。

类似 https://*.contoso.com 的通配符 URI 可能看起来很方便，但由于安全方面的影响，应避免使用它们。 根据 OAuth 2.0 规范（RFC 6749 第 3.1.2 部分），重定向终结点 URI 必须是绝对 URI。 因此，当配置的通配符 URI 与重定向 URI 匹配时，将去除重定向 URI 中的查询字符串和片段。

配置为将工作帐户或学校帐户登录的应用注册当前不支持通配符 URI。 但是，对于组织的 Microsoft Entra 租户中配置为仅将工作帐户或学校帐户登录的应用，允许使用通配符 URI。

若要将具有通配符的重定向 URI 添加到用于登录工作帐户或学校帐户的应用注册，请使用 Azure 门户的应用注册中的应用程序清单编辑器。 虽然可以通过使用清单编辑器来设置带通配符的重定向 URI，但我们还是强烈建议你遵循 RFC 6749 的 3.1.2 节的要求， 只使用绝对 URI。

如果方案所需的重定向 URI 数目超过允许的最大限制，请考虑以下状态参数方法，而不要添加通配符重定向 URI。

如果你有多个子域，并且你的方案要求在身份验证成功时将用户重定向到开始操作时所在的页面，则使用状态参数可能有帮助。

在此方法中：

1. 为每个应用程序创建一个“共享的”重定向 URI，用于处理从授权终结点收到的安全令牌。
2. 应用程序可以在状态参数中发送应用程序特定的参数（例如用户的来源子域 URL，或品牌信息等）。 使用状态参数时，请按照 RFC 6749 的第 10.12 部分中的规定提供 CSRF 保护措施。
3. 特定于应用程序的参数包含应用程序为用户呈现正确体验（即构造相应的应用程序状态）所需的所有信息。 Microsoft Entra 授权终结点从状态参数中提取 HTML，因此请确保不在此参数中传递 HTML 内容。
4. 当 Microsoft Entra 将响应发送到“共享”重定向 URI 时，它会将状态参数发回给应用程序。
5. 然后，应用程序可以使用状态参数中的值来确定要进一步将用户发送到哪个 URL。 确保验证 CSRF 保护措施。

了解应用注册应用程序清单。