Bibliothèque de client Azure Identity Brokered Authentication pour .NET - version 1.0.0

La bibliothèque étend la bibliothèque Azure.Identity pour fournir la prise en charge du répartiteur d’authentification. Il inclut les dépendances nécessaires et fournit la InteractiveBrowserCredentialBrokerOptions classe . Cette classe d’options peut être utilisée pour créer un capable d’utiliser InteractiveBrowserCredential le répartiteur d’authentification système au lieu du navigateur système lorsqu’il est disponible.

| Code sourcePackage (nuget) | Documentation de référence sur les | APIdocumentation sur l’ID Microsoft Entra

Prise en main

Installer le package

Installez la bibliothèque de client Azure Identity pour .NET avec NuGet :

dotnet add package Azure.Identity.Broker

Prérequis

• La bibliothèque Azure.Identity est une dépendance d’Azure.Identity.Broker.

Authentifier le client

Concepts clés

Ce package permet la prise en charge du répartiteur d’authentification via InteractiveBrowserCredentialBrokerOptions, en combinaison avec InteractiveBrowserCredential dans le Azure.Identity package.

Handles de fenêtre parente

Lors de l’authentification interactive via InteractiveBrowserCredential construit avec , InteractiveBrowserCredentialBrokerOptionsun handle de fenêtre parent est nécessaire pour garantir que la boîte de dialogue d’authentification s’affiche correctement sur la fenêtre de demande. Dans le contexte des interfaces utilisateur graphiques sur les appareils, un handle de fenêtre est un identificateur unique que le système d’exploitation attribue à chaque fenêtre. Pour le système d’exploitation Windows, ce handle est une valeur entière qui sert de référence à une fenêtre spécifique.

Passthrough de compte Microsoft (MSA)

Les comptes Microsoft (MSA) sont des comptes personnels créés par des utilisateurs pour accéder aux services Microsoft. Le passthrough MSA est une configuration héritée qui permet aux utilisateurs d’obtenir des jetons pour des ressources qui n’acceptent normalement pas les connexions MSA. Cette fonctionnalité est uniquement disponible pour les applications internes. Les utilisateurs qui s’authentifient auprès d’une application configurée pour utiliser le passthrough MSA peuvent définir la InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled propriété sur true pour permettre à ces comptes personnels d’être répertoriés par WAM.

URI de redirection

Microsoft Entra applications s’appuient sur des URI de redirection pour déterminer où envoyer la réponse d’authentification une fois qu’un utilisateur s’est connecté. Pour activer l’authentification répartie via WAM, un URI de redirection correspondant au modèle suivant doit être inscrit dans l’application :

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Exemples

Configuration de pour InteractiveBrowserCredential utiliser le répartiteur d’authentification système

Cet exemple montre comment configurer avec le type InteractiveBrowserCredentialBrokerOptions d’options spécialisées pour activer l’authentification InteractiveBrowserCredential répartie.

IntPtr parentWindowHandle = GetForegroundWindow();

// Create an interactive browser credential which will use the system authentication broker
var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle));

// Use the credential to authenticate a secret client
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Dépannage

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.

Gestion des erreurs

Les erreurs résultant de l’authentification peuvent être déclenchées sur n’importe quelle méthode cliente de service qui effectue une demande au service. Cela est dû au fait que la première fois que le jeton est demandé à partir des informations d’identification se trouve lors du premier appel au service, et tous les appels suivants peuvent avoir besoin d’actualiser le jeton. Afin de distinguer ces échecs des échecs dans le client de service, les classes Azure Identity déclenchent le AuthenticationFailedException avec les détails sur la source de l’erreur dans le message d’exception, ainsi que éventuellement le message d’erreur. Selon l’application, ces erreurs peuvent ou non être récupérables.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Pour plus d’informations sur la gestion des erreurs résultant d’un échec de demandes d’ID Microsoft Entra ou de points de terminaison d’identité managée, reportez-vous à la documentation relative à l’ID de Microsoft Entra sur les codes d’erreur d’autorisation.

Journalisation

La bibliothèque d’identités Azure fournit les mêmes fonctionnalités de journalisation que le reste du Kit de développement logiciel (SDK) Azure.

La façon la plus simple de voir les journaux pour faciliter le débogage des problèmes d’authentification consiste à activer la journalisation de la console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Toutes les informations d’identification peuvent être configurées avec des options de diagnostic, de la même façon que d’autres clients dans le Kit de développement logiciel (SDK).

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

ATTENTION : Les demandes et les réponses dans la bibliothèque d’identités Azure contiennent des informations sensibles. Des précautions doivent être prises pour protéger les journaux lors de la personnalisation de la sortie afin d’éviter de compromettre la sécurité du compte.

Sécurité des threads

Nous garantissons que toutes les méthodes d’informations d’identification instance sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances d’informations d’identification est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du clientAccès à la réponse | Diagnostics | Moqueur | Durée de vie du client

Étapes suivantes

Bibliothèques clientes prenant en charge l’authentification avec Azure Identity

La plupart des bibliothèques clientes répertoriées ici prennent en charge l’authentification avec TokenCredential et la bibliothèque Azure Identity. Vous y trouverez également des liens où vous pouvez en savoir plus sur leur utilisation, notamment une documentation et des exemples supplémentaires.

Problèmes connus

Cette bibliothèque ne prend actuellement pas en charge les scénarios liés au service AAD B2C .

Les problèmes actuellement en cours pour la bibliothèque Azure.Identity se trouvent ici.

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.