Microsoft Entra 应用程序中标识符 URI 限制

identifierUri - 也称为 Application ID URI - 的 Microsoft Entra 应用程序属性通常配置在资源（API）应用程序上。 安全地配置此属性对于资源的安全性至关重要。

安全模式

支持以下基于 API 和 HTTP 方案的应用程序 ID URI 格式。 替换表后列表中描述的占位符值。

• <appId> - 应用程序对象的应用程序标识符 (appId) 属性。
• <string> - 主机或 API 路径段的字符串值。
• <tenantId> - Azure 生成的 GUID，用于表示 Azure 中的租户。
• <tenantInitialDomain> - <tenantInitialDomain>.partner.onmschina.cn，其中 <tenantInitialDomain> 是租户创建者在创建租户时指定的初始域名。
• <verifiedCustomDomain> - 为 Microsoft Entra 租户配置的已验证的自定义域。

使用策略强制实施安全模式

Microsoft引入了一个安全设置，该设置可防止Microsoft Entra 应用程序上标识符 URI（也称为“应用 ID URI”）的不安全配置。 此安全设置可确保 v1 应用程序上新添加的 URI 符合上述 安全模式 。

策略行为

启用此设置后，将严格执行安全模式。 启用后，如果组织中的任何人尝试添加不符合 安全模式的标识符 URI，它们将收到如下错误：

Failed to add identifier URI {uri}. All newly added URIs must contain a tenant verified domain, tenant ID, or app ID, as per the default tenant policy of your organization. See https://aka.ms/identifier-uri-addition-error for more information on this error.

默认情况下，通过将应用程序的api.requestedAccessTokenVersion属性设置为2以配置为使用 v2.0 Entra ID 令牌的应用程序会被自动豁免。 默认情况下，配置为使用 SAML 协议进行 SSO 的应用程序，通过将服务主体的属性设置为preferredSingleSignOnModeSAML，也会自动获得豁免。

应用上已配置的现有标识符 URI 不会受到影响，所有应用将继续正常运行。 这只会影响Microsoft Entra 应用配置的新更新。

如果未启用，仍可使用某些不安全模式。 例如，仍可以添加格式 api://{string} 的 URI。 但是，即使禁用了设置，在某些情况下，仍然可能需要验证过的租户或初始域，例如，使用 https:// 计划时。

启用和管理策略

Microsoft可能已在组织中启用此策略以提高其安全性。 可以通过运行 此脚本进行检查。

即使Microsoft在你的组织中启用了策略，租户管理员仍可以完全控制该策略。 他们可以向特定Microsoft Entra 应用程序、自己、组织中的其他用户或组织使用的任何服务或进程 授予豁免 。 或者，管理员可以 禁用策略 （不建议）。

如果 Microsoft 检测到贵组织的流程可能因更改而受到干扰，则不会在组织中启用该策略。 相反，组织中的管理员可以 自行启用它 （建议）。

开发人员指南

如果你是开发人员，并且你尝试将标识符 URI（也称为应用 ID URI）添加到你拥有的 Microsoft Entra API，但收到 此错误，请阅读此部分。

可以通过三种方法将标识符 URI 添加到应用。 我们推荐它们的顺序如下。

1. 使用安全 URI 模式之一

2. 如果遇到此错误，则表示 API 当前使用 v1.0 令牌。 通过更新服务以接受 v2.0 令牌，您可以解除封锁。 V2.0 令牌类似于 v1.0，但存在一些 差异。 服务能够处理 v2.0 令牌后，可以更新应用配置，以便Microsoft Entra 向其发送 v2.0 令牌。 执行此操作的一种简单方法是在 Microsoft Entra 管理中心应用注册功能中通过清单编辑器：

   

   但是，在 进行此更改时，应谨慎行事。 这是因为应用已更新为 v2.0 令牌格式后，如果已配置不符合标识符 URI，则无法切换回 v1.0 令牌，除非已获得豁免（请参阅选项 3）。

3. 如果需要在更新到 v2.0 令牌格式之前向应用添加不符合的标识符 URI，可以请求管理员 向应用授予豁免。

其他安全设置

Microsoft还提供对identifierUris属性更为严格的安全策略。 此限制性更高的策略称为 nonDefaultUriAddition。

启用此保护后，除了已知安全方案之外，无法将新的自定义标识符 URI 添加到该组织中的任何应用程序。 具体而言，如果满足以下任一条件，仍可添加标识符 URI：

• 要添加到应用的标识符 URI 是“默认”URI 之一，这意味着它采用 api://{appId} 或 api://{tenantId}/{appId}
• 应用接受 v2.0 Entra 令牌。 如果应用 api.requestedAccessTokenVersion 的属性设置为 2，则为 true。
• 应用使用 SAML 协议进行单一登录（SSO）。 如果此应用的服务主体的属性设置为 preferredSingleSignOnMode，则条件为真。
• 管理员已向要向其添加 URI 的应用或执行添加作的用户或服务授予 豁免 。

启用此保护后，如果组织中的任何人尝试向 v1 应用程序添加自定义标识符 URI，他们将收到如下错误：

The newly added URI {uri} must comply with the format 'api://{appId}' or 'api://{tenantId}/{appId}' as per the default app management policy of your organization. If the requestedAccessTokenVersion is set to 2, this restriction may not apply. See https://aka.ms/identifier-uri-addition-error for more information on this error.

此更加严格的策略有助于保护贵组织免受声明中的 audience 常见令牌验证错误的影响。 我们建议尽可能启用它，但Microsoft不会代表你启用它。

若要在组织中启用此限制性更高的策略，可以运行 此脚本。

与其他策略一样，管理员还可以授予此策略 的豁免 ，或在启用后 禁用该 策略。

FAQ

什么是标识符 URI？

标识符 URI（也称为“应用 ID URI”）允许资源（API）开发人员为其应用程序指定字符串值作为标识符。 获取 API 令牌的客户端可以在 OAuth 请求期间使用此字符串值。 例如，如果 API 配置了标识符 URI 为 https://api.contoso.com，则 API 的客户端可以在 OAuth 请求中指定该值给 Microsoft Entra。 此标识符 URI 用作 v1.0 访问令牌中的受众声明。

标识符 URI 是使用 应用注册中的“公开 API”页配置的。 在应用注册中，标识符 URI 称为应用程序 ID URI;这是标识符 URI 的同义词。

这些策略的工作原理是什么？

通过配置组织的 应用管理策略来启用强制实施。 租户管理员可以将其打开或关闭。 Microsoft将在 2025 年 6 月和 7 月期间，默认情况下在某些组织中启用它。

了解如何检查组织中是否已启用保护

即使默认情况下Microsoft启用此设置，租户管理员仍会保留对此设置的控制。 他们可以将其打开、关闭或授予例外。