Azure Identity Brokered Authentication-Clientbibliothek für .NET – Version 1.0.0

  • Artikel

Die Bibliothek erweitert die Azure.Identity-Bibliothek, um Unterstützung für den Authentifizierungsbroker bereitzustellen. Sie enthält die erforderlichen Abhängigkeiten und stellt die InteractiveBrowserCredentialBrokerOptions -Klasse bereit. Diese Optionsklasse kann verwendet werden, um einen InteractiveBrowserCredential zu erstellen, der den Systemauthentifizierungsbroker anstelle des Systembrowsers verwenden kann, sofern verfügbar.

Quellcode | Paket (Nuget) | API-Referenzdokumentation | Dokumentation zur Microsoft Entra ID

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Identity-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Identity.Broker

Voraussetzungen

Authentifizieren des Clients

Wichtige Begriffe

Dieses Paket ermöglicht die Unterstützung des Authentifizierungsbrokers über InteractiveBrowserCredentialBrokerOptionsin Kombination mit InteractiveBrowserCredential im Azure.Identity Paket.

Übergeordnete Fensterhandle

Bei der interaktiven Authentifizierung über InteractiveBrowserCredential mit konstruiertem InteractiveBrowserCredentialBrokerOptionsist ein übergeordnetes Fensterhandle erforderlich, um sicherzustellen, dass das Authentifizierungsdialogfeld über das anfordernde Fenster ordnungsgemäß angezeigt wird. Im Kontext grafischer Benutzeroberflächen auf Geräten ist ein Fensterhandle ein eindeutiger Bezeichner, den das Betriebssystem jedem Fenster zuweist. Für das Windows-Betriebssystem ist dieses Handle ein ganzzahliger Wert, der als Verweis auf ein bestimmtes Fenster dient.

Passthrough für Microsoft-Konto (MSA)

Microsoft-Konten (MSA) sind persönliche Konten, die von Benutzern für den Zugriff auf Microsoft-Dienste erstellt werden. MSA-Passthrough ist eine Legacykonfiguration, mit der Benutzer Token an Ressourcen abrufen können, die normalerweise keine MSA-Anmeldungen akzeptieren. Dieses Feature ist nur für Erstanbieteranwendungen verfügbar. Benutzer, die sich bei einer Anwendung authentifizieren, die für die Verwendung von MSA-Passthrough konfiguriert ist, können die InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled -Eigenschaft auf true festlegen, damit diese persönlichen Konten von WAM aufgelistet werden können.

Umleitungs-URIs

Microsoft Entra Anwendungen basieren auf Umleitungs-URIs, um zu bestimmen, wohin die Authentifizierungsantwort gesendet werden soll, nachdem sich ein Benutzer angemeldet hat. Um die Brokerauthentifizierung über WAM zu aktivieren, sollte ein Umleitungs-URI, der dem folgenden Muster entspricht, bei der Anwendung registriert werden:

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

Beispiele

Konfigurieren des InteractiveBrowserCredential für die Verwendung des Systemauthentifizierungsbrokers

In diesem Beispiel wird veranschaulicht, wie InteractiveBrowserCredential sie mit dem spezialisierten Optionstyp InteractiveBrowserCredentialBrokerOptions konfiguriert wird, um die Brokerauthentifizierung zu aktivieren.

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

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im Leitfaden zur Problembehandlung .

Fehlerbehandlung

Fehler, die aus der Authentifizierung entstehen, können für jede Dienstclientmethode ausgelöst werden, die eine Anforderung an den Dienst sendet. Dies liegt daran, dass das Token beim ersten Aufruf des Diensts zum ersten Mal von den Anmeldeinformationen angefordert wird, und alle nachfolgenden Aufrufe das Token möglicherweise aktualisieren müssen. Um diese Fehler von Fehlern im Dienstclient zu unterscheiden, führen Azure Identity-Klassen mit AuthenticationFailedException Details zur Fehlerquelle in der Ausnahmemeldung sowie möglicherweise der Fehlermeldung aus. Je nach Anwendung können diese Fehler möglicherweise nicht wiederhergestellt werden.

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}");
}

Weitere Informationen zum Umgang mit Fehlern, die sich aus fehlerhaften Anforderungen an Microsoft Entra-ID oder verwaltete Identitätsendpunkte ergeben, finden Sie in der dokumentation Microsoft Entra ID zu Autorisierungsfehlercodes.

Protokollierung

Die Azure Identity-Bibliothek bietet dieselben Protokollierungsfunktionen wie der Rest des Azure SDK.

Die einfachste Möglichkeit, die Protokolle zum Debuggen von Authentifizierungsproblemen anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren.

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

Alle Anmeldeinformationen können mit Diagnoseoptionen konfiguriert werden, auf die gleiche Weise wie andere Clients im SDK.

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

ACHTUNG: Anforderungen und Antworten in der Azure Identity-Bibliothek enthalten vertrauliche Informationen. Beim Anpassen der Ausgabe müssen Vorkehrungen getroffen werden, um Protokolle zu schützen, um die Kontosicherheit zu vermeiden.

Threadsicherheit

Wir garantieren, dass alle Anmeldeinformationen instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung der Wiederverwendung von Anmeldeinformationsinstanzen immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Diagnose | Spott | Clientlebensdauer

Nächste Schritte

Clientbibliotheken, die die Authentifizierung mit Azure Identity unterstützen

Viele der hier aufgeführten Clientbibliotheken unterstützen die Authentifizierung mit TokenCredential und der Azure Identity-Bibliothek. Dort finden Sie auch Links, in denen Sie mehr über deren Verwendung erfahren können, einschließlich zusätzlicher Dokumentation und Beispiele.

Bekannte Probleme

Diese Bibliothek unterstützt derzeit keine Szenarien im Zusammenhang mit dem AAD B2C-Dienst .

Derzeit offene Probleme für die Azure.Identity-Bibliothek finden Sie hier.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe