Share via

Autenticar clientes para endpoints online

  • Artigo

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Este artigo aborda como autenticar clientes para executar operações de plano de controle e plano de dados em pontos de extremidade online.

Uma operação de plano de controle controla um ponto de extremidade e o altera. As operações do plano de controle incluem operações de criação, leitura, atualização e exclusão (CRUD) em pontos de extremidade online e implantações online.

Uma operação de plano de dados usa dados para interagir com um ponto de extremidade online sem alterar o ponto de extremidade. Por exemplo, uma operação de plano de dados pode consistir em enviar uma solicitação de pontuação para um ponto de extremidade online e obter uma resposta.

Pré-requisitos

Antes de seguir as etapas neste artigo, verifique se você tem os seguintes pré-requisitos:

  • Uma área de trabalho do Azure Machine Learning. Se você não tiver um, use as etapas no artigo Guia de início rápido: criar recursos do espaço de trabalho para criar um.

  • A CLI do Azure e a ml extensão ou o SDK do Python do Azure Machine Learning v2:

    • Para instalar a CLI e a extensão do Azure, consulte Instalar, configurar e usar a CLI (v2).

      Importante

      Os exemplos de CLI neste artigo pressupõem que você esteja usando o shell Bash (ou compatível). Por exemplo, de um sistema Linux ou Subsistema Windows para Linux.

    • Para instalar o Python SDK v2, use o seguinte comando:

      pip install azure-ai-ml azure-identity

      Para atualizar uma instalação existente do SDK para a versão mais recente, use o seguinte comando:

      pip install --upgrade azure-ai-ml azure-identity

      Para obter mais informações, consulte Instalar o Python SDK v2 para Azure Machine Learning.

Preparar uma identidade de usuário

Você precisa de uma identidade de usuário para executar operações de plano de controle (ou seja, operações CRUD) e operações de plano de dados (ou seja, enviar solicitações de pontuação) no ponto de extremidade online. Você pode usar a mesma identidade de usuário ou identidades de usuário diferentes para o plano de controle e operações do plano de dados. Neste artigo, você usa a mesma identidade de usuário para operações do plano de controle e do plano de dados.

Para criar uma identidade de usuário em Microsoft Entra ID, consulte Configurar autenticação. Você precisará do ID de identidade mais tarde.

Atribuir permissões à identidade

Nesta seção, você atribui permissões à identidade de usuário que usa para interagir com o ponto de extremidade. Você começa usando uma função interna ou criando uma função personalizada. Depois disso, você atribui a função à sua identidade de usuário.

Usar uma função interna

A AzureML Data Scientistfunção interna pode ser usada para gerenciar e usar pontos de extremidade e implantações e usa curingas para incluir as seguintes ações RBAC do plano de controle:

  • 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

e para incluir a seguinte ação RBAC do plano de dados:

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

Opcionalmente, a Azure Machine Learning Workspace Connection Secrets Reader função interna pode ser usada para acessar segredos de conexões de espaço de trabalho e inclui as seguintes ações RBAC do plano de controle:

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

Se você usar essas funções internas, não será necessária nenhuma ação nesta etapa.

(Opcional) Criar uma função personalizada

Pode ignorar este passo se estiver a utilizar funções incorporadas ou outras funções personalizadas pré-criadas.

  1. Defina o escopo e as ações para funções personalizadas criando definições JSON das funções. Por exemplo, a definição de função a seguir permite que o usuário CRUD um ponto de extremidade online, em um espaço de trabalho especificado.

    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>"
    ]
}

    A definição de função a seguir permite que o usuário envie solicitações de pontuação para um ponto de extremidade online, em um espaço de trabalho especificado.

    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. Use as definições JSON para criar funções personalizadas:

    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>

    Nota

    Para criar funções personalizadas, você precisa de uma das três funções:

    • proprietário
    • Administrador de Acesso de Usuário
    • Uma função personalizada com Microsoft.Authorization/roleDefinitions/write permissão (para criar/atualizar/excluir funções personalizadas) e Microsoft.Authorization/roleDefinitions/read permissão (para exibir funções personalizadas).

    Para obter mais informações sobre como criar funções personalizadas, consulte Funções personalizadas do Azure.

  3. Verifique a definição de função:

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

Atribuir a função à identidade

  1. Se você estiver usando a AzureML Data Scientist função interna, use o código a seguir para atribuir a função à sua identidade de usuário.

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

  2. Opcionalmente, se você estiver usando a Azure Machine Learning Workspace Connection Secrets Reader função interna, use o código a seguir para atribuir a função à sua identidade de usuário.

    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. Se você estiver usando uma função personalizada, use o código a seguir para atribuir a função à sua identidade de usuário.

    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>

    Nota

    Para atribuir funções personalizadas à identidade do usuário, você precisa de uma das três funções:

    • proprietário
    • Administrador de Acesso de Usuário
    • Uma função personalizada que permite Microsoft.Authorization/roleAssignments/write permissão (para atribuir funções personalizadas) e Microsoft.Authorization/roleAssignments/read (para exibir atribuições de função).

    Para obter mais informações sobre as diferentes funções do Azure e suas permissões, consulte Funções do Azure e Atribuição de funções do Azure usando o Portal do Azure.

  4. Confirme a atribuição da função:

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

Obtenha o token Microsoft Entra para operações de plano de controle

Execute esta etapa se você planeja executar operações de plano de controle com a API REST, que usará diretamente o token.

Se você planeja usar outras maneiras, como a CLI do Azure Machine Learning (v2), o Python SDK (v2) ou o estúdio do Azure Machine Learning, não é necessário obter o token do Microsoft Entra manualmente. Em vez disso, durante o login, sua identidade de usuário já seria autenticada e o token seria automaticamente recuperado e passado para você.

Você pode recuperar o token do Microsoft Entra para operações do plano de controle do ponto de extremidade de recurso do Azure: https://management.azure.com.

  1. Inicie sessão no Azure.

    az login

  2. Se você quiser usar uma identidade específica, use o seguinte código para entrar com a identidade:

    az login --identity --username <identityId>

  3. Use este contexto para obter o token.

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

(Opcional) Verifique o ponto de extremidade do recurso e a ID do cliente para o token do Microsoft Entra

Depois de recuperar o token do Microsoft Entra, você pode verificar se o token é para o ponto de extremidade management.azure.com de recurso do Azure correto e a ID do cliente correta decodificando o token via jwt.ms, que retornará uma resposta json com as seguintes informações:

{
    "aud": "https://management.azure.com",
    "oid": "<your-object-id>"
}

Criar um ponto final

O exemplo a seguir cria o ponto de extremidade com uma identidade atribuída pelo sistema (SAI) como a identidade do ponto de extremidade. O SAI é o tipo de identidade padrão da identidade gerenciada para pontos de extremidade. Algumas funções básicas são atribuídas automaticamente para o SAI. Para obter mais informações sobre a atribuição de função para uma identidade atribuída pelo sistema, consulte Atribuição automática de função para identidade de ponto de extremidade.

A CLI não exige que você forneça explicitamente o token do plano de controle. Em vez disso, a CLI az login autentica você durante o login, e o token é automaticamente recuperado e passado para você.

  1. Crie um arquivo YAML de definição de ponto final.

    endpoint.yml:

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

  2. Você pode substituir auth_mode por key for key auth ou aml_token por Azure Machine Learning token auth. Neste exemplo, você usa aad_token para Microsoft Entra token auth.

    az ml online-endpoint create -f endpoint.yml

  3. Verifique o status do endpoint:

    az ml online-endpoint show -n my-endpoint

  4. Se você quiser substituir auth_mode (por exemplo, para aad_token) ao criar um ponto de extremidade, execute o seguinte código:

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

  5. Se desejar atualizar o ponto de extremidade existente e especificar auth_mode (por exemplo, para aad_token), execute o seguinte código:

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

Criar uma implantação

Para criar uma implantação, consulte Implantar um modelo de ML com um ponto de extremidade online ou Usar REST para implantar um modelo como um ponto de extremidade online. Não há diferença na forma como você cria implantações para diferentes modos de autenticação.

O código a seguir é um exemplo de como criar uma implantação. Para obter mais informações sobre como implantar pontos de extremidade online, consulte Implantar um modelo de ML com um ponto de extremidade online (via CLI)

  1. Crie um arquivo YAML de definição de implantação.

    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. Crie a implantação usando o arquivo YAML. Para este exemplo, defina todo o tráfego para a nova implantação.

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

Obter o URI de pontuação para o ponto de extremidade

Se você planeja usar a CLI para invocar o ponto de extremidade, não é necessário obter o URI de pontuação explicitamente, pois a CLI o manipula para você. No entanto, você ainda pode usar a CLI para obter o URI de pontuação para que possa usá-lo com outros canais, como a API REST.

scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")

Obter a chave ou token para operações de plano de dados

Uma chave ou token pode ser usado para operações de plano de dados, mesmo que o processo de obtenção da chave ou token seja uma operação de plano de controle. Em outras palavras, você usa um token de plano de controle para obter a chave ou token que você usa posteriormente para executar suas operações de plano de dados.

Obter a chave ou o token do Azure Machine Learning requer que a função correta seja atribuída à identidade do usuário que a está solicitando, conforme descrito em autorização para operações de plano de controle. Obter o token do Microsoft Entra não requer nenhuma função extra para a identidade do usuário.

Se você planeja usar a CLI para invocar o ponto de extremidade, não é necessário obter as chaves ou o token para operações de plano de dados explicitamente, pois a CLI lida com isso para você. No entanto, você ainda pode usar a CLI para obter as chaves ou o token para a operação do plano de dados para que possa usá-lo com outros canais, como a API REST.

Para obter as chaves ou o token para operações de plano de dados, use o comando az ml online-endpoint get-credentials . Este comando retorna uma saída JSON que contém as chaves, o token e/ou informações adicionais.

Gorjeta

Para extrair uma informação específica da saída JSON, o --query parâmetro do comando CLI é usado como exemplo. No entanto, você pode usar qualquer ferramenta adequada para este fim.

Quando auth_mode do parâmetro de avaliação final é key

  • As chaves são retornadas nos primaryKey campos e 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)

Quando auth_mode do parâmetro de avaliação final é aml_token

  • O token é retornado no accessToken campo.
  • O tempo de expiração do token é retornado no expiryTimeUtc campo.
  • O tempo de atualização do token é retornado no refreshAfterTimeUtc campo.
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)

Quando auth_mode do parâmetro de avaliação final é aad_token

  • O token é retornado no accessToken campo.
  • O tempo de expiração do token é retornado no expiryTimeUtc campo.
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)

Verifique o ponto de extremidade do recurso e a ID do cliente para o token do Microsoft Entra

Depois de obter o token Entra, você pode verificar se o token é para o ponto de extremidade ml.azure.com de recurso do Azure correto e a ID do cliente correta decodificando o token por meio de jwt.ms, que retornará uma resposta json com as seguintes informações:

{
    "aud": "https://ml.azure.com",
    "oid": "<your-object-id>"
}

Pontuar dados usando a chave ou token

Você pode usar az ml online-endpoint invoke para pontos de extremidade com uma chave, um token do Azure Machine Learning ou um token do Microsoft Entra. A CLI manipula a chave ou token automaticamente para que você não precise passá-la explicitamente.

az ml online-endpoint invoke -n my-endpoint -r request.json

Registre e monitore o tráfego

Para habilitar o log de tráfego nas configurações de diagnóstico para o ponto de extremidade, siga as etapas em Como habilitar/desabilitar logs.

Se a configuração de diagnóstico estiver ativada, você poderá verificar a tabela para ver o AmlOnlineEndpointTrafficLogs modo de autenticação e a identidade do usuário.

Conteúdos relacionados