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

  • Artigo

A biblioteca de Identidades do Azure fornece suporte de autenticação de tokens do Azure Active Directory (Azure AD) no SDK do Azure. Fornece um conjunto de TokenCredential implementações, que podem ser utilizadas para construir clientes do SDK do Azure que suportam Azure AD autenticação de tokens.

Código fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIAzure AD documentação

Introdução

Instalar o pacote

Instalar a Identidade do Azure com pip:

pip install azure-identity

Pré-requisitos

  • Uma subscrição do Azure
  • Python 3.7 ou uma versão recente do Python 3 (esta biblioteca não suporta versões de fim de vida)

Autenticar durante o desenvolvimento local

Ao depurar e executar código localmente, é normal que os programadores utilizem as suas próprias contas para autenticar chamadas para serviços do Azure. A biblioteca de Identidades do Azure suporta a autenticação através de ferramentas de programador para simplificar o desenvolvimento local.

Autenticar através do Visual Studio Code

Os programadores que utilizam o Visual Studio Code podem utilizar a extensão da Conta do Azure para se autenticarem através do editor. As aplicações que utilizam DefaultAzureCredential ou VisualStudioCodeCredential podem utilizar esta conta para autenticar chamadas na respetiva aplicação quando são executadas localmente.

Para autenticar no Visual Studio Code, certifique-se de que a extensão da Conta do Azure está instalada. Depois de instalado, abra a Paleta de Comandos e execute o comando Azure: Iniciar Sessão .

É um problema conhecido que VisualStudioCodeCredential não funciona com as versões da extensão da Conta do Azure mais recentes do que a 0.9.11. Está em curso uma correção a longo prazo deste problema. Entretanto, considere autenticar através da CLI do Azure.

Autenticar através da CLI do Azure

DefaultAzureCredential e AzureCliCredential pode autenticar-se como o utilizador com sessão iniciada na CLI do Azure. Para iniciar sessão na CLI do Azure, execute az login. Num sistema com um browser predefinido, a CLI do Azure iniciará o browser para autenticar um utilizador.

Quando não estiver disponível um browser predefinido, az login utilizará o fluxo de autenticação de código do dispositivo. Este fluxo também pode ser selecionado manualmente ao executar az login --use-device-code.

Autenticar através do Azure Developer CLI

Os programadores que codificam fora de um IDE também podem utilizar o Azure Developer CLI para autenticar. As aplicações que utilizam o DefaultAzureCredential ou o AzureDeveloperCliCredential podem utilizar esta conta para autenticar chamadas na respetiva aplicação quando são executadas localmente.

Para se autenticarem com a Azure Developer CLI, os utilizadores podem executar o comando azd auth login. Para os utilizadores em execução num sistema com um browser predefinido, o Azure Developer CLI iniciará o browser para autenticar o utilizador.

Para sistemas sem um browser predefinido, o azd auth login --use-device-code comando utilizará o fluxo de autenticação de código do dispositivo.

Conceitos-chave

Credenciais

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

A biblioteca de Identidades do Azure foca-se na autenticação OAuth com Azure AD. Oferece várias classes de credenciais capazes de adquirir um token de acesso Azure AD. Veja a secção de credenciais Classes de credenciais abaixo para obter uma lista das classes de credenciais desta biblioteca.

DefaultAzureCredential

DefaultAzureCredential é adequado para a maioria das aplicações que serão executadas no Azure porque combina credenciais de produção comuns com credenciais de desenvolvimento. DefaultAzureCredential tenta autenticar-se através dos seguintes mecanismos, por esta ordem, parando quando um é bem-sucedido:

Nota: DefaultAzureCredential destina-se a simplificar a introdução à biblioteca ao processar cenários comuns com comportamentos predefinidos razoáveis. Os programadores que pretendam ter mais controlo ou cujo cenário não seja servido pelas predefinições devem utilizar outros tipos de credenciais.

Fluxo de autenticação DefaultAzureCredential

  1. Ambiente - DefaultAzureCredential irá ler as informações de conta especificadas e utilizá-la para autenticar.
  2. Identidade da Carga de Trabalho – se a aplicação for implementada no Azure Kubernetes Service com a Identidade Gerida ativada, DefaultAzureCredential será autenticada com a mesma.
  3. Identidade Gerida – se a aplicação for implementada num anfitrião do Azure com a Identidade Gerida ativada, DefaultAzureCredential será autenticada com a mesma.
  4. CLI do Azure – se um utilizador tiver iniciado sessão através do comando da CLI az login do Azure, DefaultAzureCredential será autenticado como esse utilizador.
  5. Azure PowerShell – se um utilizador tiver iniciado sessão através do comando de Connect-AzAccount Azure PowerShell, DefaultAzureCredential será autenticado como esse utilizador.
  6. Azure Developer CLI - Se o programador se tiver autenticado através do comando Azure Developer CLIazd auth login, o DefaultAzureCredential será autenticado com essa conta.
  7. Browser interativo – se estiver ativado, DefaultAzureCredential autenticará interativamente um utilizador através do browser predefinido. Este tipo de credencial está desativado por predefinição.

