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

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

项目
10/21/2023

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

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

应用服务身份验证功能可以通过 Microsoft 标识平台自动创建应用注册。你还可以使用你或目录管理员单独创建的注册。

自动创建新的应用注册
使用单独创建的现有注册

注意

自动创建新注册的选项不适用于政府云，也无法与[面向客户的 Microsoft Entra ID（预览版）]一起使用。可以单独定义注册。

选项 1：自动创建新的应用注册

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

登录 Azure 门户并导航到你的应用程序。
在左侧菜单中选择“身份验证”。选择“添加标识提供者”。
在“标识提供者”下拉列表中选择“Microsoft”。默认会选中用于创建新注册的选项。你可以更改注册名称或支持的帐户类型。

将创建一个客户端密码，并将其存储为一个名为 MICROSOFT_PROVIDER_AUTHENTICATION_SECRET 的槽粘滞应用程序设置。如果你想要在 Azure Key Vault 中管理机密，稍后可以将该设置更新为使用 Key Vault 引用。
如果这是为应用程序配置的第一个标识提供程序，你还将看到“应用服务身份验证设置”部分的提示。否则你可转到下一步。

这些选项可确定应用程序如何响应未经身份验证的请求，默认选择会将所有请求重定向到用此新提供程序登录。你现在可以更改自定义此行为，也可以稍后通过选择“身份验证”设置旁边的“编辑”，在主要“身份验证”屏幕上调整这些设置。若要详细了解这些选项，请参阅身份验证流。
（可选）选择“下一步：权限”并添加应用程序所需的任何 Microsoft Graph 权限。这些作用域将被添加到应用注册中，但你也可以稍后更改它们。
选择添加。

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

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

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

可以将应用服务身份验证配置为使用现有应用注册。以下情况是使用现有应用注册的最常见情况：

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

步骤 1：在 Microsoft Entra ID 中为你的应用服务应用创建应用注册

在应用注册的创建期间，请收集以下信息，稍后在应用服务应用中配置身份验证时需要用到它们：

客户端 ID
租户 ID
客户端密码（可选，但建议使用）
应用程序 ID URI

创建应用注册的说明取决于你使用的是工作人员租户还是客户租户。使用以下选项卡为方案选择正确的说明集。

若要注册应用，请执行以下步骤：

登录到 Azure 门户，搜索并选择“应用服务”，然后选择应用。记下应用的 URL。稍后要使用它来配置 Microsoft Entra 应用注册。
在门户中导航到你的租户：
- 工作人员租户
- 客户租户
在门户菜单中，选择“Microsoft Entra ID”。如果你使用的租户不同于用于配置应用服务应用程序的租户，则需要先更改目录。
1. 如果你还没有客户租户，请按照创建客户身份验证和访问管理 (CIAM) 租户中的说明创建一个租户。
2. 将 Azure 门户中的目录切换为客户租户。
  
  提示
  
  由于你在两个租户上下文中工作（订阅的租户和客户租户），因此你可能需要在 Web 浏览器的两个单独的选项卡中打开 Azure 门户。每个都可以登录到不同的租户。
3. 在门户菜单中，选择“Microsoft Entra ID”。
在“概述”屏幕上，记下 租户 ID 以及主域。
在左侧导航栏中，选择“应用注册”>“新建注册”。
在“注册应用”页上的“名称”中，输入应用注册的名称。
在“支持的帐户类型”中，选择可以访问此应用程序的帐户类型。
在“重定向 URI”部分中，选择“Web”平台，然后键入 <app-url>/.auth/login/aad/callback。例如，https://contoso.azurewebsites.net/.auth/login/aad/callback。
选择“注册”。
在应用注册创建后，复制“应用(客户端) ID”和“目录(租户) ID”，以供稍后使用。
从左侧导航栏中选择“身份验证”。在“隐式授权和混合流”下，启用“ID 令牌”，以允许 OpenID Connect 用户从应用服务登录。选择“保存”。
（可选）从左侧导航中，选择“品牌打造和属性”。在“主页 URL”中，输入应用服务应用的 URL，然后选择“保存”。
在左侧导航栏中，选择“公开 API”>“添加”>“保存”。此值在应用程序用作资源时唯一标识该应用程序，从而可以请求令牌以授予访问权限。它用作所创建作用域的前缀。

对于单租户应用，可以使用默认值，其格式为 api://<application-client-id>。还可以根据租户的一个已验证域指定更具可读性的 URI，例如 https://contoso.com/api。对于多租户应用，必须提供自定义 URI。要详细了解可接受的应用 ID URI 格式，请参阅应用注册最佳做法参考。
选择“添加范围”。
1. 在“范围名称”中输入 user_impersonation。
2. 如果要允许用户许可此范围的权限，请在“谁可以同意”中选择“管理员和用户”。
3. 在文本框中，输入许可范围名称，以及希望在许可页上向用户显示的说明。例如，输入“访问 <应用程序名>”。
4. 选择“添加作用域”。
（可选）：要创建客户端密码：
1. 从左侧导航中，选择“证书和机密”>“客户端密码”>“新建客户端密码”。
2. 输入说明和过期时间，然后选择“添加”。
3. 在“值”字段中，复制客户端密码值。离开此页面后，它将不会再次显示。
（可选）若要添加多个回复 URL，请选择“身份验证”。
完成应用注册设置：
- 工作人员租户
- 客户租户
无需对工作人员租户执行其他步骤。
1. 创建用户流，它会定义可在租户中的应用注册之间共享的身份验证体验：
  1. 导航回租户并选择“外部标识”。
  2. （可选）在“所有标识提供者”下配置标识提供者。有关可用选项的详细信息，请参阅客户的身份验证方法和标识提供者。
  3. 选择“用户流>新建用户流”。
  4. 输入名称（如“SignUpSignIn”），然后选择想要在此流中使用的标识提供者和用户特性。完成后，选择“创建”。
  创建注册和登录用户流中也介绍了这些步骤。
2. 配置应用注册以使用用户流：
  1. 选择刚刚创建的用户流。
  2. 选择“应用程序>添加应用程序”。
  3. 搜索之前创建的应用注册，将其选中，然后单击“选择”。
  将应用程序添加到用户流中也介绍了这些步骤。
3. 将目录切换回包含订阅和应用服务应用的租户，以便执行后续步骤。

步骤 2：在应用服务应用中启用 Microsoft Entra ID

登录 Azure 门户并导航到你的应用程序。
在左侧导航栏中，选择“身份验证”>“添加标识提供者”>“Microsoft”。
选择所创建应用注册的“租户类型”。

根据相应租户类型的说明，将应用配置为使用你创建的注册：

工作人员租户
客户租户

对于“应用注册类型”，选择以下选项之一：

选取此目录中的一个现有应用注册：从当前租户中选择一个应用注册，并自动收集必要的应用信息。系统将尝试针对应用注册创建新的客户端密码，并自动配置应用以使用它。默认颁发者 URL 是根据应用注册中配置的受支持帐户类型设置的。如果打算更改此默认值，请参阅下表。
提供现有应用注册的详细信息：或者如果你的帐户在当前租户中没有查询注册的权限，则指定来自另一个租户的应用注册的详细信息。对于此选项，必须根据下表手动填写配置值。

工作人员租户的身份验证终结点应是特定于云环境的值。例如，全球 Azure 中的劳动力租户将使用“https://login.microsoftonline.com"”作为其身份验证终结点。记下身份验证终结点值，因为构造正确的颁发者 URL 需要它。

对于客户租户，必须根据下表手动填写配置值。

客户租户的身份验证终结点应为 https://<tenant-subdomain>.ciamlogin.com，将 <tenant-subdomain> 替换为租户的默认子域。默认子域是租户的主域的一部分，它应采用格式 <tenant-subdomain>.onmicrosoft.com，它是在创建租户期间设置的。例如，如果租户具有域“contoso.onmicrosoft.com”，则租户子域为“contoso”，身份验证终结点为“https://contoso.ciamlogin.com"”。记下身份验证终结点值，因为构造正确的颁发者 URL 需要它。

直接填写配置详细信息时，请使用在应用注册创建过程中收集的值：

字段	说明
应用程序（客户端）ID	使用应用注册的应用（客户端）ID。
客户端机密	使用在应用注册中生成的客户端机密。使用客户端密码，将使用混合流，并且应用服务将返回访问令牌和刷新令牌。如果未设置客户端机密，则使用隐式流并仅返回 ID 令牌。这些令牌由提供者发送并存储在应用服务身份验证令牌存储中。
颁发者 URL	使用 `<authentication-endpoint>/<tenant-id>/v2.0`，并将 <authentication-endpoint> 替换为你在之前的步骤中为租户类型和云环境确定的身份验证终结点，同时将 <tenant-id> 替换为在其中创建应用注册的“目录（租户）ID”。对于使用 Azure AD v1 的应用程序，请省略 URL 中的 `/v2.0`。此值用于将用户重定向到正确的 Microsoft Entra 租户，并下载适当的元数据，以确定相应的令牌签名密钥和令牌颁发者声明值等。除特定于租户的终结点之外的任何配置都将被视为多租户。在多租户配置中，系统不对颁发者或租户 ID 执行验证，应在你的应用的授权逻辑中全面处理这些检查。
允许的令牌受众	此字段是可选的。配置的应用程序（客户端）ID 始终被隐式视为允许的受众。如果你的应用程序代表将由其他客户端调用的 API，则还应添加在应用注册上配置的应用程序 ID URI。允许的受众列表有 500 个总字符的限制。

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

如果这是为应用程序配置的第一个标识提供程序，你还将看到“应用服务身份验证设置”部分的提示。否则你可转到下一步。

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

授权请求

默认情况下，应用服务身份验证仅处理身份验证，确定调用方是否符合他们声称的身份。授权（确定调用方是否应有权访问某些资源）是身份验证之外的额外步骤。可以从 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 的逗号分隔列表（例如 “559a2f9c-c6f2-4d31-b8d6-5ad1a13f8330, 5693f64a-3ad5-4be7-b846-e9d1141bcebc”），从而要求传入令牌来自 tid 声明指定的租户之一。可以将 WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL 应用程序设置配置为“true”或“1”，以要求传入令牌包含 oid 声明。如果 allowedPrincipals.identities 已配置，则此设置会被忽略并视为 true，因为已根据此提供的标识列表检查了 oid 声明。

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

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

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

本机客户端应用程序

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

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

注意

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

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

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

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

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

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

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

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

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

最佳做法

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

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

迁移到 Microsoft Graph

某些较旧的应用可能还设置了对计划完全停用的已弃用的 Azure AD Graph 的依赖项。例如，应用代码可能已调用 Azure AD Graph，在中间件管道中的授权筛选器中检查组成员身份。应用应按照 Microsoft Entra ID 在 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 ID 提供的指南，还需要更新应用程序代码中对该令牌的任何使用。

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