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.

Limitações

Os pontos de extremidade com o modo de autenticação do token (aad_token) do Microsoft Entra não oferecem suporte à pontuação usando a CLI az ml online-endpoint invoke, SDK ml_client.online_endpoints.invoke()ou as guias Testar ou Consumir do estúdio do Azure Machine Learning. Em vez disso, use um SDK Python genérico ou use a API REST para passar o token do plano de controle. Para obter mais informações, consulte Dados de pontuação usando a chave ou o token.

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 função interna, use o código a seguir para atribuir a AzureML Data Scientist 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 função interna, use o código a seguir para atribuir a Azure Machine Learning Workspace Connection Secrets Reader 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 de management.azure.com 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 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.

    parâmetro de avaliação.yml:

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

  2. Você pode substituir auth_mode por for key auth ou aml_token por key 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. A identidade do usuário não precisa de nenhuma função extra para obter o token do Microsoft Entra.

Chave ou token do Azure Machine Learning

Se você planeja usar a CLI para invocar o ponto de extremidade e se o ponto de extremidade estiver configurado para usar um modo de autenticação de chave ou token do Azure Machine Learning (aml_token), não será necessário obter o token do plano de dados explicitamente, pois a CLI o manipula para você. No entanto, você ainda pode usar a CLI para obter o token do plano de dados para que possa usá-lo com outros canais, como a API REST.

Para obter a chave ou o token do Azure Machine Learning (aml_token), use o comando az ml online-endpoint get-credentials . Este comando retorna um documento JSON que contém a chave ou o token do Azure Machine Learning.

As chaves são retornadas nos primaryKey campos e secondaryKey . O exemplo a seguir mostra como usar o --query parâmetro para retornar somente a chave primária:

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)

Os Tokens do Azure Machine Learning são retornados no accessToken campo:

export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)

Além disso, os campos e contêm os expiryTimeUtc tempos de expiração e refreshAfterTimeUtc atualização do token.

Token Microsoft Entra

Para obter o token Microsoft Entra (aad_token) usando a CLI, use o comando az account get-access-token . Este comando retorna um documento JSON que contém o token Microsoft Entra.

O token Microsoft Entra é retornado no accessToken campo:

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

Nota

  • A extensão CLI ml não suporta a obtenção do token Microsoft Entra. Use az account get-access-token em vez disso, conforme descrito no código anterior.
  • O token para operações de plano de dados é recuperado do ponto de extremidade ml.azure.com de recurso do Azure em vez de , ao contrário do token para operações de plano de management.azure.comcontrole.

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 de recurso do Azure correto e a ID do cliente correta decodificando o token por meio de ml.azure.com 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

Chave ou token do Azure Machine Learning

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

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

Token Microsoft Entra

Não há suporte para o uso az ml online-endpoint invoke de pontos de extremidade com um token Microsoft Entra. Use a API REST em vez disso e use o URI de pontuação do ponto de extremidade para invocar o ponto de extremidade.

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 modo de autenticação e a AmlOnlineEndpointTrafficLogs identidade do usuário.

Conteúdos relacionados