通过

身份验证的新增功能

  • 项目

Microsoft 定期添加和修改 Microsoft 标识平台的特性和功能，以提高其安全性、可用性和标准符合性。

除非另有说明，否则此处所述更改仅适用于在所述更改生效日期之后注册的应用程序。

请定期查看本文以了解以下内容：

  • 已知问题和修补程序
  • 协议更改
  • 已弃用的功能

提示

通过将此 URL 添加到 RSS 源阅读器中即可在此页面更新时获得通知：
https://learn.microsoft.com/api/search/rss?search=%22Azure+Active+Directory+breaking+changes+reference%22&locale=en-us

2024 年 8 月

联合标识凭据现在使用区分大小写的匹配

生效日期：2024 年 9 月

受影响的协议：工作负荷联合身份验证

更改

以前，当将联合标识凭据 (FIC) issuer、subject 和 audience 值与外部 IdP 发送给Microsoft Entra ID的令牌中包含的相应 issuer、subject 和 audience 值进行匹配时，使用不区分大小写的匹配。 为了向客户提供更精细的控制，我们将切换到强制实施区分大小写的匹配。

无效示例：

  • 令牌使用者：repo:contoso/contoso-org:ref:refs/heads/main
  • FIC 使用者：repo:Contoso/Contoso-Org:ref:refs/heads/main

这两个使用者值不区分大小写匹配，因此验证失败。 相同的机制也适用于 issuer 和 audience 验证。

此更改最初将应用于在 August 14th, 2024 之后创建的应用程序或托管标识。 从 September 27th, 2024 开始，需要使用区分大小写的匹配，这取决于在 August 1st, 2024 到 August 31st, 2024 期间，所述应用程序或托管标识没有发出任何工作负荷联合身份验证。 对于活动应用程序，不区分大小写的匹配将在稍后进行通信。

为了更好地突出由于不区分大小写而导致的失败，我们正在修改 AADSTS700213 的错误消息。 它现在将处于状态；

`AADSTS700213: No matching federated identity record found for presented assertion subject '{subject}'. Please note that matching is done using a case-sensitive comparison. Check your federated identity credential Subject, Audience, and Issuer against the presented assertion.`

占位符 '{subject}' 提供从外部 IdP 发送到 Microsoft Entra ID 的令牌中包含的使用者声明的值。 此错误模板也用于围绕 issuer 和 audience 验证的不区分大小写的失败。 如果遇到此错误，你应该找到与错误中列出的 issuer、subject 或 audience 对应的联合标识凭据，并从区分大小写的角度确认相应的值是等效的。 如果不匹配，则需要将 FIC 中的当前 issuer、subject 或 audience 值替换为错误消息中包含的 issuer、subject 或 audience 值。

注意

对于使用 GitHub Actions 并遇到此错误的 Azure 应用服务客户，解决此问题的选项是转到 GitHub 存储库中 /.github/workflows 下的工作流文件，并将环境 name 属性从 "Production" 更新为 "production"。 本指导仅适用于Azure 应用服务应用场景。 如果在其他应用场景中遇到此错误，请参阅上述指导。

2023 年 10 月

更新了 RemoteConnect UX 提示

生效日期：2023 年 10 月

影响的终结点：v2.0 和 v1.0

受影响的协议：RemoteConnect

RemoteConnect 是一种跨设备流，用于涉及主刷新令牌的 Microsoft 身份验证代理和 Microsoft Intune 相关方案。 为了帮助防止网络钓鱼攻击，RemoteConnect 流将接收更新的 UX 语言，以表明远程设备（启动流的设备）在成功完成流后将能够访问你的组织使用的任何应用程序。

出现的提示如下所示：

更新后的 Remote Connect 提示屏幕截图，内容为“你将在远程设备或服务上登录，允许你访问你的组织使用的任何应用”。

2023 年 6 月

省略域名所有者未经验证的电子邮件声明

生效日期：2023 年 6 月

影响的终结点：v2.0 和 v1.0

更改

对于多租户应用程序，在令牌有效负载中请求可选的 email 声明时，默认情况下会忽略未通过域所有者验证的电子邮件。

在以下情况下，电子邮件被视为经过域所有者验证：

  1. 域属于用户帐户所在的租户，并且租户管理员已对域进行验证。
  2. 电子邮件来自 Microsoft 帐户 (MSA)。

还应注意，SAML/WS-Fed 帐户没有已验证的域。

2023 年 5 月

Power BI 管理员角色将更名为 Fabric 管理员。

生效日期：2023 年 6 月

受影响的终结点：

  • List roleDefinitions - Microsoft Graph v1.0
  • List directoryRoles - Microsoft Graph v1.0

更改

Power BI 管理员角色已重命名为 Fabric 管理员。

2023 年 5 月 23 日，Microsoft 推出了 Microsoft Fabric。这款以数据湖为中心的 SaaS 解决方案能够一站式提供依托 Azure 数据工厂提供支持的数据集成体验、依托 Synapse 提供支持的数据工程、数据仓库、数据科学，以及 Power BI 的实时分析体验和商业智能 (BI)。 这些体验的租户和容量管理全部集中在 Fabric 管理门户（以前称为 Power BI 管理门户）。

从 2023 年 6 月开始，Power BI 管理员角色将重命名为 Fabric 管理员，以适应该角色不断变化的范围和职责。 未来几周，包括 Microsoft Entra ID、Microsoft Graph API、Microsoft 365 和 GDAP 在内的所有应用程序都会陆续启用更名后的新角色。

温馨提示：你的应用程序代码和脚本不应根据角色名称或显示名称做出决策。

2021 年 12 月

将会让 AD FS 用户看到更多登录提示，以确保登录了正确的用户。

生效日期：2021 年 12 月

受影响的终结点：集成 Windows 身份验证

受影响的协议：集成 Windows 身份验证

更改

目前，在将用户发送到 AD FS 进行身份验证时，用户将以无提示方式登录到已与 AD FS 建立了会话的任何帐户。 即使用户打算登录到另一用户帐户，也会发生无提示登录。 为了降低这种错误登录发生的频率，从 12 月开始，如果 Windows 中的 Web 帐户管理器在登录期间向 Microsoft Entra ID 提供 login_hint，指示需要一个特定的用户进行登录，Microsoft Entra ID 将向 AD FS 发送 prompt=login 参数。

当满足上述要求（WAM 用于将用户发送到 Microsoft Entra ID 进行登录，包含一个 login_hint，而用户的域的 AD FS 实例支持 prompt=login）时，用户将不会以无提示方式登录，而是会被要求提供用户名以继续登录 AD FS。 如果用户希望登录现有的 AD FS 会话，可以选择登录提示下方显示的“以当前用户身份继续”选项。 否则，他们可以继续使用他们打算用来登录的用户名。

此更改将于 2021 年 12 月的几周内推出。 它不会改变以下应用程序或域的登录行为：

  • 直接使用 IWA 的应用程序
  • 使用 OAuth 的应用程序
  • 未联合到 AD FS 实例的域

2021 年 10 月

错误 50105 已修复，在交互式身份验证期间不会返回 interaction_required

生效日期：2021 年 10 月

影响的终结点：v2.0 和 v1.0

影响的协议：需要用户分配的应用的所有用户流

更改

当未分配的用户尝试登录到管理员已标记为需要用户分配的应用时，发出错误 50105（当前指定）。 这是一种常见的访问控制模式，用户必须经常找到管理员来请求分配以取消阻止访问。 该错误有一个 bug，该 bug 会导致正确处理 interaction_required 错误响应的编码良好的应用程序中出现无限循环。 interaction_required 告知应用执行交互式身份验证，但即使这样做，Microsoft Entra ID 仍会返回 interaction_required 错误响应。

