为何更新为 Microsoft 标识平台 (v2.0)？

开发新应用程序时，必须知道 Microsoft 标识平台 (v2.0) 终结点与 Azure Active Directory (v1.0) 终结点之间的差异。 本文介绍这些终结点之间的主要差异，以及 Microsoft 标识平台的一些现有限制。

谁可以登录

• v1.0 终结点仅允许使用工作和学校帐户登录到应用程序 (Azure AD)
• Microsoft 标识平台终结点允许使用 Microsoft Entra ID 中的工作和学校帐户以及 Microsoft 个人帐户 (MSA)（例如 hotmail.com、outlook.com 和 msn.com）登录。
• 这两个终结点还接受 Microsoft Entra 目录的来宾用户登录，这些用户所属的应用程序配置为单租户或多租户应用程序，并指向特定租户的终结点。

Microsoft 标识平台终结点允许编写接受 Microsoft 个人帐户以及工作和学校帐户登录的应用。 这样，你便可以编写完全不区分帐户的应用。 例如，如果你的应用调用 Microsoft Graph，那么工作帐户将可以获得一些附加功能和数据，例如他们的 SharePoint 网站或目录数据。 但是，对于许多动作（如 读取用户邮件），相同的代码可以同时访问个人帐户、工作帐户和学校帐户的电子邮件。

对于 Microsoft 标识平台终结点，可以使用 Microsoft 身份验证库 (MSAL) 来获取对使用者、教育和企业领域的访问权限。 Azure AD v1.0 终结点仅接受工作和学校帐户的登录。

增量同意和动态同意

使用 Azure AD v1.0 终结点的应用需要提前指定所需的 OAuth 2.0 权限，例如：

直接在应用程序注册上设置的权限是 静态的。 尽管在 Azure 门户中定义应用的静态权限能保持代码的简洁性，但可能会给开发人员带来几个问题：

• 应用需要在用户首次登录时请求所有可能需要的权限。 这可能会导致冗长的权限列表，而让最终用户在初始登录时打消审批应用程序访问权限的念头。

• 应用需要事先知道可能访问的所有资源。 很难创建能够访问任意数目的资源的应用程序。

使用 Microsoft 标识平台终结点，可以忽略在 Azure 门户的应用注册信息中定义的静态权限，而以递增方式请求权限，即，一开始请求最少的一组权限，然后随着时间的推移，当客户使用更多的应用功能时，再请求更多的权限。 为此，可以在请求访问令牌时，通过在 scope 参数中包含新的范围指定应用所需的范围 - 无需在应用程序注册信息中预定义这些范围。 如果用户尚未许可添加到请求的新范围，则系统会提示他们仅许可新的权限。 若要了解详细信息，请参阅 权限、同意和范围。

允许应用通过 scope 参数动态请求权限可让开发人员完全控制用户的体验。 还可以将许可体验提前，并在一个初始授权请求中请求所有的权限。 如果应用需要大量的权限，则你可以在用户尝试使用应用的某些功能过程中，以递增方式向用户收集这些权限。

代表组织执行的管理员许可仍然需要为应用注册的静态权限，因此，如果需要管理员代表整个组织提供许可，则应在应用注册门户中为应用设置这些权限。 这会减少组织管理员设置应用程序所需的周期数。

范围而非资源

对于使用 v1.0 终结点的应用，应用可以充当 资源或令牌接收者。 资源可以定义它理解的多个 范围 或 oAuth2Permissions ，允许客户端应用从该资源请求特定范围集的令牌。 请考虑将 Microsoft Graph API 作为资源的示例：

• 资源标识符，或 AppID URI：https://graph.microsoft.com/
• 范围，例如 oAuth2Permissions：Directory.Read、Directory.Write 等等。

对于 Microsoft 标识平台终结点也是如此。 应用仍可充当资源、定义范围并由 URI 标识。 客户端应用程序仍可请求访问这些范围。 但是，客户端用于请求这些权限的方式已发生了变化。

对于 v1.0 终结点，Azure AD 的 OAuth 2.0 授权请求可能如下所示：

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

此处， 资源 参数指示客户端应用请求授权的资源。 Azure AD 根据 Azure 门户中的静态设置计算应用程序所需的权限，并据以发出令牌。

对于使用 Microsoft 标识平台终结点的应用程序，相同的 OAuth 2.0 授权请求如下所示：

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

此处， scope 参数指示应用请求授权的资源和权限。 所需的资源仍然在请求中提供 - 它包含在 scope 参数的每个值中。 以此方式使用 scope 参数可让 Microsoft 标识平台终结点更符合 OAuth 2.0 规范，并且更贴近常见的行业实践。 它还使应用能够进行 增量同意 - 仅当应用程序需要权限时请求权限，而不是提前请求权限。

已知的范围

脱机访问

使用 Microsoft 标识平台终结点的应用可能需要针对应用使用新的已知权限 - offline_access 范围。 所有应用程序如果需在较长时间内代表用户访问资源，即使用户可能并未主动使用该应用程序，也必须请求此权限。 在许可对话框中，offline_access 范围对用户显示为“随时访问数据”，而用户必须同意。 请求 offline_access 权限可让 Web 应用从 Microsoft 标识平台终结点接收 OAuth 2.0 refresh_tokens。 刷新令牌属于长效令牌，可用于交换新的 OAuth 2.0 访问令牌以延长访问期限。

如果应用未请求 offline_access 范围，则收不到刷新令牌。 这意味着，在 OAuth 2.0 授权代码流中兑换授权代码时，只从 /token 终结点接收访问令牌。 该访问令牌短时间维持有效（通常是一小时），但最后终将过期。 到时，应用必须将用户重定向回到 /authorize 终结点以检索新的授权代码。 在此重定向期间，根据应用程序的类型，用户或许无需再次输入其凭据或重新同意权限。

若要了解有关 OAuth 2.0、refresh_tokens 和 access_tokens 的详细信息，请查看 Microsoft 标识平台协议参考。

OpenID、profile 和 email

从历史上看，使用 Microsoft 标识平台的最基本的 OpenID Connect 登录流程，会在生成的 id_token 中提供大量关于用户的信息。 id_token 中的声明可以包含用户的名称、首选用户名、电子邮件地址和对象 ID 等。

现在对 openid 范围允许应用访问的信息进行了限制。 openid 范围只允许应用让用户登录，并为用户接收一个应用特定的标识符。 如果想要在应用中获取关于用户的个人数据，则应用需要向用户请求额外的权限。 两个新范围 email 和 profile 将允许请求额外的权限。

• 假设用户具有可寻址的电子邮件地址，则 email 范围允许应用通过 id_token 中的 email 声明访问用户的主要电子邮件地址。
• profile 范围可让应用访问 id_token 中有关用户的所有其他基本信息，例如其姓名、首选用户名、对象 ID 等。

使用这些范围可在尽可以能透露最少信息的情况下为应用编写代码，因此，只能向用户请求应用执行其作业所需的信息集。 有关这些范围的详细信息，请参阅 Microsoft标识平台范围参考。

令牌声明

为了保持负载较小，Microsoft 身份平台终结点默认会在其令牌中发布较少的声明。 如果您的应用和服务依赖于 v1.0 令牌中的某个特定声明，而该声明在 Microsoft 标识平台令牌中默认不再提供，请考虑使用 可选声明 功能来包含该声明。

局限性

使用 Microsoft 标识平台时需要注意的一些限制。

生成与 Microsoft 标识平台集成的应用程序时，需确定 Microsoft 标识平台终结点和身份验证协议是否满足需求。 v1.0 终结点和平台仍完全受支持，并且在某些方面比 Microsoft 标识平台的功能更丰富。 但是，Microsoft标识平台 为开发人员带来了显著优势 。

下面是目前为开发人员提供的简明建议：

• 如果想要或者需要在应用程序中支持 Microsoft 个人帐户，或者要编写新应用程序，请使用 Microsoft 标识平台。 但在此之前，请确保了解本文所述的限制。
• 若要迁移或更新依赖于 SAML 的应用程序，则不能使用 Microsoft 标识平台。 请改为参阅 Azure AD v1.0 指南。

Microsoft 标识平台终结点将演变为消除此处列出的限制，因此你只需要使用 Microsoft 标识平台终结点。 与此同时，使用本文来确定 Microsoft 标识平台终结点是否适合你。 我们将持续更新本文，以反映 Microsoft 标识平台终结点当前的状态。 请不时返回重新评估您的需求与 Microsoft 标识平台的能力是否匹配。

应用注册限制

对于要与Microsoft标识平台终结点集成的每个应用，可以在 Azure 门户中的新应用注册体验中创建应用注册。 现有的 Microsoft 帐户应用与门户不兼容，但所有 Microsoft Entra 应用都兼容，无论它们是在何处或何时注册的。

支持工作和学校帐户以及个人帐户的应用注册的注意事项如下：

• 每个应用程序 ID 只允许有两个应用密码。
• 未在租户中注册的应用程序只能由注册它的帐户管理。 不能与其他开发人员共享该应用程序。 在应用注册门户中使用 Microsoft 个人帐户注册的大多数应用都是如此。 如果要与多名开发人员共享应用注册，请使用 Azure 门户的新“应用注册”部分在租户中注册该应用程序 。
• 允许的重定向 URL 格式存在一些限制。 有关重定向 URL 的详细信息，请参阅下一部分。

重定向 URL 的限制

有关注册到Microsoft标识平台的应用重定向 URL 限制的 up-to日期信息，请参阅Microsoft标识平台文档中的 重定向 URI/回复 URL 限制和限制 。

若要了解如何注册应用以用于Microsoft标识平台，请参阅 使用新的应用注册体验注册应用。

库和 SDK 限制

目前，Microsoft 标识平台终结点的库支持有限。 如果想要在生产应用程序中使用 Microsoft 标识平台终结点，可使用以下选项：

• 如果要生成 Web 应用程序，可以放心使用正式版服务器端中间件来执行登录和令牌验证操作。 其中包括适用于 ASP.NET 的 OWIN OpenID Connect 中间件和 Node.js Passport 插件。 有关使用Microsoft中间件的代码示例，请参阅 Microsoft标识平台入门 部分。
• 如果要生成桌面或移动应用程序，可以使用 Microsoft 身份验证库 (MSAL) 之一。 这些库是正式发布版或支持在生产环境中使用的预览版，因此可在生产应用程序中放心使用。 可以在 身份验证库参考中详细了解预览版条款和可用库。
• 对于 Microsoft 库不支持的平台，可以通过直接在应用程序代码中发送和接收协议消息来与 Microsoft 标识平台终结点进行集成。 OpenID Connect 和 OAuth 协议有详细的文档说明，以帮助你进行此类集成。
• 最后，可以使用开源 OpenID Connect 和 OAuth 库来与 Microsoft 标识平台终结点集成。 Microsoft 标识平台终结点应与许多开源协议库兼容，不需要进行更改。 此类库的可用性根据语言和平台而有所不同。 OpenID Connect 和 OAuth 2.0 网站维护常用实现的列表。 有关详细信息，请参阅 Microsoft标识平台和身份验证库，以及已使用Microsoft标识平台终结点测试的开源客户端库和示例列表。
• （供参考）Microsoft 标识平台的通用 .well-known 终结点是 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration。 将 common 替换为你的租户 ID，以获取特定于你的租户的数据。

协议更改

Microsoft 标识平台终结点不支持 SAML 或 WS 联合身份验证；它仅支持 OpenID Connect 和 OAuth 2.0。 相比 v1.0 终结点，OAuth 2.0 协议的重大变化包括：

• 如果配置了可选声明，或者在请求中指定了 scope=email，则返回 email 声明。
• 现在支持使用 scope 参数来取代 resource 参数。
• 许多响应已经过修改，因此更符合 OAuth 2.0 规范，例如，可正确返回整数而不是字符串形式的 expires_in。

若要更好地了解Microsoft标识平台终结点中支持的协议功能范围，请参阅 OpenID Connect 和 OAuth 2.0 协议参考。

SAML 使用情况

如果已在 Windows 应用程序中使用了 Active Directory 身份验证库 (ADAL)，则可能已利用了 Windows 集成身份验证，该身份验证使用安全断言标记语言 (SAML) 断言授予。 通过此授予，联合 Microsoft Entra 租户的用户可以使用其本地 Active Directory 实例以无提示方式进行身份验证，而无需输入凭据。 虽然 SAML 仍然是企业用户使用的受支持协议 ，但 v2.0 终结点仅用于 OAuth 2.0 应用程序。

后续步骤

在 Microsoft标识平台文档中了解详细信息。