Compartir a través de

对联机终结点的客户端进行身份验证

  • Artículo

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

本文介绍如何对客户端进行身份验证，以便在联机终结点上执行控制平面和数据平面操作。

控制平面操作可控制终结点并对其进行更改。 控制平面操作包括在联机终结点和联机部署上进行的创建、读取、更新和删除 (CRUD) 操作。

数据平面操作使用数据与联机终结点交互，而无需更改终结点。 例如，数据平面操作可能包括向联机终结点发送评分请求并获取响应。

先决条件

在按照本文中的步骤操作之前，请确保满足以下先决条件：

准备用户标识

需要用户标识才能在联机终结点上执行控制平面操作（即 CRUD 操作）和数据平面操作（即发送评分请求）。 可以对控制平面操作和数据平面操作使用相同的用户标识，也可使用不同的用户标识。 在本文中，你将对控制平面和数据平面操作使用相同的用户标识。

若要在 Microsoft Entra ID 下创建用户标识，请参阅设置身份验证。 稍后需要标识 ID。

向标识分配权限

在本部分中，将为用于与终结点交互的用户标识分配权限。 首先使用内置角色或创建自定义角色。 然后，将角色分配给用户标识。

使用内置角色

AzureML Data Scientist 内置角色可用于管理和使用终结点及部署，并使用通配符来包括以下控制平面 RBAC 操作：

  • 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

并包括以下数据平面 RBAC 操作：

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action

（可选）Azure Machine Learning Workspace Connection Secrets Reader 内置角色可用于从工作区连接访问机密，并纳入以下控制平面 RBAC 操作：

  • Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
  • Microsoft.MachineLearningServices/workspaces/metadata/secrets/read

如果使用这些内置角色，此步骤不需要执行任何操作。

（可选）创建自定义角色

如果使用内置角色或其他预制自定义角色，可以跳过此步骤。

  1. 通过创建角色的 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>"
    ]
}

  2. 使用 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 自定义角色。

  3. 验证角色定义：

    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 '"')`

将角色分配给标识

  1. 如果使用 AzureML Data Scientist 内置角色，请使用以下代码将角色分配给用户标识。

    az role assignment create --assignee <identityId> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

  2. （可选）如果使用 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>

  3. 如果使用自定义角色，请使用以下代码将角色分配给用户标识。

    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 角色。

  4. 确认角色分配：

    az role assignment list --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

获取用于控制平面操作的 Microsoft Entra 令牌

如果计划使用 REST API 执行控制平面操作，请执行此步骤，这将直接使用该令牌。

如果计划使用其他方法，例如 Azure 机器学习 CLI (v2)、Python SDK (v2) 或 Azure 机器学习工作室，则无需手动获取 Microsoft Entra 令牌。 相反，在登录期间，用户标识已经过身份验证，系统会自动检索和传递令牌。

可以从 Azure 资源终结点检索用于控制平面操作的 Microsoft Entra 令牌：https://management.chinacloudapi.cn。

  1. 登录 Azure。

    az login

  2. 如果要使用特定标识，请通过以下代码使用标识进行登录：

    az login --identity --username <identityId>

  3. 使用此上下文获取令牌。

    export CONTROL_PLANE_TOKEN=`(az account get-access-token --resource https://management.chinacloudapi.cn --query accessToken | tr -d '"')`

（可选）验证 Microsoft Entra 令牌的资源终结点和客户端 ID

检索 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 会在登录期间对你进行身份验证，系统会自动检索和传递令牌。

  1. 创建终结点定义 YAML 文件。

    endpoint.yml：

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: aad_token

  2. 可以将 auth_mode 替换为 key 来进行密钥身份验证，或者替换为 aml_token 来进行 Azure 机器学习令牌身份验证。在此示例中，使用 aad_token 来进行 Microsoft Entra 令牌身份验证。

    az ml online-endpoint create -f endpoint.yml

  3. 检查终结点的状态：

    az ml online-endpoint show -n my-endpoint

  4. 如果要在创建终结点时替代 auth_mode（例如，替代为 aad_token），请运行以下代码：

    az ml online-endpoint create -n my-endpoint --auth_mode aad_token

  5. 如果要更新现有终结点并指定 auth_mode（例如，指定为 aad_token），请运行以下代码：

    az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token

创建部署

若要创建部署，请参阅使用联机终结点部署 ML 模型或使用 REST 将模型部署为联机终结点。 为不同的身份验证模式创建部署的方式没有区别。

以下代码是关于如何创建部署的示例。 若要详细了解如何部署联机终结点，请参阅使用联机终结点部署 ML 模型（通过 CLI）

  1. 创建部署定义 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

  2. 使用 YAML 文件创建部署。 对于此示例，请将所有流量设置为新部署。

    az ml online-deployment create -f blue-deployment.yml --all-traffic

获取终结点的评分 URI

如果计划使用 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)

验证 Microsoft Entra 令牌的资源终结点和客户端 ID

获取 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 表来查看身份验证模式和用户标识。

相关内容