Autenticar clientes para pontos de extremidade online

  • Artigo

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

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

Uma operação de painel de controle controla um ponto de extremidade e o altera. As operações de painel 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 no envio de uma solicitação de pontuação para um ponto de extremidade online e na obtenção de uma resposta.

Pré-requisitos

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

Limitações

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

Preparar uma identidade de usuário

Você precisa de uma identidade de usuário para executar operações do painel 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. É possível usar a mesma identidade de usuário ou identidades de usuário diferentes para as operações de painel de controle e de plano de dados. Neste artigo, você usa a mesma identidade de usuário para ambas as operações de painel de controle e de plano de dados.

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

Atribuir permissão à identidade

Nesta seção, você atribui permissões à identidade do usuário que você 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 de RBAC de plano de dados:

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

Opcionalmente, a função interna Azure Machine Learning Workspace Connection Secrets Reader pode ser usada para acessar segredos de conexões de workspace 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 haverá nenhuma ação necessária nesta etapa.

(Opcional) Criar uma função personalizada

Você pode ignorar esta etapa se estiver usando funções internas ou outras funções personalizadas predefinidas.

  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 realize uma operação CRUD em um ponto de extremidade online em um workspace 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 workspace 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. Usar as definições de 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>

    Observação

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

    • owner
    • administrador de acesso do usuário
    • uma função personalizada com permissão Microsoft.Authorization/roleDefinitions/write (para criar/atualizar/excluir funções personalizadas) e permissão Microsoft.Authorization/roleDefinitions/read (para visualizar 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 '"')`

Atribua a função á identidade

  1. Se estiver usando a função interna AzureML Data Scientist, 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 função interna Azure Machine Learning Workspace Connection Secrets Reader, 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 estiver usando a 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>

    Observação

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

    • owner
    • administrador de acesso do usuário
    • uma função personalizada que permite a permissão Microsoft.Authorization/roleAssignments/write (para atribuir funções personalizadas) e a Microsoft.Authorization/roleAssignments/read (para visualizar atribuições de funções).

    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. Confirmar a atribuição de função:

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

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

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

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

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

  1. Faça login no Azure.

    az login

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

    az login --identity --username <identityId>

  3. Use esse contexto para obter o token.

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

(Opcional) Verificar o ponto de extremidade de 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 se refere ao ponto de extremidade de recurso management.azure.com do Azure correto e para 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://management.azure.com",
    "oid": "<your-object-id>"
}

Criar um ponto de extremidade

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 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 a identidade do ponto de extremidade.

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

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

    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 para autenticação de chave, ou aml_token para autenticação de token do Azure Machine Learning. Neste exemplo, você usa aad_token para autenticação de token do Microsoft Entra.

    az ml online-endpoint create -f endpoint.yml

  3. Verifique o status do ponto de extremidade:

    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 você quiser 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 a implantação de pontos de extremidade online, consulte Implantar um modelo de ML com ponto de extremidade online (via CLI)

  1. Criar 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. Criar 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 chamar o ponto de extremidade, não é necessário obter o URI de pontuação explicitamente, pois a CLI cuida disso para você. No entanto, você ainda pode usar a CLI para obter o URI de pontuação de modo 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 o 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 painel de controle. Em outras palavras, você usa um token do painel de controle para obter a chave ou o token usado posteriormente para executar as operações do 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 do painel de controle. A identidade do usuário não precisa de funções extras para obter o token do Microsoft Entra.

Chave ou token do Azure Machine Learning

Se você planeja usar a CLI para chamar 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), você não precisará obter o token do plano de dados explicitamente, pois a CLI cuida disso para você. No entanto, você ainda pode usar a CLI para obter o URI de pontuação de modo 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. Esse comando retorna um documento JSON que contém a chave ou o token do Azure Machine Learning.

As Chaves são retornadas nos campos primaryKey e secondaryKey. O exemplo a seguir mostra como usar o parâmetro --query para retornar apenas 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 campo accessToken:

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 expiryTimeUtc e refreshAfterTimeUtc contêm os tempos de expiração e atualização do token.

Microsoft Entra token

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

O token do Microsoft Entra é retornado no campo accessToken:

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

Observação

  • A extensão ml da CLI não dá suporte à obtenção do token do 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 de recurso do Azure ml.azure.com em vez de management.azure.com, diferentemente do token para operações do painel de controle.

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

Depois de obter o token do Microsoft Entra, você pode verificar se o token se refere ao ponto de extremidade de recurso do Azure ml.azure.com correto e a ID do cliente correta, decodificando o token por meio de jwt.ms, que retornará uma resposta json com a seguinte informação:

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

Pontuar dados usando a chave ou o 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 lida com 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

Microsoft Entra token

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

Registrar e monitorar tráfego

Para habilitar o registro de tráfego nas configurações de diagnósticos do ponto de extremidade, siga as etapas em Como habilitar /desabilitar registros.

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

Conteúdo relacionado