备注
从 2024 年 6 月 1 日开始,新创建的应用服务应用可以生成使用命名约定 <app-name>-<random-hash>.<region>.chinacloudsites.cn
的唯一默认主机名。 现有应用名称保持不变。 例如:
myapp-ds27dh7271aah175.chinanorth3-01.chinacloudsites.cn
选择另一个身份验证提供商以跳转到它。
本文介绍如何为 Azure 应用服务或 Azure Functions 配置身份验证,使应用使用 Microsoft 标识平台 (Microsoft Entra) 作为身份验证提供程序让用户登录。
在应用程序可以登录用户之前,需要在员工租户或外部租户中注册它。 如果使应用可供员工或业务来宾使用,请在员工租户中注册应用。 如果应用供消费者和企业客户使用,请在外部租户中注册应用。
登录到 Azure 门户并转到你的应用。
在应用的左侧菜单中,选择“设置”>“身份验证”,然后选择“添加标识提供者”。
在 “添加标识提供者” 页上,选择 Microsoft 作为 标识提供者 值,用 Microsoft 和 Microsoft Entra 标识登录。
在 “为应用程序及其用户选择租户”下,选择以下任一项:
- 为员工和商务访客选择“工作人员配置(当前租户)”
- 面向使用者和企业客户的外部配置
应用服务身份验证功能可以自动为你创建应用注册。 或者,可以使用你或目录管理员单独创建的注册。
自动创建新的应用注册,除非需要单独创建应用注册。 如果需要,可以稍后在 Microsoft Entra 管理中心中自定义应用注册。
下面是使用现有应用注册的最常见情况:
- 你的帐户无权在 Microsoft Entra 租户中创建应用注册。
- 你希望使用的应用注册来自与包含应用的租户不同的 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 引用。 或者,可以更改此项以 使用标识而不是客户端密码。 对使用标识的支持目前处于预览状态。
若要使用现有注册,请选择以下任一项:
在此目录中选取现有应用注册。 然后从下拉列表中选择应用注册。
提供现有应用注册的详细信息。 然后提供:
应用程序(客户端)ID。
客户端密码(推荐)。 应用程序在请求令牌时用于证明其身份的一个秘密值。 此值作为名为
MICROSOFT_PROVIDER_AUTHENTICATION_SECRET
的槽粘滞应用程序设置,保存在应用配置中。 如果未设置客户端密码,则来自服务的登录操作会使用 OAuth 2.0 隐式授权流,但不建议使用该流。发行者 URL。 此 URL 采用格式
<authentication-endpoint>/<tenant-id>/v2.0
。 将<authentication-endpoint>
替换为特定于云环境的身份验证终结点值。 例如,在全球 Azure 中,员工租户将使用https://sts.chinacloudapi.cn
作为其身份验证终结点。
如果需要在组织租户中手动创建应用注册,请参阅在 Microsoft 标识平台上注册应用程序。 完成注册过程时,请务必记下应用程序(客户端)ID 和客户端密码值。
在注册过程中,在 “重定向 URI ”部分中,为平台选择 “Web ”,然后输入 <app-url>/.auth/login/aad/callback
。 例如,输入 https://contoso.chinacloudsites.cn/.auth/login/aad/callback
。
现在,修改应用注册:
在左窗格中,选择“ 公开 API>添加>保存”。 当此值用作资源时,它以唯一方式标识应用程序,从而可以请求授予访问权限的令牌。 该值是所创建的作用域的前缀。
对于单租户应用,可以使用默认值,其格式为
api://<application-client-id>
。 还可以根据租户的一个已验证域指定更可读的 URI,例如https://contoso.com/api
。 对于多租户应用,必须提供自定义 URI。 有关应用 ID URI 接受的格式的详细信息,请参阅 Microsoft Entra ID 中应用程序属性的安全最佳做法。选择 “添加范围”,然后:
- 在“范围名称”中输入“user_impersonation”。
- 如果要允许用户许可此范围的权限,请在“谁可以同意”中选择“管理员和用户”。
- 输入同意范围名称。 输入希望用户在同意页面上看到的说明。 例如,输入 Access应用程序名称。
- 选择“添加范围”。
(推荐)为应用创建客户端断言。 若要创建客户端机密,请执行以下操作:
- 在左窗格中,选择“证书和机密客户端机密>>”新建客户端机密。
- 输入说明和到期时间,然后选择“ 添加”。
- 在“值”字段中,复制客户端密码值。 离开此页面后,它不会再次显示。
(可选)若要添加多个回复 URL,请选择“ 身份验证”。
其他检查会确定允许哪些请求访问应用程序。 现在可以自定义此行为,或者以后可以通过选择“身份验证设置”旁边的“编辑”从主“身份验证”页调整这些设置。
对于客户端应用程序要求,请选择是否:
- 仅允许来自此应用程序本身的请求。
- 允许来自特定客户端应用程序的请求。
- 允许来自任何应用程序的请求(不建议)。
对于标识要求,请选择是否:
- 允许来自任何标识的请求。
- 允许来自特定标识的请求。
对于租户要求,请选择是否:
- 仅允许来自颁发者租户的请求。
- 允许来自特定租户的请求。
- 根据颁发者使用默认限制。
你的应用可能仍然需要在代码中做出其他授权决策。 有关详细信息,请参阅本文后面的 “使用内置授权策略 ”。
身份验证设置确定应用程序如何响应未经身份验证的请求。 默认选择会重定向所有使用此新提供者进行登录的请求。 现在可以自定义此行为,或者以后可以通过选择“身份验证设置”旁边的“编辑”从主“身份验证”页调整这些设置。 有关详细信息,请参阅身份验证流。
对于 限制访问,请决定是否:
- 需要身份验证。
- 允许未经身份验证的访问。
对于 未经身份验证的请求,请选择错误选项:
- HTTP
302 Found redirect
:建议用于网站 - HTTP
401 Unauthorized
:建议用于 API - HTTP
403 Forbidden
- HTTP
404 Not found
选择“令牌存储”(建议)。 令牌存储收集、存储和刷新应用程序令牌。 如果应用不需要令牌,或者需要优化性能,则可以稍后禁用此行为。
如果选择了员工配置,可以选择“ 下一步:权限 ”,并添加应用程序所需的任何Microsoft Graph 权限。 这些权限将被添加到应用注册中,但你也可以稍后更改它们。 如果选择了外部配置,则可以稍后添加 Microsoft Graph 权限。
- 选择 添加 。
现在,你可以在应用中使用 Microsoft 标识平台进行身份验证了。 该提供者在“身份验证”页上列出。 在该屏幕上,你可以编辑或删除此提供者配置。
有关为访问 Azure 存储和 Microsoft Graph 的 Web 应用配置 Microsoft Entra 登录的示例,请参阅将应用身份验证添加到 Web 应用。
默认情况下,应用服务身份验证仅处理 身份验证。 它确定调用方是否是声称的那样。 授权(确定调用方是否应有权访问某些资源)是身份验证之外的一个步骤。 有关详细信息,请参阅授权基础知识。
你的应用可以在代码中做出授权决策。 应用服务身份验证提供一些内置检查,这些检查可能会有所帮助,但它们本身可能不足以满足应用的授权需求。 以下部分介绍这些功能。
提示
在此过程中,多租户应用程序应验证请求的颁发者和租户 ID,确保这些值是允许的。 为多租户方案配置应用服务身份验证时,它不会验证请求来自哪个租户。 根据组织是否已注册服务(例如),应用可能需要限制为特定租户。 请参阅更新代码以处理多个颁发者值。
在应用代码中执行授权检查时,可以使用应用服务身份验证提供的声明信息。 有关详细信息,请参阅访问应用代码中的用户声明。
注入的 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": []
}
}
}
}
财产 | 说明 |
---|---|
defaultAuthorizationPolicy |
必须满足一组要求才能访问应用。 根据对其配置的每个属性进行的逻辑 AND 授予访问权限。 当allowedApplications 和allowedPrincipals 都被配置时,传入请求必须满足这两个要求才能被接受。 |
allowedApplications |
字符串应用程序客户端 ID 的允许列表,这些 ID 表示调用应用的客户端资源。 当此属性配置为非空数组时,只有通过列表中指定应用程序获得的令牌才会被接受。 此策略评估传入令牌的 appid 或 azp 声明,该令牌必须是访问令牌。 请参阅有效负载声明。 |
allowedPrincipals |
一组检查,用于确定传入请求表示的主体是否可以访问应用。 allowedPrincipals 的满意度基于对其配置的属性进行的逻辑 OR 来判断。 |
identities (在 allowedPrincipals 下) |
字符串对象 ID 的允许列表,表示有权访问的用户或应用程序。 如果将此属性配置为非空数组,则如果请求表示的用户或应用程序在列表中指定, allowedPrincipals 则可以满足该要求。 标识列表的总字符数限制为 500 个字符。此策略评估传入令牌的 oid 声明。 请参阅有效负载声明。 |
此外,无论使用的 API 版本如何,都可以通过 应用程序设置配置一些检查。 可以使用最多 10 个租户 ID 的逗号分隔列表配置 WEBSITE_AUTH_AAD_ALLOWED_TENANTS
应用程序设置;例如 aaaabbbb-0000-cccc-1111-dddd2222eeee
。 此设置可能要求传入令牌来自某个指定的租户(由 tid
声明指定)。
可以将 WEBSITE_AUTH_AAD_REQUIRE_CLIENT_SERVICE_PRINCIPAL
应用程序设置配置为 true
或 1
,以要求传入令牌包含 oid
声明。 如果已配置 allowedPrincipals.identities
,此设置会被忽略并被视为 true,因为会对照所提供的此标识列表检查 oid
声明。
这些内置检查失败的请求会收到 HTTP 403 Forbidden
响应。
可以将应用程序配置为信任托管标识(预览版),而不是为应用注册配置客户端密码。 使用标识而不是机密意味着无需管理机密。 你没有秘密过期事件需要处理,并且没有与可能因披露或泄露该秘密而关联的相同级别的风险。
通过标识,可以创建 联合标识凭据,该凭据可以用作 客户端断言,而不是客户端机密。 此方法仅适用于员工配置。 内置身份验证功能目前以预览版的形式支持联合标识凭据。
可以使用本部分中的步骤来配置应用服务或 Azure Functions 资源以使用此模式。 此处的步骤假定你已使用某个受支持的方法设置应用注册,并且已定义机密。
根据这些说明创建用户分配的托管标识资源。
将该标识分配给 你的应用服务或 Azure Functions 资源。
重要
创建的用户分配的托管标识只能通过此注册分配给应用服务或 Azure Functions 应用程序。 如果将标识分配给另一个资源,则向该资源授予对应用注册不必要的访问权限。
记下托管标识的对象 ID 和 客户端 ID 值。 在下一步中,需要对象 ID 才能创建联合标识凭据。 你将在后续步骤中使用托管标识的客户端 ID。
按照 Microsoft Entra ID 说明在现有应用程序中配置联合标识凭据。 这些说明还包括用于更新应用程序代码的部分,你可以跳过这些代码。
添加一个名为
OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID
的新应用程序设置。 将其值设置为在上一步中获取的托管标识的 客户端 ID 值。 请勿使用应用注册的客户端 ID。 请确保将该应用程序设置标记为“槽粘滞”。在应用资源的内置身份验证设置中,将 客户端机密设置名称 设置为
OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID
。若要使用 Azure 门户进行此更改,请执行以下作:
- 返回到应用服务或 Azure Functions 资源,然后选择“ 身份验证 ”选项卡。
- 在 “标识提供者 ”部分的 “Microsoft ”条目中,选择 “编辑” 列中的图标。
- 在 “编辑标识提供者 ”对话框中,打开 客户端机密设置名称 的下拉列表,然后选择
OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID
。 - 选择“保存”。
若要使用 REST API 进行此更改,请执行以下作:
- 将
clientSecretSettingName
属性设置为OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID
。 可以在properties
>identityProviders
>azureActiveDirectory
>registration
下找到此属性。
验证应用程序是否按预期工作。 你应该能够成功执行新的登录操作。
如果对使用托管标识的行为感到满意,请删除现有密钥:
确保应用代码不依赖于应用程序设置。 如果这样做,请按照 说明更新应用程序代码以请求访问令牌。
删除以前保存机密的应用程序设置。 此应用程序设置的名称是以前的 客户端机密设置名称 值,然后再将其设置为
OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID
。请使用包含应用注册的租户帐户登录到 Microsoft Entra 管理中心。 再次转到应用注册。
在 “证书和机密”下,选择 “客户端机密 ”并删除客户端密码。
现在,你的应用配置为在没有机密的情况下使用 Microsoft Entra ID 身份验证。
在前面的部分中,你注册了应用服务或 Azure Functions 应用以对用户进行身份验证。 以下部分介绍如何在 Microsoft Entra 中注册本机客户端或守护程序应用。 这些客户端或应用可以请求访问应用服务代表用户或自己公开的 API,例如在 N 层体系结构中。 如果只想对用户进行身份验证,则不需要以下部分中的步骤。
可以注册本机客户端,以代表登录用户请求访问应用服务应用的 API:
在 Azure 门户菜单上,选择 Microsoft Entra ID。
在左窗格中,选择“ 管理>应用注册”。 然后选择“ 新建注册”。
在“ 注册应用程序 ”窗格中,对于 “名称”,输入应用注册的名称。
在 重定向 URI 中,选择 公共客户端/本机应用(移动和桌面),然后输入 URL
<app-url>/.auth/login/aad/callback
。 例如,输入https://contoso.chinacloudsites.cn/.auth/login/aad/callback
。选择“注册”。
创建应用注册后,复制“应用程序(客户端) ID”的值。
备注
对于Microsoft Store 应用程序,请改用包 SID 作为 URI。
在左窗格中,选择“ 管理>API 权限”。 然后选择“添加权限”>“我的 API”。
选择之前为应用服务应用创建的应用注册。 如果没有看到应用注册,请务必在应用注册中添加“user_impersonation”范围。
在“委托的权限”下,依次选择“user_impersonation”和“添加权限”。
现在,你已配置了一个本机客户端应用程序,该应用程序可以代表用户请求访问应用服务应用。
在 N 层体系结构中,客户端应用程序可以获取令牌,以代表客户端应用本身(而不是代表用户)调用应用服务或 Azure Functions 应用。 此方案适用于非交互式守护程序应用程序,这些应用程序在没有登录用户的情况下执行任务。 它使用标准 OAuth 2.0 客户端凭据授权。 有关详细信息,请参阅 Microsoft 标识平台和 OAuth 2.0 客户端凭据流。
在 Azure 门户菜单上,选择 Microsoft Entra ID。
在左窗格中,选择“ 管理>应用注册”。 然后选择“ 新建注册”。
在“ 注册应用程序 ”窗格中,对于 “名称”,输入应用注册的名称。
对于守护程序应用程序,不需要重定向 URI,因此可以将 “重定向 URI ”框保留为空。
选择“注册”。
创建应用注册后,复制“应用程序(客户端) ID”的值。
在左窗格中,选择“ 管理>证书和机密”。 然后,选择“客户端密码”“新建客户端密码”>。
输入说明和到期时间,然后选择“ 添加”。
在“值”字段中,复制客户端密码值。 离开此页面后,它不会再次显示。
现在可以使用 客户端 ID 和客户端密码请求访问令牌。 将 resource
参数设置为目标应用 的应用程序 ID URI 值。 然后,可以通过标准 OAuth 2.0 授权标头向目标应用显示生成的访问令牌。 应用服务身份验证验证并使用令牌来指示调用方已经过身份验证。 在这种情况下,调用方是应用程序,而不是用户。
此方法允许 Microsoft Entra 租户中的任何客户端应用程序请求访问令牌,并向目标应用进行身份验证。 如果还希望强制授权以仅允许某些客户端应用程序,则必须执行额外的配置。
在应用注册清单中定义应用角色,该清单表示要保护的应用服务或 Azure Functions 应用。
在表示需要获得授权的客户端的应用注册上,选择“API 权限”>“添加权限”>“我的 API”。
选择之前创建的应用注册。 如果未看到应用注册,请确保 已添加应用角色。
在 “应用程序权限”下,选择之前创建的应用角色。 然后选择“添加权限”。
选择 “授予管理员许可 ”以授权客户端应用程序请求权限。
与前面的方案类似(添加任何角色之前),现在可以为同一目标资源请求访问令牌。 访问令牌包括一个
roles
声明,其中包含为客户端应用程序授权的应用角色。
在目标应用服务或 Azure Functions 应用代码中,现在可以验证令牌是否具有预期角色。 应用服务身份验证不执行此验证。 有关详细信息,请参阅访问应用代码中的用户声明。
现在,你已配置一个守护程序客户端应用程序,该应用程序可以使用自己的标识访问应用服务应用。
无论用于设置身份验证的配置如何,以下最佳做法使租户和应用程序更安全:
- 在 Microsoft Entra 中为每个应用服务应用配置各自的应用注册。
- 为每个应用服务应用提供其自身的权限和许可。
- 避免在环境之间共享权限。 为单独的部署槽位使用单独的应用注册。 在测试新代码时,这种做法可有助于防止出现影响生产应用的问题。