对联机终结点的客户端进行身份验证
适用范围：
Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）
本文介绍如何对客户端进行身份验证，以便在联机终结点上执行控制平面和数据平面操作。
控制平面操作可控制终结点并对其进行更改。 控制平面操作包括在联机终结点和联机部署上进行的创建、读取、更新和删除 (CRUD) 操作。
数据平面操作使用数据与联机终结点交互，而无需更改终结点。 例如，数据平面操作可能包括向联机终结点发送评分请求并获取响应。
在按照本文中的步骤操作之前，请确保满足以下先决条件：
Azure 机器学习工作区。 如果没有，请按照快速入门：创建工作区资源一文中的步骤创建一个。
Azure CLI 和
ml扩展或 Azure 机器学习 Python SDK v2：若要安装 Azure CLI 和扩展，请参阅安装、设置和使用 CLI (v2)。
重要
本文中的 CLI 示例假定你使用的是 Bash（或兼容的）shell。 例如，从 Linux 系统或者适用于 Linux 的 Windows 子系统。
若要安装 Python SDK v2，请使用以下命令：
pip install azure-ai-ml azure-identity要将 SDK 的现有安装更新到最新版本，请使用以下命令：
pip install --upgrade azure-ai-ml azure-identity有关详细信息，请参阅安装适用于 Azure 机器学习的 Python SDK v2。
需要用户标识才能在联机终结点上执行控制平面操作（即 CRUD 操作）和数据平面操作（即发送评分请求）。 可以对控制平面操作和数据平面操作使用相同的用户标识，也可使用不同的用户标识。 在本文中，你将对控制平面和数据平面操作使用相同的用户标识。
若要在 Microsoft Entra ID 下创建用户标识，请参阅设置身份验证。 稍后需要标识 ID。
在本部分中，将为用于与终结点交互的用户标识分配权限。 首先使用内置角色或创建自定义角色。 然后，将角色分配给用户标识。
AzureML Data Scientist 内置角色可用于管理和使用终结点及部署，并使用通配符来包括以下控制平面 RBAC 操作：
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/writeMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/deleteMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/readMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/token/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action
并包括以下数据平面 RBAC 操作：
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action
（可选）Azure Machine Learning Workspace Connection Secrets Reader 内置角色可用于从工作区连接访问机密，并纳入以下控制平面 RBAC 操作：
Microsoft.MachineLearningServices/workspaces/connections/listsecrets/actionMicrosoft.MachineLearningServices/workspaces/metadata/secrets/read
如果使用这些内置角色，此步骤不需要执行任何操作。
如果使用内置角色或其他预制自定义角色，可以跳过此步骤。
通过创建角色的 JSON 定义来定义自定义角色的范围和操作。 例如，以下角色定义允许用户在指定的工作区下对联机终结点执行 CRUD 操作。
custom-role-for-control-plane.json：
{ "Name": "Custom role for control plane operations - online endpoint", "IsCustom": true, "Description": "Can CRUD against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action", "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>" ] }以下角色定义允许用户在指定的工作区下向联机终结点发送评分请求。
custom-role-for-scoring.json：
{ "Name": "Custom role for scoring - online endpoint", "IsCustom": true, "Description": "Can score against online endpoints.", "Actions": [ "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action" ], "NotActions": [ ], "AssignableScopes": [ "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>" ] }使用 JSON 定义创建自定义角色：
az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionId> az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionId>备注
若要创建自定义角色，需要具有下面三个角色之一：
- owner
- 用户访问管理员
- 具有
Microsoft.Authorization/roleDefinitions/write权限（可创建/更新/删除自定义角色）和Microsoft.Authorization/roleDefinitions/read权限（可查看自定义角色）的自定义角色。
若要详细了解如何创建自定义角色，请参阅 Azure 自定义角色。
验证角色定义：
az role definition list --custom-role-only -o table az role definition list -n "Custom role for control plane operations - online endpoint" az role definition list -n "Custom role for scoring - online endpoint" export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')` export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`
如果使用
AzureML Data Scientist内置角色，请使用以下代码将角色分配给用户标识。az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>（可选）如果使用
Azure Machine Learning Workspace Connection Secrets Reader内置角色，请使用以下代码将角色分配给用户标识。az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>如果使用自定义角色，请使用以下代码将角色分配给用户标识。
az role assignment create --assignee <identityId> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName> az role assignment create --assignee <identityId> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>备注
若要将自定义角色分配给用户标识，需要具有下面三个角色之一：
- owner
- 用户访问管理员
- 具有
Microsoft.Authorization/roleAssignments/write权限（可分配自定义角色）和Microsoft.Authorization/roleAssignments/read（可查看角色分配）的自定义角色。
若要详细了解不同的 Azure 角色及其权限，请参阅 Azure 角色和使用 Azure 门户分配 Azure 角色。
确认角色分配：
az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
如果计划使用 REST API 执行控制平面操作，请执行此步骤，这将直接使用该令牌。
如果计划使用其他方法，例如 Azure 机器学习 CLI (v2)、Python SDK (v2) 或 Azure 机器学习工作室，则无需手动获取 Microsoft Entra 令牌。 相反，在登录期间，用户标识已经过身份验证，系统会自动检索和传递令牌。
可以从 Azure 资源终结点检索用于控制平面操作的 Microsoft Entra 令牌：https://management.chinacloudapi.cn。
登录 Azure。
az login如果要使用特定标识，请通过以下代码使用标识进行登录：
az login --identity --username <identityId>使用此上下文获取令牌。
export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken | tr -d '"')`
检索 Microsoft Entra 令牌后，可通过 jwt.ms 解码令牌来验证令牌是否适用于正确的 Azure 资源终结点 management.chinacloudapi.cn 和正确的客户端 ID，这将返回包含以下信息的 json 响应：
{
"aud": "https://management.chinacloudapi.cn",
"oid": "<your-object-id>"
}
以下示例会创建一个将系统分配的标识 (SAI) 用作终结点标识的终结点。 SAI 是终结点托管标识的默认标识类型。 会为 SAI 自动分配一些基本角色。 若要详细了解系统分配标识的角色分配，请参阅终结点标识的自动角色分配。
CLI 不要求显式提供控制平面令牌。 相反，CLI az login 会在登录期间对你进行身份验证，系统会自动检索和传递令牌。
创建终结点定义 YAML 文件。
endpoint.yml：
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json name: my-endpoint auth_mode: aad_token可以将
auth_mode替换为key来进行密钥身份验证，或者替换为aml_token来进行 Azure 机器学习令牌身份验证。在此示例中，使用aad_token来进行 Microsoft Entra 令牌身份验证。az ml online-endpoint create -f endpoint.yml检查终结点的状态：
az ml online-endpoint show -n my-endpoint如果要在创建终结点时替代
auth_mode（例如，替代为aad_token），请运行以下代码：az ml online-endpoint create -n my-endpoint --auth_mode aad_token如果要更新现有终结点并指定
auth_mode（例如，指定为aad_token），请运行以下代码：az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token
若要创建部署，请参阅使用联机终结点部署 ML 模型或使用 REST 将模型部署为联机终结点。 为不同的身份验证模式创建部署的方式没有区别。
以下代码是关于如何创建部署的示例。 若要详细了解如何部署联机终结点，请参阅使用联机终结点部署 ML 模型（通过 CLI）
创建部署定义 YAML 文件。
blue-deployment.yml：
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json name: blue endpoint_name: my-aad-auth-endp1 model: path: ../../model-1/model/ code_configuration: code: ../../model-1/onlinescoring/ scoring_script: score.py environment: conda_file: ../../model-1/environment/conda.yml image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest instance_type: Standard_DS3_v2 instance_count: 1使用 YAML 文件创建部署。 对于此示例，请将所有流量设置为新部署。
az ml online-deployment create -f blue-deployment.yml --all-traffic
如果计划使用 CLI 来调用终结点，则不需要显式获取评分 URI，因为 CLI 会为你处理它。 但是，仍可使用 CLI 获取评分 URI，以便将它与其他通道（例如 REST API）一起使用。
scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")
密钥或令牌可用于数据平面操作，即使获取密钥或令牌的过程是控制平面操作也是如此。 换句话说，可以使用控制平面令牌获取稍后用于执行数据平面操作的密钥或令牌。
要获取密钥或 Azure 机器学习令牌，需要将正确的角色分配给请求它的用户标识，如控制平面操作授权中所述。 获取 Microsoft Entra 令牌不需要用户标识的任何额外角色。
如果计划使用 CLI 来调用终结点，则不需要显式获取数据平面操作的密钥或令牌，因为 CLI 会为你处理它。 但是，仍可使用 CLI 获取数据平面操作的密钥或令牌，以便将它与其他通道（例如 REST API）一起使用。
若要获取数据平面操作的密钥或令牌，请使用 az ml online-endpoint get-credentials 命令。 此命令返回一个 JSON 输出，其中包含密钥、令牌和/或其他信息。
提示
以 CLI 命令的 --query 参数为例，从 JSON 输出中提取特定信息。 但是，可以使用任何合适的工具来实现此目的。
当终结点的 auth_mode 为 key 时
- 密钥在
primaryKey和secondaryKey字段中返回。
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)
export DATA_PLANE_TOKEN2=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query secondaryKey)
当终结点的 auth_mode 为 aml_token 时
- 令牌在
accessToken字段中返回。 - 令牌过期时间在
expiryTimeUtc字段中返回。 - 令牌刷新时间在
refreshAfterTimeUtc字段中返回。
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
export REFRESH_AFTER_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query refreshAfterTimeUtc)
当终结点的 auth_mode 为 aad_token 时
- 令牌在
accessToken字段中返回。 - 令牌过期时间在
expiryTimeUtc字段中返回。
export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
获取 Entra 令牌后，可通过 jwt.ms 解码令牌来验证令牌是否适用于正确的 Azure 资源终结点 studio.ml.azure.cn 和正确的客户端 ID，这将返回包含以下信息的 json 响应：
{
"aud": "https://studio.ml.azure.cn",
"oid": "<your-object-id>"
}
可以将 az ml online-endpoint invoke 用于具有密钥或 Azure 机器学习令牌或 Microsoft Entra 令牌的终结点。 CLI 会自动处理密钥或令牌，因此无需显式传递它。
az ml online-endpoint invoke -n my-endpoint -r request.json
若要在终结点的诊断设置中启用流量日志记录，请按照如何启用/禁用日志中的步骤操作。
如果启用了诊断设置，可检查 AmlOnlineEndpointTrafficLogs 表来查看身份验证模式和用户标识。