Configurar a autenticação para recursos e fluxos de trabalho usando no SDK do Azure Machine Learning v1

2025-06-16

APLICA-SE A:Azure Machine Learning SDK v1 para Python

Importante

Este artigo fornece informações sobre como usar o SDK do Azure Machine Learning v1. O SDK v1 foi preterido a partir de 31 de março de 2025. O suporte para ele terminará em 30 de junho de 2026. Você pode instalar e usar o SDK v1 até essa data.

Recomendamos que você faça a transição para o SDK v2 antes de 30 de junho de 2026. Para obter mais informações sobre o SDK v2, consulte o que é a CLI do Azure Machine Learning e o SDK do Python v2? e a referência do SDK v2.

Saiba como configurar autenticação para seu espaço de trabalho do Azure Machine Learning. A autenticação no seu espaço de trabalho do Azure Machine Learning é baseada no Microsoft Entra ID para a maioria das coisas. Em geral, há quatro fluxos de trabalho de autenticação que podem ser usados ao se conectar ao espaço de trabalho:

Interativo: você usa sua conta no Microsoft Entra ID para autenticar diretamente ou para obter um token que é usado para autenticação. A autenticação interativa é usada durante a experimentação e o desenvolvimento iterativo. A autenticação interativa permite controlar o acesso a recursos (como um serviço Web) por usuário.
Entidade de serviço: você cria uma conta de entidade de serviço no Microsoft Entra ID e a usa para autenticar ou obter um token. Uma entidade de serviço é usada quando você precisa de um processo automatizado para autenticar o serviço sem a necessidade de interação do usuário. Por exemplo, um script de implantação e integração contínua que treina e testa um modelo toda vez que o código de treinamento é alterado.
Sessão da CLI do Azure: você usa uma sessão ativa da CLI do Azure para se autenticar. A autenticação da CLI do Azure é usada durante a experimentação e o desenvolvimento iterativo ou quando você precisa de um processo automatizado para se autenticar no serviço usando uma sessão pré-autenticada. Você pode entrar no Azure pela CLI do Azure em sua estação de trabalho local, sem armazenar credenciais no código Python ou solicitar que o usuário se autentique. Da mesma forma, você pode reutilizar os mesmos scripts como parte de pipelines de implantação e integração contínuas, autenticando a CLI do Azure com uma identidade de entidade de serviço.
Identidade gerenciada: Ao usar o SDK do Azure Machine Learning em uma máquina virtual do Azure, você pode usar uma identidade gerenciada para o Azure. Esse fluxo de trabalho permite que a VM se conecte ao espaço de trabalho usando a identidade gerenciada, sem armazenar credenciais no código Python ou solicitar que o usuário se autentique. Os cluster de cálculo e as instâncias de computação do Azure Machine Learning também podem ser configurados para usar uma identidade gerenciada para acessar o espaço de trabalho ao treinar modelos.

Independentemente do fluxo de trabalho de autenticação usado, o controle de acesso baseado em função do Azure (RBAC do Azure) é usado para delimitar o nível de acesso (autorização) permitido aos recursos. Por exemplo, um administrador ou processo de automação pode ter acesso para criar uma instância de computação, mas não usá-la, enquanto um cientista de dados pode usá-la, mas não excluí-la ou criá-la. Para obter mais informações, consulte Gerenciar acesso a um espaço de trabalho do Azure Machine Learning.

O Acesso Condicional do Microsoft Entra pode ser usado para controlar ou restringir ainda mais o acesso ao espaço de trabalho para cada fluxo de trabalho de autenticação. Por exemplo, um administrador pode permitir o acesso ao espaço de trabalho somente para dispositivos gerenciados.

Pré-requisitos

Criar um Workspace do Azure Machine Learning.
Configurar o ambiente de desenvolvimento para instalar o SDK do Azure Machine Learning ou usar uma instância de computação do Azure Machine Learning com o SDK já instalado.

Microsoft Entra ID

Todos os fluxos de trabalho de autenticação para seu espaço de trabalho dependem do Microsoft Entra ID. Se você quiser que os usuários se autentiquem usando contas individuais, eles devem ter contas no Microsoft Entra ID. Se você quiser usar entidades de serviço, elas devem existir em seu Microsoft Entra ID. As identidades gerenciadas também são um recurso do Microsoft Entra ID.

Para obter mais informações sobre o Microsoft Entra ID, confira O que é a autenticação do Microsoft Entra.

Depois de criar as contas do Microsoft Entra, confira Gerenciar o acesso ao Workspace do Azure Machine Learning para obter informações sobre como conceder a elas acesso ao workspace e a outras operações no Azure Machine Learning.

Configurar uma entidade de serviço

Para usar uma entidade de serviço (SP), você deve primeiro criar a SP. Em seguida, conceda-lhe acesso ao seu workspace. Como mencionado anteriormente, o controle de acesso baseado em função do Azure (RBAC do Azure) é usado para controlar o acesso, portanto, você também deve decidir qual acesso conceder à SP.

Importante

