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:

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 função integrada do AzureML Data Scientist pode ser usada para gerenciar e usar pontos de extremidade e implantações e usa caracteres curinga para incluir as seguintes ações de 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 az login autentica você durante a entrada 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. Obter o token Microsoft Entra não requer funções extras para a identidade do usuário.

Se você planeja usar a CLI para invocar o ponto de extremidade, não será necessário obter as chaves ou o token para operações de plano de dados explicitamente, pois a CLI o manipula 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 você 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. Esse comando retorna uma saída JSON que contém as chaves, o token e/ou informações adicionais.

Dica

Para extrair informações específicas da saída JSON, o parâmetro --query do comando da CLI é usado como exemplo. No entanto, você pode usar qualquer ferramenta adequada para esse propósito.

Quando auth_mode do ponto de extremidade é key

  • As chaves são retornadas nos campos primaryKey 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 ponto de extremidade é aml_token

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

Quando auth_mode do ponto de extremidade é aad_token

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

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

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 o token automaticamente para que você não precise passá-la explicitamente.

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

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