Bibliothèque de client Azure Identity pour Java - version 1.10.4

La bibliothèque Azure Identity fournit la prise en charge de l’authentification par jeton Azure Active Directory (Azure AD) dans l’ensemble du Kit de développement logiciel (SDK) Azure. Il fournit un ensemble d’implémentations TokenCredential qui peuvent être utilisées pour construire des clients du Kit de développement logiciel (SDK) Azure qui prennent en charge l’authentification par jeton Azure AD.

| Code sourceDocumentation de référence sur les | APIDocumentation Azure AD

Prise en main

Inclure le package

Inclure le fichier de nomenclature

Incluez dans azure-sdk-bom votre projet pour avoir une dépendance sur la version stable de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le fichier Lisez-moi de la nomenclature du SDK 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>

Incluez ensuite la dépendance directe dans la dependencies section sans la balise de version :

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

Inclure une dépendance directe

Pour dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit :

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

Prérequis

• Un Kit de développement Java (JDK), version 8 ou ultérieure.
• Un abonnement Azure.
• Azure CLI peut également être utile pour l’authentification dans un environnement de développement, la création de comptes et la gestion des rôles de compte.

Authentifier le client

Lors du débogage et de l’exécution de code localement, il est courant pour un développeur d’utiliser son propre compte pour authentifier les appels aux services Azure. Plusieurs outils de développement peuvent être utilisés pour effectuer cette authentification dans votre environnement de développement :

• Azure Toolkit for IntelliJ
• Extension de compte Azure Visual Studio Code
  • Il s’agit d’un problème connu qui VisualStudioCodeCredential ne fonctionne pas avec les versions d’extension de compte Azure plus récentes que 0.9.11. Une solution à long terme à ce problème est en cours. En attendant, envisagez de vous authentifier via Azure CLI (ci-dessous).
• Azure CLI

Sélectionnez chaque élément ci-dessus pour savoir comment les configurer pour l’authentification Azure Identity.

Concepts clés

Titre de compétences

Les informations d’identification sont une classe qui contient ou peut obtenir les données nécessaires à un client de service pour authentifier les demandes. Les clients de service dans le Kit de développement logiciel (SDK) Azure acceptent les informations d’identification lorsqu’ils sont construits. Les clients de service utilisent ces informations d’identification pour authentifier les demandes adressées au service.

La bibliothèque d’identités Azure se concentre sur l’authentification OAuth avec Azure AD et offre différentes classes d’informations d’identification capables d’acquérir un jeton Azure AD pour authentifier les demandes de service. Toutes les classes d’informations d’identification de cette bibliothèque sont des implémentations de la TokenCredential classe abstraite dans azure-core, et chacune d’entre elles peut être utilisée par pour construire des clients de service capables de s’authentifier avec un TokenCredential.

Pour obtenir la liste complète des classes d’informations d’identification disponibles, consultez Classes d’informations d’identification .

DefaultAzureCredential

Convient à la DefaultAzureCredential plupart des scénarios où l’application est destinée à être exécutée dans Azure. C’est parce que les DefaultAzureCredential combinent les informations d’identification couramment utilisées pour l’authentification lors du déploiement avec les informations d’identification utilisées pour l’authentification dans un environnement de développement.

Remarque : DefaultAzureCredential est destiné à simplifier la prise en main du Kit de développement logiciel (SDK) en gérant des scénarios courants avec des comportements par défaut raisonnables. Les développeurs qui souhaitent davantage de contrôle ou dont le scénario n’est pas pris en charge par les paramètres par défaut doivent utiliser d’autres types d’informations d’identification.

DefaultAzureCredential tente de s’authentifier via les mécanismes suivants dans l’ordre.

1. Environnement : lit les DefaultAzureCredential informations de compte spécifiées via des variables d’environnement et les utilise pour s’authentifier.
2. Identité de charge de travail : si l’application est déployée sur Kubernetes avec des variables d’environnement définies par le webhook d’identité de charge de travail, DefaultAzureCredential authentifie l’identité configurée.
3. Identité managée : si l’application est déployée sur un hôte Azure avec l’identité managée activée, le DefaultAzureCredential s’authentifie avec ce compte.
4. Azure Developer CLI : si le développeur a authentifié un compte via la commande Azure Developer CLIazd auth login, le DefaultAzureCredential s’authentifie auprès de ce compte.
5. IntelliJ : si le développeur s’est authentifié via Azure Toolkit pour IntelliJ, s’authentifie DefaultAzureCredential auprès de ce compte.
6. Azure CLI : si le développeur a authentifié un compte via la commande Azure CLI az login , s’authentifie DefaultAzureCredential auprès de ce compte.
7. Azure PowerShell : si le développeur a authentifié un compte via la commande Azure PowerShellConnect-AzAccount, s’authentifie auprès de DefaultAzureCredential ce compte.

