Autorização em pontos finais de lote

Artigo
09/01/2024

Os pontos de extremidade em lote suportam a autenticação Microsoft Entra ou aad_token. Isto significa que, para invocar um ponto final em lote, o utilizador deve apresentar um token de autenticação válido do Microsoft Entra para o URI do ponto final em lote. A autorização é imposta no nível do ponto de extremidade. O artigo a seguir explica como interagir corretamente com pontos de extremidade em lote e os requisitos de segurança para ele.

Como funciona a autorização

Para invocar um ponto de extremidade em lote, o usuário deve apresentar um token válido do Microsoft Entra representando uma entidade de segurança. Essa entidade de segurança pode ser uma entidade de usuário ou uma entidade de serviço. Em qualquer caso, depois que um ponto de extremidade é invocado, um trabalho de implantação em lote é criado sob a identidade associada ao token. A identidade precisa das seguintes permissões para criar um trabalho com êxito:

Leia endpoints/implantações em lote.
Crie trabalhos em pontos de extremidade/implantação de inferência em lote.
Crie experiências/execuções.
Ler e gravar de/para armazenamentos de dados.
Lista segredos do armazenamento de dados.

Consulte Configurar RBAC para invocar ponto de extremidade em lote para obter uma lista detalhada das permissões RBAC.

Importante

A identidade usada para invocar um ponto de extremidade em lote não pode ser usada para ler os dados subjacentes, dependendo de como o armazenamento de dados está configurado. Consulte Configurar clusters de computação para acesso a dados para obter mais detalhes.

Como executar trabalhos usando diferentes tipos de credenciais

Os exemplos a seguir mostram diferentes maneiras de iniciar trabalhos de implantação em lote usando diferentes tipos de credenciais:

Importante

Ao trabalhar em espaços de trabalho habilitados para link privado, os pontos de extremidade em lote não podem ser invocados da interface do usuário no estúdio do Azure Machine Learning. Em vez disso, use a CLI v2 do Azure Machine Learning para a criação de trabalhos.

Pré-requisitos

Este exemplo pressupõe que você tenha um modelo implantado corretamente como um ponto de extremidade em lote. Particularmente, estamos usando o classificador de condição cardíaca criado no tutorial Usando modelos MLflow em implantações em lote.

Executando trabalhos usando as credenciais do usuário

Nesse caso, queremos executar um ponto de extremidade em lote usando a identidade do usuário conectado no momento. Siga estes passos:

Use a CLI do Azure para fazer logon usando autenticação interativa ou de código de dispositivo:
```
az login
```

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci

Use o SDK do Azure Machine Learning para Python para fazer logon usando autenticação interativa ou de dispositivo:

from azure.ai.ml import MLClient
from azure.identity import InteractiveAzureCredentials

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(InteractiveAzureCredentials(), subscription_id, resource_group, workspace)

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

Ao trabalhar com REST, recomendamos invocar pontos de extremidade em lote usando uma entidade de serviço. No entanto, se você quiser testar uma implantação específica usando REST com suas próprias credenciais, poderá fazê-lo gerando um token Microsoft Entra para sua conta. Siga estes passos:

A maneira mais simples de obter um token válido para sua conta de usuário é usar a CLI do Azure. Em um console, execute o seguinte comando:

az account get-access-token --resource https://ml.azure.com \
                            --query "accessToken" \
                            --output tsv

Anote a saída gerada.

Uma vez autenticado, faça uma solicitação para o URI de invocação substituindo <TOKEN> pelo que você obteve antes.

Pedido:

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

Corpo:

{
    "properties": {
        "InputData": {
            "mnistinput": {
                "JobInputType" : "UriFolder",
                "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
            }
        }
    }
}

Executando trabalhos usando uma entidade de serviço

Nesse caso, queremos executar um ponto de extremidade em lote usando uma entidade de serviço já criada no Microsoft Entra ID. Para concluir a autenticação, você terá que criar um segredo para executar a autenticação. Siga estes passos:

Crie um segredo para usar na autenticação, conforme explicado na Opção 3: Criar um novo segredo do cliente.
Para autenticar usando uma entidade de serviço, use o seguinte comando. Para obter mais detalhes, consulte Entrar com a CLI do Azure.
```
az login --service-principal \
         --tenant <tenant> \
         -u <app-id> \
         -p <password-or-cert> 
```

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/

Crie um segredo para usar na autenticação, conforme explicado na Opção 3: Criar um novo segredo do cliente.

Para autenticar usando uma entidade de serviço, indique a ID do locatário, a ID do cliente e o segredo do cliente da entidade de serviço usando variáveis de ambiente, conforme demonstrado:

from azure.ai.ml import MLClient
from azure.identity import EnvironmentCredential

os.environ["AZURE_TENANT_ID"] = "<TENANT_ID>"
os.environ["AZURE_CLIENT_ID"] = "<CLIENT_ID>"
os.environ["AZURE_CLIENT_SECRET"] = "<CLIENT_SECRET>"

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(EnvironmentCredential(), subscription_id, resource_group, workspace)

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

Crie um segredo para usar na autenticação, conforme explicado na Opção 3: Criar um novo segredo do cliente.
Use o serviço de logon do Azure para obter um token de autorização. Os tokens de autorização são emitidos para um escopo específico. O tipo de recurso para o Azure Machine Learning é https://ml.azure.com. O pedido teria a seguinte aparência:

Pedido:
```
POST /{TENANT_ID}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
```
Corpo:
```
grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&resource=https://ml.azure.com
```
Importante

Observe que o escopo do recurso para invocar um ponto de extremidade em lote (https://ml.azure.com) é diferente do escopo do recurso usado para gerenciá-los. Todas as APIs de gerenciamento no Azure usam o escopo https://management.azure.comdo recurso, incluindo o Azure Machine Learning.

Depois de autenticado, use a consulta para executar um trabalho de implantação em lote:

Pedido:

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

Corpo:

{
    "properties": {
        "InputData": {
            "mnistinput": {
                "JobInputType" : "UriFolder",
                "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
            }
        }
    }
}

Executando trabalhos usando uma identidade gerenciada

Você pode usar identidades gerenciadas para invocar pontos de extremidade e implantações em lote. Observe que essa identidade de gerenciamento não pertence ao ponto de extremidade em lote, mas é a identidade usada para executar o ponto de extremidade e, portanto, criar um trabalho em lote. As identidades atribuídas pelo usuário e pelo sistema podem ser usadas nesse cenário.

Nos recursos configurados para identidades geridas para recursos do Azure, pode iniciar sessão com a identidade gerida. O início de sessão com a identidade do recurso é feito com o sinalizador --identity. Para obter mais detalhes, consulte Entrar com a CLI do Azure.

az login --identity

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci

Nos recursos configurados para identidades geridas para recursos do Azure, pode iniciar sessão com a identidade gerida. Use o ID do recurso junto com o objeto, ManagedIdentityCredential conforme demonstrado no exemplo a seguir:

from azure.ai.ml import MLClient
from azure.identity import ManagedIdentityCredential

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"
resource_id = "<resource-id>"

ml_client = MLClient(ManagedIdentityCredential(resource_id), subscription_id, resource_group, workspace)

Uma vez autenticado, use o seguinte comando para executar um trabalho de implantação em lote:

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

Configurar RBAC para invocar pontos de extremidade em lote

Os pontos de extremidade em lote expõem uma API durável que os consumidores podem usar para gerar trabalhos. O invocador solicita a permissão adequada para poder gerar esses trabalhos. Você pode usar uma das funções de segurança internas ou criar uma função personalizada para as finalidades.

Para invocar com êxito um ponto de extremidade em lote, você precisa das seguintes ações explícitas concedidas à identidade usada para invocar os pontos de extremidade. Consulte Etapas para atribuir uma função do Azure para obter instruções sobre como atribuí-las.

"actions": [
    "Microsoft.MachineLearningServices/workspaces/read",
    "Microsoft.MachineLearningServices/workspaces/data/versions/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/read",
    "Microsoft.MachineLearningServices/workspaces/datastores/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/listsecrets/action",
    "Microsoft.MachineLearningServices/workspaces/listStorageAccountKeys/action",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/computes/read",
    "Microsoft.MachineLearningServices/workspaces/computes/listKeys/action",
    "Microsoft.MachineLearningServices/workspaces/metadata/secrets/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/snapshots/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/write",
    "Microsoft.MachineLearningServices/workspaces/experiments/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/submit/action",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/write",
    "Microsoft.MachineLearningServices/workspaces/metrics/resource/write",
    "Microsoft.MachineLearningServices/workspaces/modules/read",
    "Microsoft.MachineLearningServices/workspaces/models/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/write",
    "Microsoft.MachineLearningServices/workspaces/environments/read",
    "Microsoft.MachineLearningServices/workspaces/environments/write",
    "Microsoft.MachineLearningServices/workspaces/environments/build/action",
    "Microsoft.MachineLearningServices/workspaces/environments/readSecrets/action"
]

Configurar clusters de computação para acesso a dados

Os pontos de extremidade em lote garantem que apenas usuários autorizados possam invocar implantações em lote e gerar trabalhos. No entanto, dependendo de como os dados de entrada são configurados, outras credenciais podem ser usadas para ler os dados subjacentes. Use a tabela a seguir para entender quais credenciais são usadas:

Tipo de entrada de dados	Credencial na loja	Credenciais utilizadas	Acesso concedido por
Arquivo de dados	Sim	Credenciais do armazenamento de dados no espaço de trabalho	Chave de acesso ou SAS
Ativo de dados	Sim	Credenciais do armazenamento de dados no espaço de trabalho	Chave de acesso ou SAS
Arquivo de dados	Não	Identidade do trabalho + Identidade gerenciada do cluster de computação	RBAC
Ativo de dados	Não	Identidade do trabalho + Identidade gerenciada do cluster de computação	RBAC
Armazenamento de Blobs do Azure	Não se aplica	Identidade do trabalho + Identidade gerenciada do cluster de computação	RBAC
Armazenamento do Azure Data Lake Ger1	Não se aplica	Identidade do trabalho + Identidade gerenciada do cluster de computação	POSIX
Azure Data Lake Storage Gen2	Não se aplica	Identidade do trabalho + Identidade gerenciada do cluster de computação	POSIX e RBAC

Para os itens na tabela em que Identidade do trabalho + Identidade gerenciada do cluster de computação é exibida, a identidade gerenciada do cluster de computação é usada para montar e configurar contas de armazenamento. No entanto, a identidade do trabalho ainda é usada para ler os dados subjacentes, permitindo que você obtenha controle de acesso granular. Isso significa que, para ler com êxito os dados do armazenamento, a identidade gerenciada do cluster de computação em que a implantação está sendo executada deve ter pelo menos acesso do Storage Blob Data Reader à conta de armazenamento.

Para configurar o cluster de computação para acesso a dados, siga estas etapas:

Vá para o estúdio do Azure Machine Learning.
Navegue até Computação e, em seguida , Agrupamentos de computação e selecione o cluster de computação que sua implantação está usando.
Atribua uma identidade gerenciada ao cluster de computação:
1. Na seção Identidade gerenciada, verifique se a computação tem uma identidade gerenciada atribuída. Caso contrário, selecione a opção Editar.
2. Selecione Atribuir uma identidade gerenciada e configure-a conforme necessário. Você pode usar uma Identidade Gerenciada Atribuída pelo Sistema ou uma Identidade Gerenciada Atribuída pelo Usuário. Se estiver usando uma Identidade Gerenciada Atribuída pelo Sistema, ela será nomeada como "[nome do espaço de trabalho]/computes/[nome do cluster de computação]".
3. Guarde as alterações.
Vá para o portal do Azure e navegue até a conta de armazenamento associada onde os dados estão localizados. Se a entrada de dados for um Ativo de Dados ou um Armazenamento de Dados, procure a conta de armazenamento onde esses ativos estão colocados.
Atribua o nível de acesso do Leitor de Dados de Blob de Armazenamento na conta de armazenamento:
1. Vá para a seção Controle de acesso (IAM).
2. Selecione a guia Atribuição de função e clique em Adicionar>atribuição de função.
3. Procure a função chamada Storage Blob Data Reader, selecione-a e clique em Next.
4. Clique em Selecionar membros.
5. Procure a identidade gerenciada que você criou. Se estiver usando uma Identidade Gerenciada Atribuída pelo Sistema, ela será nomeada como "[nome do espaço de trabalho]/computes/[nome do cluster de computação]".
6. Adicione a conta e conclua o assistente.
Seu endpoint está pronto para receber trabalhos e dados de entrada da conta de armazenamento selecionada.

Partilhar via

Autorização em pontos finais de lote

Como funciona a autorização

Como executar trabalhos usando diferentes tipos de credenciais

Pré-requisitos

Executando trabalhos usando as credenciais do usuário

Executando trabalhos usando uma entidade de serviço

Executando trabalhos usando uma identidade gerenciada

Configurar RBAC para invocar pontos de extremidade em lote

Configurar clusters de computação para acesso a dados

Próximos passos

Comentários

Recursos adicionais