Compartilhar via

Biblioteca de clientes da Identidade do Azure para Java – versão 1.10.4

  • 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 implementações TokenCredential que podem ser usadas para construir clientes do SDK do Azure que dão suporte à autenticação de token Azure AD.

Código-fonte | Documentação | de referência da APIdocumentação do Azure AD

Introdução

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para usar uma dependência na versão estável da biblioteca. No snippet a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, confira o LEIAME do BOM do SDK do Azure.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Em seguida, inclua a dependência direta na dependencies seção sem a marca de versão:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Para assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Pré-requisitos

Autenticar o cliente

Ao depurar e executar o código localmente, é comum que um desenvolvedor use sua própria conta para autenticar chamadas aos serviços do Azure. Há várias ferramentas de desenvolvedor que podem ser usadas para executar essa autenticação em seu ambiente de desenvolvimento:

Selecione cada item acima para saber mais sobre como configurá-los para a autenticação de Identidade do Azure.

Principais conceitos

Credencial

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 credenciais quando são construídos. Os clientes de serviço usam essas credenciais para autenticar solicitações para o serviço.

A biblioteca de Identidade do Azure se concentra na autenticação OAuth com Azure AD e oferece várias classes de credencial capazes de adquirir um token Azure AD para autenticar solicitações de serviço. Todas as classes de credencial nesta biblioteca são implementações da TokenCredential classe abstrata no azure-core e qualquer uma delas pode ser usada por para construir clientes de serviço capazes de autenticar com um TokenCredential.

Confira Classes de credencial para obter uma lista completa das classes de credencial disponíveis.

DefaultAzureCredential

O DefaultAzureCredential é apropriado para a maioria dos cenários em que o aplicativo se destina a ser executado no Azure. Isso ocorre porque o DefaultAzureCredential combina as credenciais normalmente usadas para autenticação quando implantada com as credenciais usadas para realizar a autenticação em um ambiente de desenvolvimento.

Observação: DefaultAzureCredential destina-se a simplificar a introdução ao SDK 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.

A DefaultAzureCredential tentará realizar a autenticação usando os mecanismos a seguir na ordem.

Fluxo de autenticação DefaultAzureCredential

  1. Ambiente – o DefaultAzureCredential lerá as informações da conta especificadas por meio de variáveis de ambiente e as usará para autenticar.
  2. Identidade da carga de trabalho – se o aplicativo for implantado no Kubernetes com variáveis de ambiente definidas pelo webhook de identidade de carga de trabalho, DefaultAzureCredential autenticará a identidade configurada.
  3. Identidade Gerenciada – se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, o DefaultAzureCredential será autenticado com essa conta.
  4. Azure Developer CLI – se o desenvolvedor tiver autenticado uma conta por meio do comando Azure Developer CLIazd auth login, o DefaultAzureCredential será autenticado com essa conta.
  5. IntelliJ – se o desenvolvedor tiver se autenticado por meio do Kit de Ferramentas do Azure para IntelliJ, o DefaultAzureCredential será autenticado com essa conta.
  6. CLI do Azure – se o desenvolvedor tiver autenticado uma conta por meio do comando da CLI az login do Azure, o DefaultAzureCredential será autenticado com essa conta.
  7. Azure PowerShell – se o desenvolvedor tiver autenticado uma conta por meio do comando Azure PowerShellConnect-AzAccount, o DefaultAzureCredential será autenticado com essa conta.

Política de continuação

A partir da v1.10.0, DefaultAzureCredential tentará autenticar com todas as credenciais de desenvolvedor até que uma seja bem-sucedida, independentemente de erros que as credenciais anteriores do desenvolvedor tenham sofrido. Por exemplo, uma credencial de desenvolvedor pode tentar obter um token e falhar, portanto DefaultAzureCredential , continuará para a próxima credencial no fluxo. As credenciais de serviço implantadas interromperão o fluxo com uma exceção gerada se puderem tentar recuperar o token, mas não receberem uma.

Isso permite experimentar todas as credenciais do desenvolvedor em seu computador, ao mesmo tempo em que tem um comportamento previsível implantado.

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

Você pode encontrar mais exemplos de como usar várias credenciais na página Wiki de Exemplos de Identidade do Azure.

Autenticar com DefaultAzureCredential

Este exemplo demonstra a autenticação do SecretClient da biblioteca de clientes azure-security-keyvault-secrets usando a DefaultAzureCredential.

/**
 * The default credential first checks environment variables for configuration.
 * If environment configuration is incomplete, it will try managed identity.
 */
public void createDefaultAzureCredential() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Veja mais como configurar o DefaultAzureCredential em sua estação de trabalho ou no Azure em Configurar DefaultAzureCredential.

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

Para autenticar usando a identidade gerenciada atribuída pelo usuário, verifique se as instruções de configuração para o recurso do Azure com suporte aqui foram concluídas com êxito.

O exemplo abaixo demonstra a SecretClient autenticação da biblioteca de clientes azure-security-keyvault-secrets usando o DefaultAzureCredential, implantado em um recurso do Azure com uma identidade gerenciada atribuída pelo usuário configurada.

Veja mais sobre como configurar uma identidade gerenciada atribuída pelo usuário para um recurso do Azure em Habilitar identidade gerenciada para recursos do Azure.

/**
 * The default credential will use the user assigned managed identity with the specified client ID.
 */
public void createDefaultAzureCredentialForUserAssignedManagedIdentity() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        .managedIdentityClientId("<MANAGED_IDENTITY_CLIENT_ID>")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Além de configurar o por meio do managedIdentityClientId código, ele também pode ser definido usando a AZURE_CLIENT_ID variável de ambiente. Essas duas abordagens são equivalentes ao usar o DefaultAzureCredential.

Autenticar um usuário no Kit de Ferramentas do Azure para IntelliJ com DefaultAzureCredential

Para autenticar usando o IntelliJ, verifique se as instruções de configuração aqui foram concluídas com êxito.

O exemplo abaixo demonstra a SecretClient autenticação da biblioteca de clientes azure-security-keyvault-secrets usando o DefaultAzureCredential, em uma estação de trabalho com o IntelliJ IDEA instalado e o usuário entrou com uma conta do Azure no Kit de Ferramentas do Azure para IntelliJ.

Veja mais sobre como configurar seu IntelliJ IDEA em Entrar no Kit de Ferramentas do Azure para IntelliJ para IntelliJCredential.

/**
 * The default credential will use the KeePass database path to find the user account in IntelliJ on Windows.
 */
public void createDefaultAzureCredentialForIntelliJ() {
    DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
        // KeePass configuration required only for Windows. No configuration needed for Linux / Mac
        .intelliJKeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(defaultCredential)
        .buildClient();
}

Suporte à Identidade Gerenciada

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

Nota: Use azure-identity a versão 1.7.0 ou posterior para utilizar o suporte ao cache de token para autenticação de identidade gerenciada.

Exemplos

Autenticar no Azure com a Identidade Gerenciada

Este exemplo demonstra a autenticação da SecretClient biblioteca de clientes azure-security-keyvault-secrets usando o ManagedIdentityCredential em uma máquina virtual, serviço de aplicativo, aplicativo de funções, cloud shell ou ambiente aks no Azure, com identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário habilitada.

Veja mais sobre como configurar seu recurso do Azure para identidade gerenciada em Habilitar identidade gerenciada para recursos do Azure

/**
 * Authenticate with a User Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .clientId("<USER ASSIGNED MANAGED IDENTITY CLIENT ID>") // only required for user assigned
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

/**
 * Authenticate with a System Assigned Managed identity.
 */
public void createManagedIdentityCredential() {
    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(managedIdentityCredential)
        .buildClient();
}

Definir um fluxo de autenticação personalizado com ChainedTokenCredential

Embora DefaultAzureCredential seja geralmente a maneira mais rápida de começar a desenvolver aplicativos para o Azure, os usuários mais avançados podem personalizar as credenciais consideradas durante a autenticação. ChainedTokenCredential permite que os usuários combinem várias instâncias de credencial para definir uma cadeia personalizada de credenciais. Este exemplo demonstra a criação de um ChainedTokenCredential, que:

  • Tente autenticar usando a identidade gerenciada.
  • Volte à autenticação por meio da CLI do Azure se a identidade gerenciada não estiver disponível no ambiente atual.
// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

    ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
    AzureCliCredential cliCredential = new AzureCliCredentialBuilder().build();

    ChainedTokenCredential credential = new ChainedTokenCredentialBuilder().addLast(managedIdentityCredential).addLast(cliCredential).build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(credential)
        .buildClient();

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 auhtorityHost argumento . O AzureAuthorityHosts define as autoridades para nuvens conhecidas:

DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
    .build();

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

Autenticar aplicativos hospedados no Azure
Classe de credencial Uso Exemplo
DefaultAzureCredential fornece uma experiência de autenticação simplificada para iniciar rapidamente o desenvolvimento de aplicativos executados no Azure Exemplo
ChainedTokenCredential permite que os usuários definam fluxos de autenticação personalizados compondo várias credenciais Exemplo
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 Exemplo
WorkloadIdentityCredential dá suporte Azure AD identidade de carga de trabalho no Kubernetes Exemplo

Autenticar entidades de serviço

Autenticar entidades de serviço
Classe de credencial Uso Exemplo Referência
ClientAssertionCredential autentica uma entidade de serviço usando uma declaração de cliente assinada
ClientCertificateCredential autentica uma entidade de serviço usando um certificado Exemplo Autenticação de entidade de serviço
ClientSecretCredential autentica uma entidade de serviço usando um segredo Exemplo Autenticação de entidade de serviço

Autenticar usuários

Autenticar usuários
Classe de credencial Uso Exemplo Referência
AuthorizationCodeCredential autenticar um usuário com um código de autorização obtido anteriormente como parte de um fluxo Oauth 2 Código de autenticação do OAuth2
DeviceCodeCredential autentica interativamente um usuário em dispositivos com interface do usuário limitada Exemplo Autenticação de código de dispositivo
InteractiveBrowserCredential autentica interativamente um usuário com o navegador do sistema padrão Exemplo 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 sem autenticação multifator Exemplo Autenticação de nome de usuário e senha

Autenticar por meio de ferramentas de desenvolvimento

Autenticar por meio de ferramentas de desenvolvimento
Classe de credencial Uso Exemplo Referência
AzureCliCredential Autenticar em um ambiente de desenvolvimento com o usuário ou entidade de serviço habilitado na CLI do Azure Exemplo Autenticação com a CLI do Azure
AzureDeveloperCliCredential Autenticar em um ambiente de desenvolvimento com o usuário ou entidade de serviço habilitado no Azure Developer CLI Referência de Azure Developer CLI
AzurePowerShellCredential Autenticar em um ambiente de desenvolvimento com o usuário ou entidade de serviço habilitado no Azure PowerShell Exemplo Documentação do Azure PowerShell
IntelliJCredential Autenticar em um ambiente de desenvolvimento com a conta no Kit de Ferramentas do Azure para IntelliJ Exemplo Autenticação IntelliJ
VisualStudioCodeCredential Autentique-se em um ambiente de desenvolvimento com a conta em Visual Studio Code extensão de Conta do Azure. Exemplo Extensão da conta do Azure do VS Code

Nota: Todas as implementações de credencial na biblioteca de identidade do Azure são threadsafe e uma única instância de credencial pode ser usada para criar vários clientes de serviço.

As credenciais podem ser encadeadas juntas para serem testadas, por sua vez, até que uma seja bem-sucedida usando o ChainedTokenCredential; consulte encadear credenciais para obter detalhes.

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

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

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 codificado em PEM ou PFX, incluindo chave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD (opcional) senha para certificado. O certificado não pode ser protegido por senha, a menos que esse valor seja especificado.

Nome de usuário e senha

Nome de usuário e senha
Nome da variável Valor
AZURE_CLIENT_ID ID de um aplicativo do Azure AD
AZURE_TENANT_ID (opcional) ID do locatário Azure AD do aplicativo
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.

Avaliação contínua de acesso

A partir da v1.10.0, o acesso aos recursos protegidos pela CAE ( Avaliação Contínua de Acesso ) é possível por solicitação. Isso pode ser habilitado usando a TokenRequestContext.setCaeEnabled(boolean) API. Não há suporte para CAE para credenciais de desenvolvedor.

Armazenamento de token em cache

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

  • Tokens de cache na memória (padrão) ou no 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

As credenciais geram exceções quando falham na autenticação ou não podem executar a autenticação. Quando as credenciais falham ao autenticar, oClientAuthenticationException é gerado. A exceção tem um message atributo , que descreve por que a autenticação falhou. Quando essa exceção é gerada pelo ChainedTokenCredential, a execução encadeada da lista subjacente de credenciais é interrompida.

Quando as credenciais não podem executar a autenticação devido a um dos recursos subjacentes exigidos pela credencial que está indisponível no computador, oCredentialUnavailableException é gerado. A exceção tem um message atributo que descreve por que a credencial não está disponível para execução de autenticação. Quando essa exceção é gerada por ChainedTokenCredential, a mensagem coleta mensagens de erro de cada credencial na cadeia.

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

Próximas etapas

As bibliotecas de clientes Java listadas aqui dão suporte à autenticação com TokenCredential e à biblioteca de identidade do Azure. Você pode saber mais sobre seu uso e encontrar documentação adicional sobre o uso dessas bibliotecas de clientes junto com exemplos pode ser encontrada nos links mencionados aqui.

O microsoft-graph-sdk também dá suporte à autenticação com TokenCredential e à biblioteca de identidade do Azure.

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 que usam 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 pelo email opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões