你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
管理应用服务身份验证的 API 和运行时版本
本文介绍如何自定义应用服务中的内置身份验证和授权的 API 和运行时版本。
用于应用服务身份验证的管理 API 有两个版本。 V2 版本是 Azure 门户“身份验证”体验的必备项。 已在使用 V1 API 的应用可在进行一些更改后升级到 V2 版本。 具体而言,必须将机密配置移至槽粘滞应用程序设置。 这可以从应用门户的“身份验证”部分自动完成。
更新配置版本
警告
迁移到 V2 后,将会禁止通过某些客户端(例如应用程序在 Azure 门户、Azure CLI 和 Azure PowerShell 中的现有体验)管理应用程序的应用服务身份验证/授权功能。 此更改无法撤消。
V2 API 与 V1 不同,它不支持将 Microsoft 帐户创建或编辑为一个独特的提供程序, 但会使用聚合的 Microsoft 标识平台让拥有 Microsoft Entra 和 Microsoft 个人帐户的用户登录。 切换到 V2 API 时,V1 Microsoft Entra 配置将用于配置 Microsoft 标识平台提供程序。 V1 Microsoft 帐户提供程序在迁移过程中会被继续使用,并且会继续正常运行,但你应迁移到较新的 Microsoft 标识平台模型。 有关详细信息,请参阅对于 Microsoft 帐户提供程序注册的支持。
自动迁移过程会将提供程序机密移动到应用程序设置中,然后将其余配置转换为新格式。 若要使用自动迁移,请执行以下操作:
- 在门户中导航到应用,然后选择“身份验证”菜单选项。
- 如果该应用是使用 V1 模型配置的,你将看到“升级”按钮。
- 查看确认提示中的说明。 如果已准备好执行迁移,请选择提示中的“升级”。
手动管理迁移
如果你不希望使用上面提到的自动版本,可按照以下步骤将应用程序手动迁移到 V2 API。
将机密移动到应用程序设置
使用 V1 API 获取现有配置:
az webapp auth show -g <group_name> -n <site_name>
在生成的 JSON 有效负载中,记下已配置的每个提供程序所用的机密值:
- Microsoft Entra:
clientSecret
- Google:
googleClientSecret
- Facebook:
facebookAppSecret
- X:
twitterConsumerSecret
- Microsoft 帐户:
microsoftAccountClientSecret
重要
机密值是重要的安全凭据,应谨慎处理。 请勿共享这些值或将其保留在本地计算机。
- Microsoft Entra:
应为每个机密值创建槽粘滞应用程序设置。 可以选择每个应用程序设置的名称。 其值应与上一步中获取的值匹配,也可能引用使用该值创建的密钥保管库机密。
若要创建此设置,可使用 Azure 门户或对每个提供程序运行以下命令(应进行相应更改):
# For Web Apps, Google example az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step> # For Azure Functions, X example az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>
注意
此配置的应用程序设置应标记为槽粘滞,这意味着它们不会在槽交换操作期间在各环境之间移动。 这是因为身份验证配置本身与环境相关联。
创建名为
authsettings.json
的新 JSON 文件。 采用之前接收的输出,并删除其中的每个机密值。 将其余的输出写入该文件,确保不包含任何机密。 在某些情况下,配置中可能有包含空字符串的数组。 请确保microsoftAccountOAuthScopes
不包含这类数组,如有,请将值切换为null
。向
authsettings.json
添加一个属性,该属性指向之前为每个提供程序创建的应用程序设置名称:- Microsoft Entra:
clientSecretSettingName
- Google:
googleClientSecretSettingName
- Facebook:
facebookAppSecretSettingName
- X:
twitterConsumerSecretSettingName
- Microsoft 帐户:
microsoftAccountClientSecretSettingName
完成这一操作后的示例文件可能类似于以下内容,本例中仅对 Microsoft Entra ID 进行了配置:
{ "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings", "name": "authsettings", "type": "Microsoft.Web/sites/config", "location": "Central US", "properties": { "enabled": true, "runtimeVersion": "~1", "unauthenticatedClientAction": "AllowAnonymous", "tokenStoreEnabled": true, "allowedExternalRedirectUrls": null, "defaultProvider": "AzureActiveDirectory", "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444", "clientSecret": "", "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET", "clientSecretCertificateThumbprint": null, "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/", "allowedAudiences": [ "https://mywebapp.azurewebsites.net" ], "additionalLoginParams": null, "isAadAutoProvisioned": true, "aadClaimsAuthorization": null, "googleClientId": null, "googleClientSecret": null, "googleClientSecretSettingName": null, "googleOAuthScopes": null, "facebookAppId": null, "facebookAppSecret": null, "facebookAppSecretSettingName": null, "facebookOAuthScopes": null, "gitHubClientId": null, "gitHubClientSecret": null, "gitHubClientSecretSettingName": null, "gitHubOAuthScopes": null, "twitterConsumerKey": null, "twitterConsumerSecret": null, "twitterConsumerSecretSettingName": null, "microsoftAccountClientId": null, "microsoftAccountClientSecret": null, "microsoftAccountClientSecretSettingName": null, "microsoftAccountOAuthScopes": null, "isAuthFromFile": "false" } }
- Microsoft Entra:
提交此文件作为应用的新身份验证/授权配置:
az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json
验证应用程序在此操作后是否仍按预期运行。
删除前面的步骤中使用的文件。
现在,你已迁移应用,以将标识提供程序机密存储为应用程序设置。
对于 Microsoft 帐户提供程序注册的支持
如果现有配置包含 Microsoft 帐户提供程序而不包含 Microsoft Entra 提供程序,你可以将配置切换到 Microsoft Entra 提供程序,然后执行迁移。 要执行此操作:
- 转到 Azure 门户中的应用注册,并找到与你的 Microsoft 帐户提供程序关联的注册。 该注册可能位于“来自个人帐户的应用程序”标题下。
- 导航到该注册的“身份验证”页。 在“重定向 URI”下,你应该会看到以
/.auth/login/microsoftaccount/callback
结尾的条目。 复制此 URI。 - 添加一个与刚刚复制的 URI 匹配的新 URI,但要将其结尾改为
/.auth/login/aad/callback
。 这样,应用服务身份验证/授权配置便可以使用注册。 - 导航到应用的应用服务身份验证/授权配置。
- 收集 Microsoft 帐户提供程序的配置。
- 使用“高级”管理模式配置 Microsoft Entra 提供程序,同时提供你在上一步中收集的客户端 ID 和客户端密码值。 对于证书颁发者 URL,请使用
<authentication-endpoint>/<tenant-id>/v2.0
,然后将 <authentication-endpoint> 替换为云环境的身份验证终结点(例如,全球 Microsoft Entra ID 的“https://login.microsoftonline.com"”),同时将 <tenant-id> 替换为你的目录(租户)ID。 - 保存配置后,请在浏览器中导航到站点上的
/.auth/login/aad
终结点,以测试登录流,然后完成登录流。 - 至此,你已成功复制配置,但现有 Microsoft 帐户提供程序配置仍然存在。 在将其删除之前,请确保应用程序的所有部分都通过登录链接等引用 Microsoft Entra 提供程序。验证应用的所有部分是否按预期工作。
- 验证 Microsoft Entra 提供程序能够正常运作后,即可删除 Microsoft 帐户提供程序配置。
警告
可通过修改 Microsoft Entra 应用注册支持的帐户类型来聚合两个注册。 但这样会强制向 Microsoft 帐户用户显示新的同意提示,并且这些用户的标识声明在结构上可能不同,同时由于正在使用新的应用 ID,sub
值会发生明显变化。 除非完全理解此方法,否则不建议使用该方法。 应等待 V2 API 表面提供对两个注册的支持。
切换到 V2
执行上述步骤后,请在 Azure 门户中导航到应用。 选择“身份验证(预览)”部分。
或者,也可以对站点资源下的 config/authsettingsv2
资源发出 PUT 请求。 有效负载的架构与基于文件的配置部分所介绍的内容相同。
将应用固定到特定身份验证运行时版本
启用身份验证/授权时,会将平台中间件注入 HTTP 请求管道,如功能概述中所述。 作为平台例常更新的一部分,此平台中间件定期更新新功能和改进。 默认情况下,Web 或函数应用在此平台中间件的最新版本上运行。 这些自动更新始终向后兼容。 但在极少情况下此自动更新引入 Web 或函数应用的运行时问题,此时可以暂时回滚到以前的中间件版本。 本文介绍如何将应用临时固定到特定版本的身份验证中间件。
自动和手动版本更新
可以通过设置应用的 runtimeVersion
设置,将应用固定到平台中间件的特定版本。 应用始终在最新版本上运行,除非选择将其显式固定回特定版本。 一次支持几个版本。 如果固定到不再受支持的无效版本,应用将改用最新版本。 若要始终运行最新版本,将 runtimeVersion
设为 ~1。
查看和更新当前运行时版本
可以更改应用使用的运行时版本。 新的运行时版本应在重启应用后生效。
查看当前运行时版本
可以使用 Azure CLI 或应用中的内置版本 HTTP 终结点之一来查看平台身份验证中间件的当前版本。
通过 Azure CLI
使用 Azure CLI 通过 az webapp auth show 命令查看当前中间件版本。
az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>
在此代码中,用应用名称替换 <my_app_name>
。 还使用应用的资源组名称替换 <my_resource_group>
。
你将在 CLI 输出中看到 runtimeVersion
字段。 它类似于以下示例输出,为了清晰起见,该输出已被截断:
{
"additionalLoginParams": null,
"allowedAudiences": null,
...
"runtimeVersion": "1.3.2",
...
}
使用版本终结点
还可点击应用上的 /.auth/version 终结点来查看应用运行所在的当前中间件版本。 它类似于以下示例输出:
{
"version": "1.3.2"
}
更新当前运行时版本
使用 Azure CLI,可以通过 az webapp auth update 命令更新应用中的 runtimeVersion
设置。
az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>
将 <my_app_name>
替换为你的应用的名称。 还使用应用的资源组名称替换 <my_resource_group>
。 另外,将 <version>
替换为 1.x 运行时的有效版本,或替换为 ~1
获取最新版本。 请参阅不同运行时版本的发行说明,以便确定要固定到的版本。
可以通过在前面代码示例中选择“试一试”运行这个来自 Azure Cloud Shell 的命令。 还可以在执行 az login 登录后使用 Azure CLI 在本地执行此命令。