配置 Microsoft Entra 身份验证 - Azure App Service

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

项目
05/29/2024

注意

从 2024 年 6 月 1 日开始，所有新创建的应用服务应用都可以选择生成唯一的默认主机名，命名约定为 <app-name>-<random-hash>.<region>.azurewebsites.net。现有应用名称将保持不变。

示例： myapp-ds27dh7271aah175.westus-01.azurewebsites.net

有关更多详细信息，请参阅应用服务资源的唯一默认主机名。

选择另一个身份验证提供商以跳转到它。

本文介绍如何为 Azure 应用服务或 Azure Functions 配置身份验证，使应用使用 Microsoft 标识平台 (Microsoft Entra) 作为身份验证提供程序让用户登录。

为应用程序及其用户选择租户

在应用程序可以让用户登录之前，首先需要在员工租户或外部租户中注册应用。如果使应用可供员工或业务来宾使用，请在员工租户中注册应用。如果应用供消费者和企业客户使用，请在外部租户中注册应用。

登录 Azure 门户并导航到你的应用程序。
在应用程序的左侧菜单中，选择“身份验证”，然后选择“添加标识提供者”。
在“添加标识提供者”页上，选择“Microsoft”作为“标识提供者”以登录 Microsoft 和 Microsoft Entra 标识。
对于“租户类型”，请为员工和业务来宾选择“员工配置（当前租户）”，或为消费者和企业客户选择“外部配置”。

选择应用注册

应用服务身份验证功能可以自动为你创建应用注册，也可以使用你或目录管理员单独创建的注册。

自动创建新的应用注册，除非需要单独创建应用注册。如果需要，可以稍后在 Microsoft Entra 管理中心中自定义应用注册。

以下情况是使用现有应用注册的最常见情况：

你的帐户无权在 Microsoft Entra 租户中创建应用注册。
你想要使用的应用注册来自其他 Microsoft Entra 租户，而不是应用所在的租户。
用于创建新注册的选项不适用于政府云。

工作人员配置
外部配置

创建和使用新的应用注册，或使用单独创建的现有注册。

选项 1：创建和使用新的应用注册

除非需要单独创建应用注册，否则请使用此选项。创建应用注册后，可以在 Microsoft Entra 中对它进行自定义。

注意

用于自动创建新注册的选项不适用于政府云。可以单独定义注册。

输入新应用注册的名称。

选择支持的帐户类型：

当前租户 - 单一租户。仅此组织目录中的帐户。您的目录中的所有用户和来宾帐户都可以使用您的应用程序或 API。目标受众是组织内部人员时使用本选项。
任何 Microsoft Entra 目录 - 多租户。任何组织目录中的帐户。拥有 Microsoft 工作或学校帐户的所有用户都可以使用应用程序或 API。这包括使用 Office 365 的学校和企业。如果目标受众是企业客户或教育客户，且要启用多租户，请使用此选项。
任何 Microsoft Entra 目录和个人 Microsoft 帐户。任何组织目录中的帐户和 Microsoft 个人帐户（例如 Skype、XBox）。拥有工作或学校帐户或者个人 Microsoft 帐户的所有用户都可以使用应用程序或 API。这包括使用 Office 365 的学校和企业以及用来登录 Xbox 和 Skype 等服务的个人帐户。此选项可用于定位范围最广的 Microsoft 标识集并启用多租户。
仅 Microsoft 个人帐户。用于登录 Xbox 和 Skype 等服务的个人帐户。使用此选项以定位范围最广的 Microsoft 标识集。

如果需要，你可以稍后更改注册名称或支持的帐户类型。

将客户端密码创建为名为 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的“槽粘滞”应用程序设置。如果你想要在 Azure Key Vault 中管理机密，稍后可以将该设置更新为使用 Key Vault 引用。

选项 2：使用单独创建的现有注册

二者之一：

选择“选择此目录中的现有应用注册”，然后从下拉列表中选择应用注册。
选择“提供现有应用注册的详细信息”并提供：
- 应用程序（客户端）ID。
- 客户端密码（推荐）。应用程序在请求令牌时用来证明其身份的密码值。此值作为名为 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的槽粘滞应用程序设置保存在应用的配置中。如果未设置客户端密码，则来自服务的登录操作会使用 OAuth 2.0 隐式授权流，我们不建议这样做。
- 证书颁发者 URL，采用 <authentication-endpoint>/<tenant-id>/v2.0 格式。将 <authentication-endpoint> 替换为特定于云环境的身份验证终结点值。例如，全球 Azure 中的劳动力租户将使用“https://sts.windows.net"”作为其身份验证终结点。

如果需要在员工租户中手动创建应用注册，请按照注册应用程序快速入门指南进行操作。完成注册过程时，请务必记下应用程序（客户端）ID 和客户端密码值。

在注册过程中，在“重定向 URI”部分中，为平台和类型 <app-url>/.auth/login/aad/callback 选择“Web”。例如 https://contoso.azurewebsites.net/.auth/login/aad/callback。

创建后，修改应用注册：

在左侧导航栏中，选择“公开 API”>“添加”>“保存”。此值在应用程序用作资源时唯一标识该应用程序，从而可以请求令牌以授予访问权限。它用作所创建作用域的前缀。

对于单租户应用，可以使用默认值，其格式为 api://<application-client-id>。还可以根据租户的一个已验证域指定更具可读性的 URI，例如 https://contoso.com/api。对于多租户应用，必须提供自定义 URI。要详细了解可接受的应用 ID URI 格式，请参阅应用注册最佳做法参考。
选择“添加范围”。
1. 在“范围名称”中输入 user_impersonation。
2. 如果要允许用户许可此范围的权限，请在“谁可以同意”中选择“管理员和用户”。
3. 在文本框中，输入许可范围名称，以及希望在许可页上向用户显示的说明。例如，输入“访问 <应用程序名>”。
4. 选择“添加作用域”。
（推荐）若要创建客户端密码，请：
1. 从左侧导航中，选择“证书和机密”>“客户端密码”>“新建客户端密码”。
2. 输入说明和过期时间，然后选择“添加”。
3. 在“值”字段中，复制客户端密码值。离开此页面后，它将不会再次显示。
（可选）若要添加多个回复 URL，请选择“身份验证”。

创建和使用新的应用注册，或使用单独创建的现有注册。

选项 1：创建和使用新的应用注册

除非需要单独创建应用注册，否则请使用此选项。创建应用注册后，可以在 Microsoft Entra 中对它进行自定义。

选择“新建应用注册”以创建新的应用注册。

从下拉菜单中选择要使用的现有租户，或者选择“新建”以创建新的外部租户。

创建新的外部租户（可选）

在“创建租户”页中，添加“租户名称”和“域名”。选择“位置”，选择“评审并创建”，然后选择“创建”。租户创建过程需要几分钟时间。

选择“配置”以配置新租户的外部身份验证。
浏览器将打开“配置客户身份验证”。
从下拉列表中选择用户流，或选择“新建”。用户流定义外部用户可以使用的登录方法。每个应用只能有一个用户流，但你可以为多个应用重复使用相同的用户流。

新建用户流

输入该用户流的名称。
为外部用户选择登录方法。新租户中已配置电子邮件和密码和电子邮件和一次性密码。还可以将 Google 或 Facebook 配置为标识提供者。
选择“创建”以创建用户流。

自定义品牌打造

选择“下一步”以自定义品牌打造。
添加徽标，选择背景色，然后选择登录布局。
选择“下一步”和“是，更新更改“以接受品牌打造更改。
在“查看”选项卡中选择“配置”，以确认外部租户更新。
浏览器再次打开“添加标识提供者”页。

选项 2：使用单独创建的现有注册

选择“提供现有应用注册的详细信息”并提供：- 应用程序（客户端）ID - 客户端密码 - 证书颁发者 URL

如果需要在外部租户中手动创建应用注册，请按照注册应用程序快速入门指南进行操作。

在注册过程中，在“重定向 URI”部分中，为平台和类型 <app-url>/.auth/login/aad/callback 选择“Web”。例如 https://contoso.azurewebsites.net/.auth/login/aad/callback。

创建后，修改应用注册：

在左侧导航栏中，选择“公开 API”>“添加”>“保存”。此值在应用程序用作资源时唯一标识该应用程序，从而可以请求令牌以授予访问权限。它用作所创建作用域的前缀。

对于单租户应用，可以使用默认值，其格式为 api://<application-client-id>。还可以根据租户的一个已验证域指定更具可读性的 URI，例如 https://contoso.com/api。对于多租户应用，必须提供自定义 URI。要详细了解可接受的应用 ID URI 格式，请参阅应用注册最佳做法参考。
选择“添加范围”。
1. 在“范围名称”中输入 user_impersonation。
2. 如果要允许用户许可此范围的权限，请在“谁可以同意”中选择“管理员和用户”。
3. 在文本框中，输入许可范围名称，以及希望在许可页上向用户显示的说明。例如，输入“访问 <应用程序名>”。
4. 选择“添加作用域”。
（可选）：要创建客户端密码：
1. 从左侧导航中，选择“证书和机密”>“客户端密码”>“新建客户端密码”。
2. 输入说明和过期时间，然后选择“添加”。
3. 在“值”字段中，复制客户端密码值。离开此页面后，它将不会再次显示。
（可选）若要添加多个回复 URL，请选择“身份验证”。