Nota sobre VisualStudioCodeCredential

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

Exemplos

Os exemplos seguintes são fornecidos abaixo:

Autenticar com DefaultAzureCredential

Pode encontrar mais detalhes sobre como configurar o seu ambiente para utilizar o DefaultAzureCredential na documentação de referência da classe.

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

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Ativar a autenticação interativa com DefaultAzureCredential

A autenticação interativa está desativada por predefinição DefaultAzureCredential e pode ser ativada com um argumento de palavra-chave:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Quando ativada, DefaultAzureCredential a autenticação interativa é feita através do browser predefinido do sistema quando não existem outras credenciais disponíveis.

Especifique uma identidade gerida atribuída pelo utilizador para DefaultAzureCredential

Muitos anfitriões do Azure permitem a atribuição de uma identidade gerida atribuída pelo utilizador. Para configurar DefaultAzureCredential para autenticar uma identidade atribuída pelo utilizador, utilize o managed_identity_client_id argumento de palavra-chave:

DefaultAzureCredential(managed_identity_client_id=client_id)

Em alternativa, defina a variável AZURE_CLIENT_ID de ambiente para o ID de cliente da identidade.

Definir um fluxo de autenticação personalizado com ChainedTokenCredential

DefaultAzureCredential geralmente, é a forma mais rápida de começar a desenvolver aplicações para o Azure. Para cenários mais avançados, ChainedTokenCredential liga várias instâncias de credenciais para serem experimentadas sequencialmente ao autenticar. Tentará cada credencial em cadeia por sua vez até que uma forneça um token ou não se autentique devido a um erro.

O exemplo seguinte demonstra a criação de uma credencial que tentará primeiro autenticar com a identidade gerida. A credencial reverterá para a autenticação através da CLI do Azure quando uma identidade gerida estiver indisponível. Este exemplo utiliza a EventHubProducerClient da biblioteca de cliente 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

Esta biblioteca inclui um conjunto de APIs assíncronas. Para utilizar as credenciais assíncronas em azure.identity.aio, primeiro tem de instalar um transporte assíncrono, como aiohttp. Para obter mais informações, veja a documentação azure-core.

As credenciais assíncronas devem ser fechadas quando já não forem necessárias. Cada credencial assíncrona é um gestor 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 gerida

A autenticação de identidade gerida é suportada através do DefaultAzureCredential ou diretamente ManagedIdentityCredential para os seguintes serviços do Azure:

Exemplos

Autenticar com uma identidade gerida atribuída pelo utilizador

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 gerida 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 da nuvem

As credenciais estão predefinidas para autenticar no ponto final Azure AD para a Cloud Pública do Azure. Para aceder a recursos noutras clouds, como Azure Government ou numa nuvem privada, configure as credenciais com o authority argumento . O AzureAuthorityHosts define as autoridades para clouds conhecidas:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Se a autoridade para a sua cloud não estiver listada no AzureAuthorityHosts, pode especificar explicitamente o RESE:

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

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

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

Nem todas as credenciais requerem esta configuração. As credenciais que se autenticam através de uma ferramenta de desenvolvimento, como AzureCliCredential, utilizam a configuração dessa ferramenta. Da mesma forma, aceita um authority argumento, VisualStudioCodeCredential mas é predefinido para a autoridade que corresponde à definição "Azure: Cloud" do VS Code.

Classes de credenciais

Autenticar aplicações alojadas no Azure

Credencial Utilização
DefaultAzureCredential Fornece uma experiência de autenticação simplificada para começar rapidamente a desenvolver aplicações executadas no Azure.
ChainedTokenCredential Permite que os utilizadores definam fluxos de autenticação personalizados compondo múltiplas credenciais.
EnvironmentCredential Autentica um principal de serviço ou utilizador através de informações de credenciais especificadas em variáveis de ambiente.
ManagedIdentityCredential Autentica a identidade gerida de um recurso do Azure.
WorkloadIdentityCredential Suporta Azure AD identidade da carga de trabalho no Kubernetes.

Autenticar principais de serviço

Credencial Utilização Referência
CertificateCredential Autentica um principal de serviço com um certificado. Autenticação do principal de serviço
ClientAssertionCredential Autentica um principal de serviço com uma asserção de cliente assinada.
ClientSecretCredential Autentica um principal de serviço com um segredo. Autenticação do principal de serviço

Autenticar utilizadores

Credencial Utilização Referência
AuthorizationCodeCredential Autentica um utilizador com um código de autorização obtido anteriormente. Código de autenticação OAuth2
DeviceCodeCredential Autentica interativamente um utilizador em dispositivos com IU limitada. Autenticação do código do dispositivo
InteractiveBrowserCredential Autentica interativamente um utilizador com o browser de sistema predefinido. Código de autenticação OAuth2
OnBehalfOfCredential Propaga a identidade de utilizador delegado e as permissões através da cadeia de pedidos. Autenticação em nome de
UsernamePasswordCredential Autentica um utilizador com um nome de utilizador e palavra-passe (não suporta a autenticação multifator). Nome de utilizador + autenticação por palavra-passe

Autenticar através de ferramentas de desenvolvimento

Credencial Utilização Referência
AzureCliCredential Autentica-se num ambiente de desenvolvimento com a CLI do Azure. Autenticação da CLI do Azure
AzureDeveloperCliCredential Autentica-se num ambiente de desenvolvimento com o Azure Developer CLI. Referência Azure Developer CLI
AzurePowerShellCredential Autentica-se num ambiente de desenvolvimento com a Azure PowerShell. autenticação Azure PowerShell
VisualStudioCodeCredential Autentica-se como o utilizador que iniciou sessão na extensão da Conta do Azure do Visual Studio Code. 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:

Principal de serviço com segredo

Nome da variável Valor
AZURE_CLIENT_ID ID de uma aplicação Azure AD
AZURE_TENANT_ID ID do inquilino Azure AD da aplicação
AZURE_CLIENT_SECRET um dos segredos do cliente da aplicação

Principal de serviço com certificado

Nome da variável Valor
AZURE_CLIENT_ID ID de uma aplicação Azure AD
AZURE_TENANT_ID ID do inquilino Azure AD da aplicação
AZURE_CLIENT_CERTIFICATE_PATH caminho para um ficheiro de certificado PEM ou PKCS12, incluindo chave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD palavra-passe do ficheiro de certificado, se existir

Nome de utilizador e palavra-passe

Nome da variável Valor
AZURE_CLIENT_ID ID de uma aplicação Azure AD
AZURE_USERNAME um nome de utilizador (normalmente um endereço de e-mail)
AZURE_PASSWORD palavra-passe desse utilizador

A configuração é tentada pela ordem acima. Por exemplo, se os valores de um segredo de cliente e certificado estiverem ambos presentes, será utilizado o segredo do cliente.

Colocação em cache de tokens

A colocação em cache de tokens é uma funcionalidade fornecida pela biblioteca de Identidade do Azure que permite que as aplicações:

  • Colocar tokens em cache na memória (predefinição) ou no disco (optar ativamente por participar).
  • Melhorar a resiliência e o desempenho.
  • Reduza o número de pedidos feitos a Azure AD para obter tokens de acesso.

A biblioteca de Identidades do Azure oferece colocação em cache dentro da memória e do disco persistente. Para obter mais detalhes, veja a documentação de colocação em cache de tokens.

Resolução de problemas

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

Processamento de erros

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

As credenciais são levantadas azure.core.exceptions.ClientAuthenticationError quando falham na autenticação. ClientAuthenticationError tem um message atributo, que descreve o motivo pelo qual a autenticação falhou. Quando gerado por DefaultAzureCredential ou ChainedTokenCredential, a mensagem recolhe mensagens de erro de cada credencial na cadeia.

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

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo. As credenciais registam informações básicas, incluindo sessões HTTP (URLs, cabeçalhos, etc.) ao nível da INFORMAÇÃO. Estas entradas de registo não contêm segredos de autenticação.

O registo de nível DEBUG detalhado, incluindo os corpos de pedido/resposta e os valores do cabeçalho, não está ativado por predefinição. Pode ser ativado com o logging_enable argumento. Por exemplo:

credential = DefaultAzureCredential(logging_enable=True)

ATENÇÃO: os registos de nível de DEPURAÇÃO de credenciais contêm informações confidenciais. Estes registos têm de ser protegidos para evitar comprometer a segurança da conta.

Passos seguintes

Suporte da biblioteca de cliente

As bibliotecas de cliente e gestão listadas na página de versão do SDK do Azure que suportam Azure AD autenticação aceitam credenciais desta biblioteca. Pode saber mais sobre como utilizar estas bibliotecas na respetiva documentação, que está ligada a partir da página de lançamento.

Problemas conhecidos

Esta biblioteca não suporta Azure AD B2C.

Para obter outros problemas abertos, veja o repositório do GitHub da biblioteca.

Enviar comentários

Se encontrar erros ou tiver sugestões, abra um problema.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Só terá de o fazer uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões