Biblioteca de clientes da Identidade do Azure para Python – versão 1.14.1

  • Artigo

A biblioteca de identidade do Azure fornece suporte à autenticação de token do Azure Active Directory (Azure AD) no SDK do Azure. Ele fornece um conjunto de TokenCredential implementações, que podem ser usadas para construir clientes do SDK do Azure que dão suporte à autenticação de token Azure AD.

Código-fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIdocumentação do Azure AD

Introdução

Instalar o pacote

Instale o Azure Identity com pip:

pip install azure-identity

Pré-requisitos

  • Uma assinatura do Azure
  • Python 3.7 ou uma versão recente do Python 3 (essa biblioteca não dá suporte a versões de fim de vida útil)

Autenticar durante o desenvolvimento local

Ao depurar e executar o código localmente, é comum que os desenvolvedores usem suas próprias contas para autenticar chamadas aos serviços do Azure. A biblioteca de Identidade do Azure dá suporte à autenticação por meio de ferramentas de desenvolvedor para simplificar o desenvolvimento local.

Autenticar por meio de Visual Studio Code

Os desenvolvedores que usam Visual Studio Code podem usar a extensão conta do Azure para autenticar por meio do editor. Os aplicativos que usam DefaultAzureCredential ou VisualStudioCodeCredential podem usar essa conta para autenticar chamadas em seu aplicativo ao serem executados localmente.

Para autenticar em Visual Studio Code, verifique se a extensão conta do Azure está instalada. Depois de instalado, abra a Paleta de Comandos e execute o comando Azure: Entrar .

É um problema conhecido que VisualStudioCodeCredential não funciona com versões de extensão da Conta do Azure mais recentes do que 0.9.11. Uma correção de longo prazo para esse problema está em andamento. Enquanto isso, considere a autenticação por meio da CLI do Azure.

Autenticar por meio da CLI do Azure

DefaultAzureCredential e AzureCliCredential podem se autenticar como o usuário conectado à CLI do Azure. Para entrar na CLI do Azure, execute az login. Em um sistema com um navegador da Web padrão, a CLI do Azure iniciará o navegador para autenticar um usuário.

Quando nenhum navegador padrão estiver disponível, az login o usará o fluxo de autenticação de código do dispositivo. Esse fluxo também pode ser selecionado manualmente executando az login --use-device-code.

Autenticar por meio do Azure Developer CLI

Os desenvolvedores que codificam fora de um IDE também podem usar o Azure Developer CLI para autenticar. Os aplicativos que usam DefaultAzureCredential ou AzureDeveloperCliCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.

Para autenticar com o Azure Developer CLI, os usuários podem executar o comando azd auth login. Para usuários em execução em um sistema com um navegador da Web padrão, o Azure Developer CLI iniciará o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando azd auth login --use-device-code usará o fluxo de autenticação de código do dispositivo.

Principais conceitos

Credenciais

Uma credencial é uma classe que contém ou pode obter os dados necessários para um cliente de serviço autenticar solicitações. Os clientes de serviço no SDK do Azure aceitam uma instância de credencial quando são construídos e usam essa credencial para autenticar solicitações.

A biblioteca de Identidade do Azure se concentra na autenticação OAuth com Azure AD. Ele oferece várias classes de credencial capazes de adquirir um token de acesso Azure AD. Consulte a seção Classes de credencial abaixo para obter uma lista das classes de credencial dessa biblioteca.

DefaultAzureCredential

DefaultAzureCredential é apropriado para a maioria dos aplicativos que serão executados no Azure porque combina credenciais de produção comuns com credenciais de desenvolvimento. DefaultAzureCredential tenta autenticar por meio dos seguintes mecanismos, nesta ordem, parando quando um for bem-sucedido:

Observação: DefaultAzureCredential destina-se a simplificar a introdução à biblioteca manipulando cenários comuns com comportamentos padrão razoáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é abordado nas configurações padrão devem usar outros tipos de credencial.

Fluxo de autenticação DefaultAzureCredential

  1. Ambiente - DefaultAzureCredential lerá as informações da conta especificadas por meio de de ambiente e as usará para autenticar.
  2. Identidade da carga de trabalho – se o aplicativo for implantado para Serviço de Kubernetes do Azure com a Identidade Gerenciada habilitada, DefaultAzureCredential será autenticada com ela.
  3. Identidade Gerenciada – se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, DefaultAzureCredential será autenticada com ele.
  4. CLI do Azure – se um usuário tiver se conectado por meio do comando da CLI az login do Azure, DefaultAzureCredential será autenticado como esse usuário.
  5. Azure PowerShell – se um usuário tiver se conectado por meio do comando do Connect-AzAccount Azure PowerShell, DefaultAzureCredential será autenticado como esse usuário.
  6. Azure Developer CLI – se o desenvolvedor tiver se autenticado por meio do comando Azure Developer CLIazd auth login, o DefaultAzureCredential será autenticado com essa conta.
  7. Navegador interativo – se habilitado, DefaultAzureCredential autenticará interativamente um usuário por meio do navegador padrão. Esse tipo de credencial está desabilitado por padrão.