配置其他检查

配置其他检查，确定允许哪些请求访问应用程序。你现在可以自定义此行为，也可以稍后通过选择“身份验证”设置旁边的“编辑”，在主要“身份验证”屏幕上调整这些设置。

对于客户端应用程序要求，请选择是否：

仅允许来自此应用程序本身的请求
允许来自特定客户端应用程序的请求
允许来自任何应用程序的请求（不建议）

对于标识要求，请选择是否：

允许来自任何标识的请求
允许来自特定标识的请求

对于租户要求，请选择是否：

仅允许来自证书颁发者租户的请求
允许来自特定租户的请求
根据证书颁发者使用默认限制

你的应用可能需要在代码中做出额外的授权决策。有关详细信息，请参阅“使用内置授权策略”。

配置身份验证设置

这些选项可确定应用程序如何响应未经身份验证的请求，默认选择会将所有请求重定向到用此新提供程序登录。你现在可以更改自定义此行为，也可以稍后通过选择“身份验证”设置旁边的“编辑”，在主要“身份验证”屏幕上调整这些设置。若要详细了解这些选项，请参阅身份验证流。

对于 限制访问，请决定是否：

需要身份验证
允许未经身份验证的访问

对于未经身份验证的请求

HTTP 302 发现重定向：建议用于网站
HTTP 401 未授权：建议用于 API
HTTP 403 禁止访问
HTTP 404 找不到

选择“令牌存储”（建议）。令牌存储收集、存储和刷新应用程序的令牌。如果应用不需要令牌，或者需要优化性能，则可以稍后禁用此功能。

添加标识提供者

如果选择了员工配置，可以选择“下一步：权限”并添加应用程序所需的任何 Microsoft Graph 权限。这些作用域将被添加到应用注册中，但你也可以稍后更改它们。如果选择了外部配置，则可以稍后添加 Microsoft Graph 权限。

选择添加。

现在，你可以在应用中使用 Microsoft 标识平台进行身份验证了。该提供程序将在“身份验证”屏幕上列出。在该屏幕上，你可以编辑或删除此提供程序配置。

有关为访问 Azure 存储和 Microsoft Graph 的 Web 应用配置 Microsoft Entra 登录的示例，请参阅此教程。

授权请求

默认情况下，应用服务身份验证仅处理身份验证，确定调用方是否符合他们声称的身份。授权（确定调用方是否应有权访问某些资源）是身份验证之外的额外步骤。可以从 Microsoft 标识平台授权基础知识中了解有关这些概念的详细信息。

你的应用可以在代码中做出授权决策。应用服务身份验证确实提供了一些内置检查，这些检查可能有所帮助，但它们可能不足以满足应用的授权需求。

提示

多租户应用程序应在此过程中验证请求的颁发者和租户 ID，以确保这些值受允许。为多租户方案配置应用服务身份验证时，它不会验证请求来自哪个租户。例如，根据组织是否已注册该服务，应用可能需要限制为特定租户。请参阅 Microsoft 标识平台多租户指南。

从应用程序代码执行验证

在应用代码中执行授权检查时，可以使用应用服务身份验证提供的声明信息。注入的 x-ms-client-principal 标头包含 Base64 编码的 JSON 对象，其中包含有关调用方的断言的声明。默认情况下，这些声明会经过声明映射，因此声明名称可能并不总是与令牌中显示的名称匹配。例如，tid 声明会转而映射到 http://schemas.microsoft.com/identity/claims/tenantid。

还可以直接使用注入的 x-ms-token-aad-access-token 标头中的基础访问令牌。

使用内置授权策略

创建的应用注册会对你的 Microsoft Entra 租户的传入请求进行身份验证。默认情况下，它让租户中的任何人都可以访问应用程序，这对许多应用程序来说没有问题。但是，某些应用程序需要通过授权决策来进一步限制访问。应用程序代码通常是处理自定义授权逻辑的最佳位置。但是，对于常见方案，Microsoft 标识平台提供了内置检查，可用于限制访问。

本部分介绍如何使用应用服务身份验证 V2 API 启用内置检查。目前，配置这些内置检查的唯一方法是通过 Azure 资源管理器模板或 REST API。

在 API 对象中，Microsoft Entra 标识提供者配置具有一个 validation 部分，该部分可包含一个 defaultAuthorizationPolicy 对象，如以下结构所示：

{
    "validation": {
        "defaultAuthorizationPolicy": {
            "allowedApplications": [],
            "allowedPrincipals": {
                "identities": []
            }
        }
    }
}

properties	说明
`defaultAuthorizationPolicy`	访问应用必须满足的一组要求。访问权限基于对其每个已配置属性的逻辑 `AND` 授予。同时配置 `allowedApplications` 和 `allowedPrincipals` 时，传入请求必须同时满足这两个要求才能被接受。
`allowedApplications`	字符串应用程序客户端 ID 的允许列表，这些 ID 表示正在调用到应用的客户端资源。当此属性配置为非空数组时，只有通过列表中指定应用程序获得的令牌才会被接受。此策略评估传入令牌的 `appid` 或 `azp` 声明，该令牌必须是访问令牌。请参阅 Microsoft 标识平台声明参考。
`allowedPrincipals`	用于确定传入请求表示的主体是否可以访问应用的一组检查。 `allowedPrincipals` 的达成度基于对其已配置的属性的逻辑 `OR`。
`identities`（在 `allowedPrincipals` 下）	表示具有访问权限的用户或应用程序的字符串对象 ID 的允许列表。当此属性配置为非空数组时，如果列表中指定了由请求表示的用户或应用程序，则可以满足 `allowedPrincipals` 要求。标识列表有 500 个总字符的限制。此策略评估传入令牌的 `oid` 声明。请参阅 Microsoft 标识平台声明参考。

此外，无论使用的 API 版本如何，都可以通过应用程序设置配置某些检查。 WEBSITE_AUTH_AAD_ALLOWED_TENANTS 应用程序设置可配置最多 10 个租户 ID 的逗号分隔列表（例如“aaaabbbb-0000-cccc-1111-dddd2222eeee”），从而要求传入令牌来自 tid 声明指定的租户之一。可以将 WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL 应用程序设置配置为“true”或“1”，以要求传入令牌包含 oid 声明。如果 allowedPrincipals.identities 已配置，则此设置会被忽略并视为 true，因为已根据此提供的标识列表检查了 oid 声明。

这些内置检查失败的请求会得到 HTTP 403 Forbidden 响应。

配置客户端应用以访问应用服务

在上一部分中，你注册了应用服务或 Azure Function 以便对用户进行身份验证。本部分介绍如何在 Microsoft Entra 中注册本机客户端或守护程序应用，让它们能够代表用户或自行请求访问你的应用服务公开的 API，例如在 N 层体系结构中。如果你只想要对用户进行身份验证，则不需要完成本部分所述的步骤。

本机客户端应用程序

可以注册本机客户端，以代表已登录用户请求访问应用服务应用的 API。

在门户菜单中，选择“Microsoft Entra”。
在左侧导航栏中，选择“应用注册”>“新建注册”。
在“注册应用”页上的“名称”中，输入应用注册的名称。
在“重定向 URI”中，选择“公共客户端(移动和桌面)”，然后键入 URL“<app-url>/.auth/login/aad/callback”。例如 https://contoso.azurewebsites.net/.auth/login/aad/callback。
选择“注册”。
创建应用注册后，复制“应用程序(客户端) ID”的值。

注意

对于Microsoft Store 应用程序，请改用包 SID 作为 URI。
在左侧导航栏中，选择“API 权限”>“添加权限”>“我的 API”。
选择前面为应用服务应用创建的应用注册。如果没有看到应用注册，请确保已在应用注册中添加 user_impersonation 范围。
在“委托的权限”下，依次选择“user_impersonation”和“添加权限”。

现已配置一个可以代表用户请求访问应用服务应用的本机客户端应用程序。

守护程序客户端应用程序（服务到服务的调用）

在 n 层体系结构中，客户端应用程序可以获取令牌来代表客户端应用（并非代表用户）调用应用服务或函数应用。此方案适用于在没有登录用户的情况下执行任务的非交互式后台程序应用程序。它使用标准 OAuth 2.0 客户端凭据授权。

在门户菜单中，选择“Microsoft Entra”。
在左侧导航栏中，选择“应用注册”>“新建注册”。
在“注册应用”页上的“名称”中，输入应用注册的名称。
对于后台应用程序，不需要“重定向 URI”，因此可将其保留为空。
选择“注册”。
创建应用注册后，复制“应用程序(客户端) ID”的值。
从左侧导航中，选择“证书和机密”>“客户端密码”>“新建客户端密码”。
输入说明和过期时间，然后选择“添加”。
在“值”字段中，复制客户端密码值。离开此页面后，它将不会再次显示。

现在可以通过将 resource 参数设置为目标应用的“应用程序 ID URI”，使用客户端 ID 和客户端机密请求访问令牌。然后，可以使用标准 OAuth 2.0 授权标头将生成的访问令牌提供给目标应用，应用服务身份验证将像平常一样验证和使用该令牌，以指示调用方（在本例中是应用程序，不是用户）已进行身份验证。

目前，这允许 Microsoft Entra 租户中的任何客户端应用程序请求访问令牌，并向目标应用进行身份验证。如果还想要强制授权以只允许某些客户端应用程序，则必须执行一些额外配置。

在表示要保护的应用服务或 Functions 应用的应用注册清单中定义应用角色。
在表示需要获得授权的客户端的应用注册上，选择“API 权限”>“添加权限”>“我的 API”。
选择之前创建的应用注册。如果看不到应用注册，请确保已添加应用角色。
在“应用程序权限”下，选择之前创建的应用角色，然后选择“添加权限”。
确保选择“授予管理员同意”以授权客户端应用程序请求权限。
与前面的方案（添加任何角色之前）类似，现在可以为同一目标 resource请求访问令牌，而访问令牌将包括一个 roles 声明，其中包含授权给客户端应用程序的应用角色。
在目标应用服务或 Functions 应用代码中，现在可以验证令牌中是否存在预期的角色（这不是由应用服务身份验证执行的）。有关详细信息，请参阅访问用户声明。

现已配置可以使用自己的标识访问应用服务应用的后台程序客户端应用程序。

最佳做法

无论使用哪种配置来设置身份验证，以下最佳做法都能使租户和应用程序保持更高的安全性：

在 Microsoft Entra 中为每个应用服务应用配置各自的应用注册。
为每个应用服务应用提供其自身的权限和许可。
避免通过对不同的部署槽使用不同的应用注册，在环境之间共享权限。在测试新代码时，这种做法可有助于防止出现影响生产应用的问题。

迁移到 Microsoft Graph

某些较旧的应用可能还设置了对计划完全停用的已弃用的 Azure AD Graph 的依赖项。例如，应用代码可能已调用 Azure AD Graph，在中间件管道中的授权筛选器中检查组成员身份。应用应按照 Microsoft Entra 在 Azure AD Graph 弃用过程中提供的指南，迁移到 Microsoft Graph。按照以下说明操作，可能需要对应用服务身份验证的配置进行一些更改。将 Microsoft Graph 权限添加到应用注册后，可以：

更新证书颁发者 URL，以包含“/v2.0”后缀（如果尚未添加）。
从登录配置中删除 Azure AD Graph 权限请求。要更改的属性取决于正在使用的管理 API 版本：
- 如果使用 V1 API (/authsettings)，则要更改的属性在 additionalLoginParams 数组中。
- 如果使用 V2 API (/authsettingsV2)，则要更改的属性在 loginParameters 数组中。
例如，假设需要删除对“https://graph.windows.net"”的任何引用。其中包括 resource 参数（“/v2.0”终结点不支持）或从 Azure AD Graph 专门请求的任何范围。

还需要更新配置，以请求为应用程序注册设置的新 Microsoft Graph 权限。在许多情况下，可以使用 .default 范围来简化此设置。为此，需要添加新的登录参数 scope=openid profile email https://graph.microsoft.com/.default。

执行上述更改后，应用服务身份验证尝试登录时，将不再请求对 Azure AD Graph 的权限，而是获取 Microsoft Graph 的令牌。根据 Microsoft Entra 提供的指南，还需要更新应用程序代码中对该令牌的任何使用。

通过

为应用程序及其用户选择租户

选择应用注册

选项 1：创建和使用新的应用注册

选项 2：使用单独创建的现有注册

选项 1：创建和使用新的应用注册

创建新的外部租户（可选）

新建用户流

自定义品牌打造

选项 2：使用单独创建的现有注册

配置其他检查

配置身份验证设置

添加标识提供者

授权请求

从应用程序代码执行验证

使用内置授权策略

配置客户端应用以访问应用服务

本机客户端应用程序

守护程序客户端应用程序（服务到服务的调用）

最佳做法

迁移到 Microsoft Graph

后续步骤

反馈

其他资源

通过

将应用服务或 Azure Functions 应用配置为使用 Microsoft Entra 登录

为应用程序及其用户选择租户

选择应用注册

选项 1：创建和使用新的应用注册

选项 2：使用单独创建的现有注册

配置其他检查

配置身份验证设置

添加标识提供者

授权请求

从应用程序代码执行验证

使用内置授权策略

配置客户端应用以访问应用服务

本机客户端应用程序

守护程序客户端应用程序（服务到服务的调用）

最佳做法

迁移到 Microsoft Graph

后续步骤

反馈

其他资源