Stratégie de continuation

À partir de la version 1.10.0, DefaultAzureCredential tente de s’authentifier avec toutes les informations d’identification du développeur jusqu’à ce que l’une d’elles réussisse, quelles que soient les erreurs rencontrées précédemment dans les informations d’identification du développeur. Par exemple, une information d’identification de développeur peut tenter d’obtenir un jeton et échouer. Elle passe donc DefaultAzureCredential aux informations d’identification suivantes dans le flux. Les informations d’identification de service déployées arrêtent le flux avec une exception levée si elles sont en mesure de tenter de récupérer des jetons, mais qu’elles n’en reçoivent pas.

Cela permet d’essayer toutes les informations d’identification du développeur sur votre ordinateur tout en ayant un comportement de déploiement prévisible.

Remarque sur VisualStudioCodeCredential

En raison d’un problème connu, VisualStudioCodeCredential a été supprimé de la chaîne de DefaultAzureCredential jetons. Lorsque le problème est résolu dans une version ultérieure, cette modification est annulée.

Exemples

Vous trouverez d’autres exemples d’utilisation de diverses informations d’identification dans la page Wiki Exemples d’identité Azure.

Authentifier avec DefaultAzureCredential

Cet exemple illustre l’authentification du SecretClient à partir de la bibliothèque de client azure-security-keyvault-secrets à l’aide de 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();
}

Pour plus d’informations sur la configuration de DefaultAzureCredential sur votre station de travail ou Azure, consultez Configurer DefaultAzureCredential.

Authentifier une identité managée affectée par l’utilisateur avec DefaultAzureCredential

Pour vous authentifier à l’aide d’une identité managée affectée par l’utilisateur, assurez-vous que les instructions de configuration pour votre ressource Azure prise en charge ici ont été correctement remplies.

L’exemple ci-dessous illustre l’authentification du SecretClient à partir de la bibliothèque cliente azure-security-keyvault-secrets à l’aide du DefaultAzureCredential, déployé sur une ressource Azure avec une identité managée affectée par l’utilisateur configurée.

Pour plus d’informations sur la configuration d’une identité managée affectée par l’utilisateur pour une ressource Azure, consultez Activer l’identité managée pour les ressources 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();
}

En plus de configurer via le managedIdentityClientId code, il peut également être défini à l’aide de la variable d’environnement AZURE_CLIENT_ID . Ces deux approches sont équivalentes lors de l’utilisation de DefaultAzureCredential.

Authentifier un utilisateur dans le kit de ressources Azure pour IntelliJ avec DefaultAzureCredential

Pour vous authentifier à l’aide d’IntelliJ, vérifiez que les instructions de configuration ont été correctement exécutées ici .

L’exemple ci-dessous illustre l’authentification du SecretClient à partir de la bibliothèque de client azure-security-keyvault-secrets à l’aide du DefaultAzureCredential, sur une station de travail sur laquelle IntelliJ IDEA est installé, et l’utilisateur s’est connecté avec un compte Azure au kit de ressources Azure pour IntelliJ.

Pour plus d’informations sur la configuration de votre intelliJ IDEA , consultez Se connecter au kit de ressources Azure pour IntelliJ pour 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();
}

Prise en charge des identités managées

L’authentification d’identité managée est prise en charge via ou DefaultAzureCredentialManagedIdentityCredential directement pour les services Azure suivants :

• Azure App Service et Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Machines virtuelles Azure
• Azure Virtual Machine Scale Sets

Note: Utilisez la azure-identity version ou une version 1.7.0 ultérieure pour utiliser la prise en charge de la mise en cache de jetons pour l’authentification d’identité managée.

Exemples

S’authentifier dans Azure avec une identité managée

Cet exemple illustre l’authentification du SecretClient à partir de la bibliothèque cliente azure-security-keyvault-secrets à l’aide de ManagedIdentityCredential dans une machine virtuelle, un service d’application, une application de fonction, un environnement Cloud Shell ou AKS sur Azure, avec une identité managée affectée par le système ou affectée par l’utilisateur activée.

Pour plus d’informations sur la configuration de votre ressource Azure pour l’identité managée, consultez Activer l’identité managée pour les ressources 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();
}

Définir un flux d’authentification personnalisé avec les ChainedTokenCredential

L’utilisation des DefaultAzureCredential est généralement le moyen le plus rapide pour commencer à développer des applications pour Azure, mais les utilisateurs plus expérimentés souhaiteront peut-être personnaliser les informations d’identification prises en compte lors de l’authentification. Avec ChainedTokenCredential, les utilisateurs peuvent combiner plusieurs instances d’informations d’identification pour définir une chaîne d’informations d’identification personnalisée. Cet exemple illustre la création d’un ChainedTokenCredential, qui :

• Essayez de vous authentifier à l’aide de l’identité managée.
• Revenez à l’authentification via Azure CLI si l’identité managée n’est pas disponible dans l’environnement actuel.

// 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();

Cloud configuration

Par défaut, les informations d’identification s’authentifient auprès du point de terminaison Azure AD pour le cloud public Azure. Pour accéder aux ressources d’autres clouds, telles que Azure Government ou un cloud privé, configurez les informations d’identification avec l’argument auhtorityHost . AzureAuthorityHosts définit les autorités pour les clouds connus :

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

Toutes les informations d’identification ne nécessitent pas cette configuration. Les informations d’identification qui s’authentifient via un outil de développement, tel que AzureCliCredential, utilisent la configuration de cet outil. De même, VisualStudioCodeCredential accepte un authority argument, mais utilise par défaut l’autorité correspondant au paramètre « Azure : Cloud » de VS Code.

Classes d’informations d’identification

Authentifier les applications hébergées par Azure

Authentifier les principaux de service

Authentification des utilisateurs

S’authentifier via des outils de développement

Note: Toutes les implémentations d’informations d’identification dans la bibliothèque d’identités Azure sont threadsafe, et une seule instance d’informations d’identification peut être utilisée pour créer plusieurs clients de service.

Les informations d’identification peuvent être chaînées pour être essayées à leur tour jusqu’à ce que l’une d’elles réussisse à l’aide de ChainedTokenCredential. Pour plus d’informations, consultez les informations d’identification de chaînage .

Variables d'environnement

Les DefaultAzureCredential et EnvironmentCredential peuvent être configurés à l’aide de variables d’environnement. Chaque type d’authentification nécessite des valeurs pour des variables spécifiques :

Principal de service avec une clé secrète

Principal de service avec un certificat

Nom d’utilisateur et mot de passe

La configuration est tentée dans l’ordre indiqué ci-dessus. Par exemple, si les valeurs d’un certificat et d’une clé secrète client sont toutes deux présentes, la clé secrète client est utilisée.

Évaluation continue de l’accès

À partir de la version 1.10.0, l’accès aux ressources protégées par l’évaluation continue de l’accès (CAE) est possible par demande. Cela peut être activé à l’aide de l’APITokenRequestContext.setCaeEnabled(boolean). CAE n’est pas pris en charge pour les informations d’identification des développeurs.

Mise en cache de jeton

La mise en cache de jetons est une fonctionnalité fournie par la bibliothèque Azure Identity qui permet aux applications de :

• Cachez les jetons en mémoire (par défaut) ou sur le disque (opt-in).
• Améliorez la résilience et les performances.
• Réduisez le nombre de demandes adressées à Azure AD pour obtenir des jetons d’accès.

La bibliothèque Azure Identity offre à la fois une mise en cache de disque en mémoire et persistante. Pour plus d’informations, consultez la documentation relative à la mise en cache des jetons.

Dépannage

Les informations d’identification déclenchent des exceptions lorsqu’elles ne parviennent pas à s’authentifier ou ne peuvent pas exécuter l’authentification. Lorsque les informations d’identification ne parviennent pas à s’authentifier, leClientAuthenticationException est déclenché. L’exception a un message attribut, qui décrit la raison de l’échec de l’authentification. Lorsque cette exception est levée par ChainedTokenCredential, l’exécution chaînée de la liste sous-jacente des informations d’identification est arrêtée.

Lorsque les informations d’identification ne peuvent pas exécuter l’authentification en raison de l’une des ressources sous-jacentes requises par l’indisponibilité des informations d’identification sur l’ordinateur, leCredentialUnavailableException est déclenché. L’exception a un message attribut qui décrit la raison pour laquelle les informations d’identification ne sont pas disponibles pour l’exécution de l’authentification. Lorsque cette exception est levée par ChainedTokenCredential, le message collecte les messages d’erreur de chaque informations d’identification dans la chaîne.

Consultez le guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Étapes suivantes

Les bibliothèques clientes Java répertoriées ici prennent en charge l’authentification avec TokenCredential et la bibliothèque d’identités Azure. Vous pouvez en savoir plus sur leur utilisation et trouver une documentation supplémentaire sur l’utilisation de ces bibliothèques clientes ainsi que des exemples avec se trouvent dans les liens mentionnés ici.

Le sdk microsoft-graph-prend également en charge l’authentification avec TokenCredential et la bibliothèque d’identités Azure.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.