Ao usar um principal de serviço, conceda-lhe o acesso mínimo necessário para a tarefa que está sendo realizada. Por exemplo, você não concederia à entidade de serviço acesso como proprietário ou colaborador se ela for usada apenas para leitura do token de acesso em uma implantação Web.

O motivo para conceder o menor acesso é que uma entidade de serviço usa uma senha para autenticar e a senha pode ser armazenada como parte de um script de automação. Se a senha for vazada, ter o acesso mínimo necessário para uma tarefa específica minimizará o uso mal-intencionado do SP.

É importante girar segredos como a senha da entidade de serviço regularmente.

A maneira mais fácil de criar uma SP e conceder acesso ao seu espaço de trabalho é usando a CLI do Azure. Para criar uma entidade de serviço e conceder acesso ao seu espaço de trabalho, use as seguintes etapas:

Observação

Você precisa ser um administrador na assinatura para executar as etapas a seguir.

Autentique-se na assinatura do Azure:
```
az login
```
Se a CLI pode abrir seu navegador padrão, ela irá fazê-lo e carregará uma página de entrada. Caso contrário, você precisará abrir um navegador e seguir as instruções na linha de comando. As instruções envolvem a navegação e a https://aka.ms/devicelogin inserção de um código de autorização.

Se tiver várias assinaturas do Azure, você deve usar a assinatura que contém o az account set -s <subscription name or ID> comando para definir a assinatura. Para saber mais, confira Usar várias assinaturas do Azure.

Para outros métodos de autenticação, confira Entrar com a CLI do Azure.

Crie a entidade de serviço. No exemplo a seguir, uma SP chamada ml-auth é criada:

az ad sp create-for-rbac --json-auth --name ml-auth --role Contributor --scopes /subscriptions/<subscription id>

O parâmetro --json-auth está disponível nas versões da CLI do Azure >= 2.51.0. Versões anteriores a essa usam --sdk-auth.

A saída é um JSON semelhante ao seguinte. Anote os campos clientId, clientSecret e tenantId, pois você precisará deles para outras etapas neste artigo.

{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "subscriptionId": "your-sub-id",
    "tenantId": "your-tenant-id",
    "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
    "resourceManagerEndpointUrl": "https://management.azure.com",
    "activeDirectoryGraphResourceId": "https://graph.windows.net",
    "sqlManagementEndpointUrl": "https://management.core.windows.net:5555",
    "galleryEndpointUrl": "https://gallery.azure.com/",
    "managementEndpointUrl": "https://management.core.windows.net"
}

Recupere os detalhes da entidade de serviço usando o valor clientId retornado na etapa anterior:
```
az ad sp show --id your-client-id
```
O JSON a seguir é uma simplificação da saída do comando. Anote o campo objectId, pois você precisará do valor dele para a próxima etapa.
```
{
    "accountEnabled": "True",
    "addIns": [],
    "appDisplayName": "ml-auth",
    ...
    ...
    ...
    "objectId": "your-sp-object-id",
    "objectType": "ServicePrincipal"
}
```
Para conceder acesso ao espaço de trabalho e a outros recursos usados pelo Azure Machine Learning, use as informações nos seguintes artigos:
- Como atribuir funções e ações no Azure Machine Learning
- Como atribuir funções na CLI
Importante

O acesso do proprietário permite que a entidade de serviço faça praticamente qualquer operação em seu espaço de trabalho. Ele é usado neste documento para demonstrar como conceder acesso; em um ambiente de produção, a Microsoft recomenda conceder à entidade de serviço o acesso mínimo necessário para executar a função que você pretende. Para obter informações sobre como criar uma função personalizada com o acesso necessário para seu cenário, consulte Gerenciar o acesso ao espaço de trabalho do Azure Machine Learning.

Configurar uma identidade gerenciada

Importante

A identidade gerenciada só tem suporte ao usar o SDK do Azure Machine Learning de uma máquina virtual do Azure ou com um cluster de cálculo ou uma instância de computação do Azure Machine Learning.

Identidade gerenciada com uma VM

Habilite uma identidade gerenciada atribuída pelo sistema para recursos do Azure na VM.
No portal do Azure, selecione seu espaço de trabalho e selecione Controle de Acesso (IAM).
Selecione Adicionar, Adicionar Atribuição de Função para abrir a página Adicionar atribuição de função.
Atribua a função a seguir. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.

Configuração Valor

Função Selecione a função que você deseja atribuir.

Atribuir acesso a Identidade Gerenciada

Membros A identidade gerenciada que você criou anteriormente

Configuração	Valor
Função	Selecione a função que você deseja atribuir.
Atribuir acesso a	Identidade Gerenciada
Membros	A identidade gerenciada que você criou anteriormente

Identidade gerenciada com cluster de cálculo

Para obter mais informações, consulte Configurar a identidade gerenciada para cluster de cálculo.

Usar autenticação interativa

Importante

A autenticação interativa usa seu navegador e requer cookies (incluindo cookies de terceiros). Se você desabilitou cookies, poderá receber um erro como "não foi possível entrar". Esse erro também poderá ocorrer se você tiver habilitado a autenticação multifator do Microsoft Entra.

A maioria dos exemplos na documentação e nos exemplos usa a autenticação interativa. Por exemplo, ao usar o SDK, há duas chamadas de função que solicitam automaticamente um fluxo de autenticação baseado em interface do usuário:

Chamar a função from_config() emite o prompt.
```
from azureml.core import Workspace
ws = Workspace.from_config()
```
A função from_config() procura um arquivo JSON com as informações de conexão de seu workspace.

Ao usar o construtor Workspace para informar assinatura, grupo de recursos e espaço de trabalho, também será exibido um prompt para autenticação interativa.

ws = Workspace(subscription_id="your-sub-id",
              resource_group="your-resource-group-id",
              workspace_name="your-workspace-name"
              )

Dica

Se você tiver acesso a vários locatários, pode ser necessário importar a classe e definir explicitamente qual locatário deseja segmentar. Chamar o construtor para InteractiveLoginAuthentication também solicita que você faça login, semelhante aos exemplos anteriores.

from azureml.core.authentication import InteractiveLoginAuthentication
interactive_auth = InteractiveLoginAuthentication(tenant_id="your-tenant-id")

Quando você usa a CLI do Azure, o comando az login é usado para autenticar a sessão da CLI. Para obter mais informações, consulte Introdução à CLI do Azure.

Dica

Se você estiver usando o SDK de um ambiente em que se autenticou interativamente usando a CLI do Azure, poderá usar a AzureCliAuthentication classe para se autenticar no workspace usando as credenciais armazenadas em cache pela CLI:

from azureml.core.authentication import AzureCliAuthentication
cli_auth = AzureCliAuthentication()
ws = Workspace(subscription_id="your-sub-id",
               resource_group="your-resource-group-id",
               workspace_name="your-workspace-name",
               auth=cli_auth
               )

Usar a autenticação de entidade de serviço

Para se autenticar no seu espaço de trabalho do SDK, usando uma entidade de serviço, use o ServicePrincipalAuthentication Construtor de classe. Use os valores que você obteve ao criar o provedor de serviços como os parâmetros. O parâmetro tenant_id corresponde ao tenantId mencionado anteriormente, service_principal_id corresponde ao clientId e service_principal_password corresponde ao clientSecret.

from azureml.core.authentication import ServicePrincipalAuthentication

sp = ServicePrincipalAuthentication(tenant_id="your-tenant-id", # tenantID
                                    service_principal_id="your-client-id", # clientId
                                    service_principal_password="your-client-secret") # clientSecret

Agora, a variável sp contém um objeto de autenticação que você usa diretamente no SDK. Em geral, é uma boa ideia armazenar as IDs/segredos usados anteriormente em variáveis de ambiente, conforme mostrado no código a seguir. O armazenamento em variáveis de ambiente impede que as informações sejam verificadas acidentalmente em um repositório GitHub.

import os

sp = ServicePrincipalAuthentication(tenant_id=os.environ['AML_TENANT_ID'],
                                    service_principal_id=os.environ['AML_PRINCIPAL_ID'],
                                    service_principal_password=os.environ['AML_PRINCIPAL_PASS'])

Para fluxos de trabalho automatizados que são executados no Python e usam principalmente o SDK, você pode usar esse objeto no estado em que se encontra na maioria dos casos para autenticação. O código a seguir é autenticado em seu espaço de trabalho usando o objeto de autenticação criado.

from azureml.core import Workspace

ws = Workspace.get(name="ml-example",
                   auth=sp,
                   subscription_id="your-sub-id",
                   resource_group="your-rg-name")
ws.get_details()

Use a autenticação de identidade gerenciada

Para autenticar no espaço de trabalho de uma VM, cluster de cálculo ou instância de computação configurada com uma identidade gerenciada, use a classe MsiAuthentication. O exemplo a seguir demonstra como usar essa classe para autenticar em um espaço de trabalho:

from azureml.core.authentication import MsiAuthentication

msi_auth = MsiAuthentication()

ws = Workspace(subscription_id="your-sub-id",
                resource_group="your-resource-group-id",
                workspace_name="your-workspace-name",
                auth=msi_auth
                )

Usar o Acesso Condicional

Como administrador, você pode impor políticas de Acesso Condicional do Microsoft Entra para usuários que entram no espaço de trabalho. Por exemplo, é possível requerer a autenticação de dois fatores ou permitir a conexão somente de dispositivos gerenciados. Para usar o acesso condicional especificamente para espaços de trabalho do Azure Machine Learning, atribua a política de acesso condicional ao aplicativo chamado Azure Machine Learning. A ID do aplicativo é 0736f41a-0425-bdb5-1563eff02385.

Compartilhar via

Configurar a autenticação para recursos e fluxos de trabalho usando no SDK do Azure Machine Learning v1

Pré-requisitos

Microsoft Entra ID

Configurar uma entidade de serviço

Configurar uma identidade gerenciada

Identidade gerenciada com uma VM

Identidade gerenciada com cluster de cálculo

Usar autenticação interativa

Usar a autenticação de entidade de serviço

Use a autenticação de identidade gerenciada

Usar o Acesso Condicional

Próximas etapas

Comentários

Recursos adicionais