重定向 URI(回复 URL)限制和局限Redirect URI (reply URL) restrictions and limitations

重定向 URI(或回复 URL)是在为应用成功授权并为其授予授权代码或访问令牌后,授权服务器将用户发送到的位置。A redirect URI, or reply URL, is the location where the authorization server sends the user once the app has been successfully authorized and granted an authorization code or access token. 授权服务器将代码或令牌发送到重定向 URI,因此在应用注册过程中注册正确的位置非常重要。The authorization server sends the code or token to the redirect URI, so it's important you register the correct location as part of the app registration process.

重定向 URI 存在以下限制:The following restrictions apply to redirect URIs:

  • 重定向 URI 必须以方案 https 开头。The redirect URI must begin with the scheme https. 有一些 localhost 重定向 URI 例外There are some exceptions for localhost redirect URIs.

  • 重定向 URI 区分大小写。The redirect URI is case-sensitive. 其大小写必须与正在运行的应用程序的 URL 路径的大小写匹配。Its case must match the case of the URL path of your running application. 例如,如果应用程序在其路径中包括 .../abc/response-oidc,请不要在重定向 URI 中指定 .../ABC/response-oidcFor example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the redirect URI. 由于 Web 浏览器将路径视为区分大小写,因此在重定向到大小写不匹配的 .../ABC/response-oidc URL 时,可能会排除与 .../abc/response-oidc 关联的 cookie。Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc may be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.

重定向 URI 的最大数量Maximum number of redirect URIs

此表显示了可以在 Microsoft 标识平台中添加到应用注册的重定向 URI 的最大数目。This table shows the maximum number of redirect URIs you can add to an app registration in the Microsoft identity platform.

正在登录的帐户Accounts being signed in 最大重定向 URI 数Maximum number of redirect URIs 说明Description
任何组织的 Azure Active Directory (Azure AD) 租户中的 Microsoft 工作或学校帐户Microsoft work or school accounts in any organization's Azure Active Directory (Azure AD) tenant 256256 应用程序清单中的 signInAudience 字段设置为 AzureADMyOrgAzureADMultipleOrgssignInAudience field in the application manifest is set to either AzureADMyOrg or AzureADMultipleOrgs

最大 URI 长度Maximum URI length

对于要添加到应用注册中的每个重定向 URI,最多可以使用 256 个字符。You can use a maximum of 256 characters for each redirect URI you add to an app registration.

支持的方案Supported schemes

Azure Active Directory (Azure AD) 应用程序模型目前同时支持 HTTP 和 HTTPS 方案,这两种方案所针对的应用可以在任何组织的 Azure AD 租户中登录工作或学校帐户。The Azure Active Directory (Azure AD) application model currently supports both HTTP and HTTPS schemes for apps that sign in work or school accounts in any organization's Azure AD tenant. 这些帐户类型由应用程序清单的 signInAudience 字段中的 AzureADMyOrgAzureADMultipleOrgs 值指定。These account types are specified by the AzureADMyOrg and AzureADMultipleOrgs values in the signInAudience field of the application manifest.

若要将具有 HTTP 方案的重定向 URI 添加到用于登录工作帐户或学校帐户的应用注册,需要使用 Azure 门户的应用注册中的应用程序清单编辑器。To add redirect URIs with an HTTP scheme to app registrations that sign in work or school accounts, you need to use the application manifest editor in App registrations in the Azure portal. 虽然可以使用清单编辑器来设置基于 HTTP 的重定向 URI,但我们强烈建议你为重定向 URI 使用 HTTPS 方案。However, though it's possible to set an HTTP-based redirect URI by using the manifest editor, we strongly recommend that you use the HTTPS scheme for your redirect URIs.

Localhost 例外Localhost exceptions

RFC 8252 8.3 节7.3 节指出,“环回”或“localhost”重定向 URI 有两个特殊的注意事项:Per RFC 8252 sections 8.3 and 7.3, "loopback" or "localhost" redirect URIs come with two special considerations:

  1. http URI 方案是可接受的,因为重定向绝不会离开设备。http URI schemes are acceptable because the redirect never leaves the device. 因此,下面这两个都是可接受的:As such, both of these are acceptable:
    • http://127.0.0.1/myApp
    • https://127.0.0.1/myApp
  2. 由于原生应用程序经常需要临时端口范围,因此,在匹配重定向 URI 时会忽略端口组件(例如 :5001:443)。Due to ephemeral port ranges often required by native applications, the port component (for example, :5001 or :443) is ignored for the purposes of matching a redirect URI. 因此,下面所有这些都被视为等效项:As a result, all of these are considered equivalent:
    • http://127.0.0.1/MyApp
    • http://127.0.0.1:1234/MyApp
    • http://127.0.0.1:5000/MyApp
    • http://127.0.0.1:8080/MyApp

从开发的角度来看,这意味着:From a development standpoint, this means a few things:

  • 不要注册多个只有端口不同的重定向 URI。Do not register multiple redirect URIs where only the port differs. 登录服务器会任意选择一个,并使用与该重定向 URI 关联的行为(例如,是 web 类型的、native 类型的还是 spa 类型的重定向)。The login server will pick one arbitrarily and use the behavior associated with that redirect URI (for example, whether it's web-, native-, or spa-type redirect).

  • 如果需要在 localhost 上注册多个重定向 URI,以在开发过程中测试不同的流,请使用 URI 的 path 组件来区分它们。If you need to register multiple redirect URIs on localhost to test different flows during development, differentiate them using the path component of the URI. 例如,http://127.0.0.1/MyWebApphttp://127.0.0.1/MyNativeApp 不匹配。For example, http://127.0.0.1/MyWebApp doesn't match http://127.0.0.1/MyNativeApp.

  • 当前不支持 IPv6 环回地址 ([::1])。The IPv6 loopback address ([::1]) is not currently supported.

  • 若要防止应用被错误配置的防火墙或重命名的网络接口中断,请使用重定向 URI 中的 IP 文本环回地址 127.0.0.1,而不是使用 localhostTo prevent your app from being broken by misconfigured firewalls or renamed network interfaces, use the IP literal loopback address 127.0.0.1 in your redirect URI instead of localhost.

    若要在 IP 文本环回地址 127.0.0.1 中使用 http 方案,当前必须修改应用程序清单中的 replyUrlsWithType 属性。To use the http scheme with the IP literal loopback address 127.0.0.1, you must currently modify the replyUrlsWithType attribute in the application manifest.

重定向 URI 中对通配符的限制Restrictions on wildcards in redirect URIs

类似 https://*.contoso.com 的通配符 URI 可能看起来很方便,但由于安全方面的影响,应避免使用它们。Wildcard URIs like https://*.contoso.com may seem convenient, but should be avoided due to security implications. 根据 OAuth 2.0 规范(RFC 6749 第 3.1.2 部分),重定向终结点 URI 必须是绝对 URI。According to the OAuth 2.0 specification (section 3.1.2 of RFC 6749), a redirection endpoint URI must be an absolute URI.

配置为将工作帐户或学校帐户登录的应用注册当前不支持通配符 URI。Wildcard URIs are currently unsupported in app registrations configured to sign in work or school accounts. 但是,对于组织的 Azure AD 租户中配置为仅将工作帐户或学校帐户登录的应用,允许使用通配符 URI。Wildcard URIs are allowed, however, for apps that are configured to sign in only work or school accounts in an organization's Azure AD tenant.

若要将具有通配符的重定向 URI 添加到用于登录工作帐户或学校帐户的应用注册,需要使用 Azure 门户的应用注册中的应用程序清单编辑器。To add redirect URIs with wildcards to app registrations that sign in work or school accounts, you need to use the application manifest editor in App registrations in the Azure portal. 尽管可以使用清单编辑器来设置具有通配符的重定向 URI,但我们强烈建议你遵循 RFC 6749 的 3.1.2 节的要求,仅使用绝对 URI。Though it's possible to set a redirect URI with a wildcard by using the manifest editor, we strongly recommend you adhere to section 3.1.2 of RFC 6749 and use only absolute URIs.

如果方案所需的重定向 URI 数目超过允许的最大限制,请考虑以下状态参数方法,而不要添加通配符重定向 URI。If your scenario requires more redirect URIs than the maximum limit allowed, consider the following state parameter approach instead of adding a wildcard redirect URI.

使用状态参数Use a state parameter

如果你有多个子域,并且你的方案要求在身份验证成功时将用户重定向到开始操作时所在的页面,则使用状态参数可能有帮助。If you have several subdomains and your scenario requires that, upon successful authentication, you redirect users to the same page from which they started, using a state parameter might be helpful.

在此方法中:In this approach:

  1. 为每个应用程序创建一个“共享的”重定向 URI,用于处理从授权终结点收到的安全令牌。Create a "shared" redirect URI per application to process the security tokens you receive from the authorization endpoint.
  2. 应用程序可以在状态参数中发送应用程序特定的参数(例如用户的来源子域 URL,或品牌信息等)。Your application can send application-specific parameters (such as subdomain URL where the user originated or anything like branding information) in the state parameter. 使用状态参数时,请根据 RFC 6749 第 10.12 部分中的规定提供 CSRF 保护措施。When using a state parameter, guard against CSRF protection as specified in section 10.12 of RFC 6749).
  3. 应用程序特定的参数包含应用程序为用户呈现正确体验(即,构造相应的应用程序状态)所需的所有信息。The application-specific parameters will include all the information needed for the application to render the correct experience for the user, that is, construct the appropriate application state. Azure AD 授权终结点会去除状态参数中的 HTML,因此请确保不要在此参数中传递 HTML 内容。The Azure AD authorization endpoint strips HTML from the state parameter so make sure you are not passing HTML content in this parameter.
  4. 当 Azure AD 向“共享的”重定向 URI 发送响应时,会将状态参数发回到应用程序。When Azure AD sends a response to the "shared" redirect URI, it will send the state parameter back to the application.
  5. 然后,应用程序可以使用状态参数中的值来确定要进一步将用户发送到哪个 URL。The application can then use the value in the state parameter to determine which URL to further send the user to. 确保验证 CSRF 保护措施。Make sure you validate for CSRF protection.

警告

此方法允许遭到攻击的客户端修改状态参数中发送的其他参数,从而将用户重定向到其他 URL,这就是 RFC 6819 中所述的开放重定向程序威胁This approach allows a compromised client to modify the additional parameters sent in the state parameter, thereby redirecting the user to a different URL, which is the open redirector threat described in RFC 6819. 因此,客户端必须对状态加密或通过其他一些方式进行验证(如根据令牌验证重定向 URI 中的域名),从而保护这些参数。Therefore, the client must protect these parameters by encrypting the state or verifying it by some other means, like validating the domain name in the redirect URI against the token.

后续步骤Next steps

了解应用注册应用程序清单Learn about the app registration Application manifest.