Observação sobre VisualStudioCodeCredential

Devido a um problema conhecido, VisualStudioCodeCredential foi removido da DefaultAzureCredential cadeia de tokens. Quando o problema for resolvido em uma versão futura, essa alteração será revertida.

Exemplos

Os exemplos a seguir são fornecidos abaixo:

Autenticar com DefaultAzureCredential

Mais detalhes sobre como configurar seu ambiente para usar o DefaultAzureCredential podem ser encontrados na documentação de referência da classe.

Este exemplo demonstra a autenticação do BlobServiceClient da biblioteca azure-storage-blob usando DefaultAzureCredential.

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Habilitar a autenticação interativa com DefaultAzureCredential

A autenticação interativa está desabilitada no DefaultAzureCredential por padrão e pode ser habilitada com um argumento palavra-chave:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Quando habilitado, DefaultAzureCredential volta a ser autenticado interativamente por meio do navegador da Web padrão do sistema quando nenhuma outra credencial está disponível.

Especificar uma identidade gerenciada atribuída pelo usuário para DefaultAzureCredential

Muitos hosts do Azure permitem a atribuição de uma identidade gerenciada atribuída pelo usuário. Para configurar DefaultAzureCredential para autenticar uma identidade atribuída pelo usuário, use o managed_identity_client_id argumento palavra-chave:

DefaultAzureCredential(managed_identity_client_id=client_id)

Como alternativa, defina a variável AZURE_CLIENT_ID de ambiente como a ID do cliente da identidade.

Definir um fluxo de autenticação personalizado com ChainedTokenCredential

DefaultAzureCredential geralmente é a maneira mais rápida de começar a desenvolver aplicativos para o Azure. Para cenários mais avançados, ChainedTokenCredential vincula várias instâncias de credencial a serem tentadas sequencialmente durante a autenticação. Ele tentará cada credencial encadeada, por sua vez, até que uma forneça um token ou não seja autenticada devido a um erro.

O exemplo a seguir demonstra como criar uma credencial que primeiro tentará autenticar usando a identidade gerenciada. A credencial voltará a ser autenticada por meio da CLI do Azure quando uma identidade gerenciada não estiver disponível. Este exemplo usa o EventHubProducerClient da biblioteca de clientes azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Credenciais assíncronas

Essa biblioteca inclui um conjunto de APIs assíncronas. Para usar as credenciais assíncronas em azure.identity.aio, primeiro você deve instalar um transporte assíncrono, como aiohttp. Para obter mais informações, consulte a documentação do azure-core.

As credenciais assíncronas devem ser fechadas quando não forem mais necessárias. Cada credencial assíncrona é um gerenciador de contexto assíncrono e define um método assíncrono close . Por exemplo:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

Este exemplo demonstra a autenticação assíncrona SecretClient de azure-keyvault-secrets com uma credencial assíncrona.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Suporte de identidade gerenciada

A autenticação de identidade gerenciada tem suporte por meio do DefaultAzureCredential ou diretamente ManagedIdentityCredential para os seguintes serviços do Azure:

Exemplos

Autenticar com uma identidade gerenciada atribuída pelo usuário

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

Autenticar com uma identidade gerenciada atribuída pelo sistema

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

Configuração de nuvem

As credenciais são padrão para autenticar no ponto de extremidade Azure AD para a Nuvem Pública do Azure. Para acessar recursos em outras nuvens, como Azure Governamental ou uma nuvem privada, configure as credenciais com o authority argumento . O AzureAuthorityHosts define as autoridades para nuvens conhecidas:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Se a autoridade para sua nuvem não estiver listada no AzureAuthorityHosts, você poderá especificar explicitamente sua URL:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

Como alternativa à especificação do authority argumento, você também pode definir a AZURE_AUTHORITY_HOST variável de ambiente como a URL da autoridade da nuvem. Essa abordagem é útil ao configurar várias credenciais para autenticar na mesma nuvem:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Nem todas as credenciais exigem essa configuração. As credenciais que se autenticam por meio de uma ferramenta de desenvolvimento, como AzureCliCredential, usam a configuração dessa ferramenta. Da mesma forma, aceita um authority argumento, VisualStudioCodeCredential mas usa como padrão a autoridade que corresponde à configuração "Azure: Nuvem" do VS Code.

Classes de credencial

Autenticar aplicativos hospedados no Azure

Credencial Uso
DefaultAzureCredential Fornece uma experiência de autenticação simplificada para iniciar rapidamente o desenvolvimento de aplicativos executados no Azure.
ChainedTokenCredential Permita que os usuários definam fluxos de autenticação personalizados compondo várias credenciais.
EnvironmentCredential Autentica uma entidade de serviço ou um usuário por meio de informações de credencial especificadas em variáveis de ambiente.
ManagedIdentityCredential Autentica a identidade gerenciada de um recurso do Azure.
WorkloadIdentityCredential Dá suporte Azure AD identidade de carga de trabalho no Kubernetes.

Autenticar entidades de serviço

Credencial Uso Referência
CertificateCredential Autentica uma entidade de serviço usando um certificado. Autenticação de entidade de serviço
ClientAssertionCredential Autentica uma entidade de serviço usando uma declaração de cliente assinada.
ClientSecretCredential Autentica uma entidade de serviço usando um segredo. Autenticação de entidade de serviço