错误场景已更新，因此在非交互式身份验证期间（prompt=none 用于隐藏 UX），将指示应用使用 interaction_required 错误响应执行交互式身份验证。 在后续交互式身份验证中，Microsoft Entra ID 将保存用户并直接显示错误消息，从而阻止发生循环。

提醒一下，应用程序代码不应根据错误代码字符串（如 AADSTS50105）做出决策， 而应按照错误处理指南进行操作，并使用标准化身份验证响应，例如在响应的标准 error 字段中找到的 interaction_required 和 login_required。 其他响应字段仅供人用于排查其问题。

可以在错误查找服务中查看 50105 错误的当前文本以及更多内容：https://login.partner.microsoftonline.cn/error?code=50105。

单租户应用程序中的 AppID URI 需要使用默认方案或已验证的域

生效日期：2021 年 10 月

影响的终结点：v2.0 和 v1.0

受影响的协议：所有流

更改

对于单租户应用程序，添加或更新 AppId URI 会验证 HTTPS 方案 URI 中的域是否列在客户租户的已验证域列表中，或者该值是否使用 Microsoft Entra ID 提供的默认方案 (api://{appId})。 如果该域不在验证域列表中，或者该值未使用默认方案，这可能会阻止应用程序添加 AppID URI。 若要了解有关验证域的详细信息，请参阅自定义域文档。

此项更改不会影响在 AppID URI 中使用未验证域的现有应用程序。 它仅验证新应用程序，或在现有应用程序更新标识符 URI 或向 identifierUri 集合添加新标识符 URI 时进行验证。 新的限制仅适用于在 2021 年 10 月 15 日之后添加到应用的 identifierUris 集合的 URI。 此限制在 2021 年 10 月 15 日生效之后，即使向应用程序的 identifierUris 集合添加了新 URI，集合中现有的 AppID URI 也会继续工作。

如果请求未通过验证检查，则用于创建/更新的应用程序 API 将向客户端返回 400 badrequest，指示 HostNameNotOnVerifiedDomain。

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

支持的应用程序 ID
URI 格式		 示例应用 ID URI
api://<appId> api://00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<appId> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
api://<tenantId>/<string> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
api://<string>/<appId> api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
https://<tenantInitialDomain>.partner.onmschina.cn/<string> https://contoso.partner.onmschina.cn/productsapi
https://<verifiedCustomDomain>/<string> https://contoso.com/productsapi
https://<string>.<verifiedCustomDomain> https://product.contoso.com
https://<string>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
  • <appId> - 应用程序对象的应用程序标识符 (appId) 属性。
  • <string> - 主机或 API 路径段的字符串值。
  • <tenantId> - Azure 生成的用于表示 Azure 中的租户的 GUID。
  • <tenantInitialDomain> - <tenantInitialDomain>.partner.onmschina.cn，其中 <tenantInitialDomain> 是租户创建者在创建租户时指定的初始域名。
  • <verifiedCustomDomain> - 为 Microsoft Entra 租户配置的已验证的自定义域。

注意

如果使用 api:// 方案，则直接在“api://”之后添加一个字符串值。 例如，api://<string>。 该字符串值可以是 GUID 或任意字符串。 如果添加 GUID 值，值必须与应用 ID 或租户 ID 匹配。 应用程序 ID URI 值对于租户必须是唯一的。 如果将 api://<tenantId> 添加为应用程序 ID URI，其他人将无法在任何其他应用程序中使用该 URI。 建议改用 api://<appId> 或 HTTP 方案。

重要

应用程序 ID URI 值不能以斜杠“/”字符结尾。

注意

虽然可以安全地删除当前租户中应用注册的 identifierUris，但删除 identifierUris 可能会导致客户端在其他应用注册中失败。

2021 年 8 月

仅会为显式请求的范围触发条件访问

生效日期：2021 年 8 月，从 4 月开始逐步推出。

受影响的终结点：v2.0

受影响的协议：所有使用动态许可的流

现在，使用动态同意的应用程序将获得它们被同意的所有权限，即使未按名称在 scope 参数中请求这些权限。 例如，仅请求 user.read 但被同意 files.read 的应用可能会被强制要求通过为 files.read 分配的条件访问要求。

为了减少不必要的条件访问提示次数，Microsoft Entra ID 将更改向应用程序提供范围的方式，仅显式请求的范围会触发条件访问。 依赖于 Microsoft Entra ID 以前的行为（将所有范围都包括在令牌中，不管是否进行了请求）的应用程序可能会因缺少范围而发生中断。

现在，应用将收到包含混合权限的访问令牌：所请求令牌的权限，以及已获得同意且不需要条件访问提示的权限。 令牌的访问范围反映在令牌响应的 scope 参数中。

此更改将对所有应用进行，但被观察到对此行为具有依赖项的应用除外。 如果开发人员由于可能依赖于其他条件访问提示而被排除在此更改计划外，将与他们取得联系。

示例

应用已获得 user.read、files.readwrite 和 tasks.read 许可。 files.readwrite 应用了条件访问策略，而另两个未应用。 如果应用发出 scope=user.read 的令牌请求，且当前登录用户尚未通过任何条件访问策略，则生成的令牌将用于 user.read 和 tasks.read 权限。 将包括 tasks.read，因为应用已获得有关它的许可，且它不要求强制实施条件访问策略。

如果应用随后请求 scope=files.readwrite，则将触发租户所需的条件访问，并强制应用显示可满足条件访问策略的交互式身份验证提示。 返回的令牌将包含全部三个范围。

如果应用最后一次请求三个范围中的任何一个范围（例如 scope=tasks.read），Microsoft Entra ID 会发现用户已完成 files.readwrite 所需的条件访问策略，因此会再次颁发包含所有三个权限的令牌。

2021 年 6 月

设备代码流 UX 现在将包括应用确认提示

生效日期：2021 年 6 月。

影响的终结点：v2.0 和 v1.0

影响的协议：设备代码流

为了防止网络钓鱼攻击，设备代码流现在包含一个提示，用于验证用户是否登录到其所期望的应用。

出现的提示如下所示：

新提示，内容为“你是在尝试登录到 Azure CLI 吗？”

2020 年 5 月

Bug 修复：Microsoft Entra ID 将不再对状态参数进行两次 URL 编码

生效日期：2021 年 5 月

受影响的终结点：v1.0 和 v2.0

受影响的协议：所有访问 /authorize 终结点的流（隐式流和授权代码流）

在 Microsoft Entra 授权响应中发现并修复了 bug。 在身份验证的 /authorize 阶段，请求中的 state 参数包含在响应中，以便保持应用状态并防止 CSRF 攻击。 在将 state 参数插入到响应中之前，Microsoft Entra ID 错误地对参数进行了 URL 编码，在响应中又进行了一次编码。 这会导致应用程序错误地拒绝 Microsoft Entra ID 的响应。

Microsoft Entra ID 将不再对此参数进行双重编码，从而允许应用正确分析结果。 将对所有应用程序进行此更改。

2020 年 3 月

用户密码将限制为 256 个字符。

生效日期：2020 年 3 月 13 日

受影响的终结点：全部

受影响的协议：所有用户流。

系统会要求使用的密码超过 256 个字符的直接登录到 Microsoft Entra ID（不是联合 IDP，例如 AD FS）的用户在登录之前更改其密码。 管理员可能会收到要求帮助重置用户密码的请求。

登录日志中的错误将类似于“AADSTS 50052: InvalidPasswordExceedsMaxLength”。

消息：The password entered exceeds the maximum length of 256. Please reach out to your admin to reset the password.

补救措施：

用户无法登录，因为其密码超过了允许的最大长度。 他们应该联系管理员以重置密码。 如果已为其租户启用了 SSPR，则他们可以通过打开“忘记密码”链接来重置其密码。

2020 年 2 月

会将空片段追加到来自登录终结点的每个 HTTP 重定向。

生效日期：2020 年 2 月 8 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：使用 response_type=query 的 OAuth 和 OIDC 流 - 涵盖授权代码流（在某些情况下）和隐式流。

通过 HTTP 重定向将身份验证响应从 login.partner.microsoftonline.cn 发送到应用程序时，该服务会将一个空片段追加到回复 URL。 这可以确保浏览器擦除身份验证请求中的任何现有片段，防止出现重定向攻击类。 任何应用都不应依赖于此行为。

2019 年 8 月

POST 表单语义会更严格地实施 - 空格和引号会被忽略

生效日期：2019 年 9 月 2 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：使用 POST 的任何位置（客户端凭据、授权代码兑换、ROPC、OBO和刷新令牌兑换）

从 2019 年 9 月 2 日那一周开始，使用 POST 方法的身份验证请求会按更严格的 HTTP 标准进行验证。 具体来说，将不再从请求窗体值中删除空格和双引号 (")。 这些更改不应造成任何现有客户端出现中断，将确保发送到 Microsoft Entra ID 的请求每次都能够得到可靠的处理。 在将来（见上），我们计划还要拒绝重复参数并忽略请求中的 BOM。

示例：

目前，?e= "f"&g=h 的分析与 ?e=f&g=h 相同，因此 e == f。 进行此更改后，它现在可以进行分析，使得 e == "f" - 这不可能成为一个有效的参数，请求会失败。

2019 年 7 月

仅当客户端应用在资源租户中存在时，才为单租户应用程序颁发仅限应用的令牌

生效日期：2019 年 7 月 26 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：客户端凭据（仅限应用的令牌）

一项安全更改已在 2019 年 7 月 26 日生效，它会更改颁发仅限应用的令牌的方式（通过客户端凭据授予）。 以前，允许应用程序获取令牌来调用任何其他应用，无论该应用程序是否在租户中存在或者是否向其许可了角色。 此行为现已更新，对于设置为单租户（默认值）的资源（有时称为 Web API），客户端应用程序必须在资源租户中存在。 仍不需要客户端与 API 之间的现有同意，应用应该仍会执行其自身的授权检查，以确保 roles 声明存在并且包含 API 所需的值。

此方案的错误消息目前会指出：

The service principal named <appName> was not found in the tenant named <tenant_name>. This can happen if the application has not been installed by the administrator of the tenant.

若要解决此问题，请使用管理员许可体验在租户中创建客户端应用程序服务主体，或手动创建该服务主体。 此项要求可确保租户授予应用程序在租户中操作的权限。

示例请求

https://login.partner.microsoftonline.cn/contoso.com/oauth2/authorize?resource=https://gateway.contoso.com/api&response_type=token&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&... 在此示例中，资源租户（颁发机构）是 contoso.com，资源应用是 Contoso 租户的某个单租户应用（名为 gateway.contoso.com/api），客户端应用是 00001111-aaaa-2222-bbbb-3333cccc4444。 如果客户端应用在 Contoso.com 中有服务主体，则此请求可以继续。 不过，如果没有服务主体，则请求将会失败并出现上面所示的错误。

但是，如果 Contoso 网关应用是多租户应用程序，则无论客户端应用是否在 Contoso.com 中有服务主体，请求都会继续。

重定向 URI 现在可以包含查询字符串参数

生效日期：2019 年 7 月 22 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：所有流

根据 RFC 6749，Microsoft Entra 应用程序现在可以为 OAuth 2.0 请求注册和使用带有静态查询参数（例如 https://contoso.com/oauth2?idp=microsoft）的重定向（回复）URI。 动态重定向 URI 仍旧受禁用，因为它们表示存在安全风险，不可将其用于保留身份验证请求的状态信息 - 为此，请使用 state 参数。

与重定向 URI 的任何其他部分一样，静态查询参数需要接受重定向 URI 的字符串匹配 - 如果未注册与 URI 解码的 redirect_uri 匹配的字符串，则会拒绝请求。 如果在应用注册中找到了 URI，则会使用整个字符串（包括静态查询参数）来重定向用户。

目前（2019 年 7 月底），Azure 门户中的应用注册 UX 仍会阻止查询参数。 不过，你可以手动编辑应用程序清单，以添加查询参数并在应用中对其进行测试。

2019 年 3 月

循环客户端将会中断

生效日期：2019 年 3 月 25 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：所有流

客户端应用程序有时可能会出现行为异常，在短时间内发出数百个相同的登录请求。 这些请求不一定会成功，但会导致用户体验变得糟糕，增大 IDP 的工作负荷，增大所有用户的延迟，并降低 IDP 的可用性。 这些应用程序的工作范围超过了正常的使用边界，应予以更新才能让其保持正常的行为。

将为多次发出重复请求的客户端设置 invalid_grant 错误：AADSTS50196: The server terminated an operation because it encountered a loop while processing a request。

大多数客户端无需改变行为即可避免此错误。 此错误只会影响配置不当的客户端（没有令牌缓存的客户端，或已经出现提示循环的客户端）。 根据以下因素，在本地按实例跟踪客户端（通过 Cookie）：

  • 用户提示（如果有）

  • 请求的范围或资源

  • 客户端 ID

  • 重定向 URI

  • 响应类型和模式

在短时间（5 分钟）内发出多个请求（15 个以上）的应用将会收到 invalid_grant 错误，指出它们正在循环。 所请求的令牌具有足够长的生存期（最短 10 分钟，默认为 60 分钟），因此，在此时间段内发出的重复请求都是没有必要的。

所有应用应该通过显示交互式提示来处理 invalid_grant，而不是以静默方式请求令牌。 若要避免此错误，客户端应确保正确缓存它们收到的令牌。

2018 年 10 月

授权代码无法再重复使用

生效日期：2018 年 11 月 15 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：代码流

从 2018 年 11 月 15 日起，Microsoft Entra ID 不再允许对应用使用以前用过的身份验证代码。 此项安全变更有助于使 Microsoft Entra ID 与 OAuth 规范保持一致，将在 v1 和 v2 终结点上强制实施。

如果应用重复使用授权代码来获取多个资源的令牌，则我们建议使用该代码获取刷新令牌，然后使用该刷新令牌获取其他资源的其他令牌。 授权代码只能使用一次，但刷新令牌可对多个资源使用多次。 尝试在 OAuth 代码流期间重用身份验证代码的任何新应用都将收到 invalid_grant 错误。

有关刷新令牌的详细信息，请参阅刷新访问令牌。 如果使用 ADAL 或 MSAL，则由库为你处理 - 将 AcquireTokenByAuthorizationCodeAsync 的第二个实例替换为 AcquireTokenSilentAsync。

2018 年 5 月

ID 令牌不能用于 OBO 流

日期：2018 年 5 月 1 日

受影响的终结点：v1.0 和 v2.0

受影响的协议：隐式流和代理流

在 2018 年 5 月 1 日之后，id_token 不能用作新应用程序的 OBO 流中的断言。 应改为使用访问令牌来保护 API，即使在同一应用程序的客户端和中间层之间也是如此。 在 2018 年 5 月 1 日之前注册的应用将继续有效，并能够使用 id_tokens 交换访问令牌；但是，此模式并不是最佳做法。

要解决此更改，可以执行以下操作：

  1. 使用一个或多个作用域为应用程序创建 Web API。 此显式入口点可实现更精细的控制和安全性。
  2. 在你的应用的清单中，在 Azure 门户中，确保允许应用通过隐式流发出访问令牌。 这通过 oauth2AllowImplicitFlow 密钥进行控制。
  3. 客户端应用程序通过 response_type=id_token 请求 id_token 时，还会请求上面创建的 Web API 的访问令牌 (response_type=token)。 因此，使用 v2.0 终结点时，scope 参数应与 api://GUID/SCOPE 类似。 在 v1.0 终结点上，resource 参数应为 Web API 应用 URI。
  4. 将此访问令牌传递到中间层，代替 id_token。