Autenticar usuários

Credencial Uso Referência
AuthorizationCodeCredential Autentica um usuário com um código de autorização obtido anteriormente. Código de autenticação do OAuth2
DeviceCodeCredential Autentica de modo interativo um usuário em dispositivos com interface do usuário limitada. Autenticação de código de dispositivo
InteractiveBrowserCredential Autentica interativamente um usuário com o navegador padrão do sistema. Código de autenticação do OAuth2
OnBehalfOfCredential Propaga a identidade do usuário delegado e as permissões por meio da cadeia de solicitações. Autenticação em nome de
UsernamePasswordCredential Autentica um usuário com um nome de usuário e senha (não dá suporte à autenticação multifator). Autenticação de nome de usuário e senha

Autenticar por meio de ferramentas de desenvolvimento

Credencial Uso Referência
AzureCliCredential Autentica em um ambiente de desenvolvimento com a CLI do Azure. Autenticação com a CLI do Azure
AzureDeveloperCliCredential Autentica em um ambiente de desenvolvimento com o Azure Developer CLI. Referência de Azure Developer CLI
AzurePowerShellCredential Autentica em um ambiente de desenvolvimento com o Azure PowerShell. autenticação Azure PowerShell
VisualStudioCodeCredential Autentica como o usuário entrou na extensão de conta do Visual Studio Code Azure. Extensão da conta do Azure do VS Code

Variáveis de ambiente

DefaultAzureCredential e EnvironmentCredential podem ser configurados com variáveis de ambiente. Cada tipo de autenticação requer valores para variáveis específicas:

Entidade de serviço com segredo

Nome da variável Valor
AZURE_CLIENT_ID ID de um aplicativo do Azure AD
AZURE_TENANT_ID ID do locatário do Azure AD do aplicativo
AZURE_CLIENT_SECRET um dos segredos do cliente do aplicativo

Entidade de serviço com certificado

Nome da variável Valor
AZURE_CLIENT_ID ID de um aplicativo do Azure AD
AZURE_TENANT_ID ID do locatário do Azure AD do aplicativo
AZURE_CLIENT_CERTIFICATE_PATH caminho para um arquivo de certificado PEM ou PKCS12, incluindo chave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD senha do arquivo de certificado, se houver

Nome de usuário e senha

Nome da variável Valor
AZURE_CLIENT_ID ID de um aplicativo do Azure AD
AZURE_USERNAME um nome de usuário (geralmente um endereço de email)
AZURE_PASSWORD a senha desse usuário

A configuração é tentada na ordem acima. Por exemplo, se os valores para um segredo do cliente e um certificado estiverem presentes, o segredo do cliente será usado.

Armazenamento de token em cache

O cache de tokens é um recurso fornecido pela biblioteca de Identidade do Azure que permite que os aplicativos:

  • Cache de tokens na memória (padrão) ou em disco (aceitação).
  • Melhorar a resiliência e o desempenho.
  • Reduza o número de solicitações feitas a Azure AD para obter tokens de acesso.

A biblioteca de Identidade do Azure oferece cache de disco persistente e na memória. Para obter mais detalhes, consulte a documentação de cache de token.

Solução de problemas

Consulte o guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Tratamento de erros

As credenciais são geradas CredentialUnavailableError quando não conseguem tentar a autenticação porque não têm dados ou estado necessários. Por exemplo, EnvironmentCredential gerará essa exceção quando estiver incompleta.

As credenciais geram azure.core.exceptions.ClientAuthenticationError quando não conseguem se autenticar. ClientAuthenticationError tem um message atributo , que descreve por que a autenticação falhou. Quando gerada por DefaultAzureCredential ou ChainedTokenCredential, a mensagem coleta mensagens de erro de cada credencial na cadeia.

Para obter mais informações sobre como lidar com erros de Azure AD específicos, consulte a documentação do código de erro Azure AD.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. As credenciais registram informações básicas, incluindo sessões HTTP (URLs, cabeçalhos etc.) no nível do INFO. Essas entradas de log não contêm segredos de autenticação.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e valores de cabeçalho, não está habilitado por padrão. Ele pode ser habilitado com o logging_enable argumento . Por exemplo:

credential = DefaultAzureCredential(logging_enable=True)

CUIDADO: os logs de nível DEBUG das credenciais contêm informações confidenciais. Esses logs devem ser protegidos para evitar comprometer a segurança da conta.

Próximas etapas

Suporte da biblioteca de clientes

Bibliotecas de cliente e gerenciamento listadas na página de versão do SDK do Azure que dão suporte a Azure AD autenticação aceitam credenciais dessa biblioteca. Você pode saber mais sobre como usar essas bibliotecas na documentação, que está vinculada na página de lançamento.

Problemas conhecidos

Essa biblioteca não dá suporte a Azure AD B2C.

Para outros problemas abertos, consulte o repositório GitHub da biblioteca.

Fornecer comentários

Se você encontrar bugs ou tiver sugestões, abra um problema.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões