Azure Identity-Clientbibliothek für .NET– Version 1.10.3

Die Azure Identity-Bibliothek bietet unterstützung für die Tokenauthentifizierung Microsoft Entra ID (früher Azure Active Directory) im Azure SDK. Es bietet eine Reihe von Implementierungen, die zum Erstellen von TokenCredential Azure SDK-Clients verwendet werden können, die Microsoft Entra Tokenauthentifizierung unterstützen.

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

Voraussetzungen

• Ein Azure-Abonnement.
• Die Azure CLI kann auch für die Authentifizierung in einer Entwicklungsumgebung, das Erstellen von Konten und das Verwalten von Kontorollen nützlich sein.

Authentifizieren des Clients

Beim lokalen Debuggen und Ausführen von Code ist es typisch, dass entwickler ihr eigenes Konto verwenden, um Aufrufe von Azure-Diensten zu authentifizieren. Es gibt mehrere Entwicklertools, die verwendet werden können, um diese Authentifizierung in Ihrer Entwicklungsumgebung auszuführen.

Authentifizieren über Visual Studio

Entwickler, die Visual Studio 2017 oder höher verwenden, können ein Microsoft Entra Konto über die IDE authentifizieren. Anwendungen, die DefaultAzureCredential oder VisualStudioCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Um sich in Visual Studio zu authentifizieren, wählen Sie das Menü Extras>Optionen aus, um das Dialogfeld Optionen zu starten. Navigieren Sie dann zu den Azure Service Authentication Optionen, mit denen Sie sich mit Ihrem Microsoft Entra-Konto anmelden können.

Authentifizieren über Visual Studio Code

Entwickler, die Visual Studio Code verwenden, können die Azure-Kontoerweiterung verwenden, um sich über den Editor zu authentifizieren. Anwendungen, die DefaultAzureCredential oder VisualStudioCodeCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Es handelt sich um ein bekanntes Problem , das VisualStudioCodeCredential mit Azure-Kontoerweiterungsversionen neuer als 0.9.11 nicht funktioniert. Eine langfristige Lösung dieses Problems wird ausgeführt. In der Zwischenzeit sollten Sie sich über die Azure CLI authentifizieren.

Authentifizieren über die Azure CLI

Entwickler, die außerhalb einer IDE programmieren, können auch die Azure CLI zur Authentifizierung verwenden. Anwendungen, die DefaultAzureCredential oder AzureCliCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Zur Authentifizierung mit der Azure CLI können Benutzer den Befehl az loginausführen. Für Benutzer, die auf einem System mit einem Standardwebbrowser ausgeführt werden, startet die Azure CLI den Browser, um den Benutzer zu authentifizieren.

Für Systeme ohne Standardwebbrowser verwendet der az login-Befehl den Gerätecode-Authentifizierungsfluss. Der Benutzer kann durch Angeben des Arguments --use-device-code auch erzwingen, dass die Azure CLI den Gerätecodefluss verwendet, anstatt einen Browser zu starten.

Authentifizieren über die Azure Developer CLI

Entwickler, die außerhalb einer IDE programmieren, können auch die Azure Developer CLI verwenden, um sich zu authentifizieren. Anwendungen, die DefaultAzureCredential oder AzureDeveloperCliCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Um sich beim Azure Developer CLI zu authentifizieren, können Benutzer den Befehl azd auth loginausführen. Für Benutzer, die auf einem System mit einem Standardwebbrowser ausgeführt werden, startet die Azure Developer CLI den Browser, um den Benutzer zu authentifizieren.

Für Systeme ohne Standardwebbrowser verwendet der azd auth login --use-device-code-Befehl den Gerätecode-Authentifizierungsfluss.

Authentifizieren über Azure PowerShell

Entwickler, die außerhalb einer IDE programmieren, können auch Azure PowerShell zur Authentifizierung verwenden. Anwendungen, die DefaultAzureCredential oder AzurePowerShellCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Um sich bei Azure PowerShell zu authentifizieren, können Benutzer den Befehl Connect-AzAccountausführen. Für Benutzer, die auf einem System mit einem Standardwebbrowser und Version 5.0.0 oder höher von Azure PowerShell ausgeführt werden, wird der Browser gestartet, um den Benutzer zu authentifizieren.

Für Systeme ohne Standardwebbrowser verwendet der Connect-AzAccount-Befehl den Gerätecode-Authentifizierungsfluss. Der Benutzer kann auch erzwingen, dass Azure PowerShell den Gerätecodeflow verwendet, anstatt einen Browser zu starten, indem er das UseDeviceAuthentication Argument angibt.

Wichtige Begriffe

Anmeldeinformationen

Bei den Anmeldeinformationen handelt es sich um eine Klasse, die die Daten enthält oder abrufen kann, die für einen Dienstclient zum Authentifizieren von Anforderungen erforderlich sind. Dienstclients im azure SDK akzeptieren Anmeldeinformationen, wenn sie erstellt werden. Dienstclients verwenden diese Anmeldeinformationen, um Anforderungen an den Dienst zu authentifizieren.

Die Azure Identity-Bibliothek konzentriert sich auf die OAuth-Authentifizierung mit Microsoft Entra ID und bietet eine Vielzahl von Anmeldeinformationsklassen, die ein Microsoft Entra Token zum Authentifizieren von Dienstanforderungen abrufen können. Alle Anmeldeinformationsklassen in dieser Bibliothek sind Implementierungen der TokenCredential abstrakten Klasse in Azure.Core, und jede dieser Klassen kann verwendet werden, um Dienstclients zu erstellen, die sich mit authentifizieren TokenCredentialkönnen.

Eine vollständige Liste der verfügbaren Anmeldeinformationstypen finden Sie unter Anmeldeinformationsklassen .

DefaultAzureCredential

eignet DefaultAzureCredential sich für die meisten Szenarien, in denen die Anwendung letztendlich in Azure ausgeführt werden soll. Der Grund ist, dass DefaultAzureCredential Anmeldeinformationen, die bei der Bereitstellung zur Authentifizierung genutzt werden, mit Anmeldeinformationen kombiniert, die zur Authentifizierung in einer Entwicklungsumgebung dienen.

Hinweis: DefaultAzureCredential Soll den Einstieg in das SDK vereinfachen, indem gängige Szenarien mit vernünftigen Standardverhalten behandelt werden. Entwickler, die mehr Kontrolle wünschen oder deren Szenario von den Standardeinstellungen nicht abgedeckt wird, sollten andere Anmeldeinformationstypen verwenden.

DefaultAzureCredential versucht, sich mithilfe der folgenden Mechanismen in der angegebenen Reihenfolge zu authentifizieren, und wird beendet, wenn die Authentifizierung erfolgreich ist:

1. Umgebung : Liest DefaultAzureCredential Kontoinformationen, die über Umgebungsvariablen angegeben wurden, und verwendet sie für die Authentifizierung.
2. Workloadidentität : Wenn die Anwendung auf einem Azure-Host mit aktivierter Workloadidentität bereitgestellt wird, authentifiziert sich mit DefaultAzureCredential diesem Konto.
3. Verwaltete Identität : Wenn die Anwendung auf einem Azure-Host mit aktivierter verwalteter Identität bereitgestellt wird, authentifiziert sich mit DefaultAzureCredential diesem Konto.
4. Visual Studio : Wenn sich der Entwickler über Visual Studio authentifiziert hat, authentifiziert sich mit DefaultAzureCredential diesem Konto.
5. Visual Studio Code : Derzeit standardmäßig ausgeschlossen, da die SDK-Authentifizierung über Visual Studio Code aufgrund des Problems #27263 nicht funktioniert. Die VisualStudioCodeCredential wird im DefaultAzureCredential Flow erneut aktiviert, sobald eine Korrektur vorhanden ist. In Issue #30525 wird dies nachverfolgt. In der Zwischenzeit können Visual Studio Code-Benutzer ihre Entwicklungsumgebung mithilfe der Azure CLI authentifizieren.
6. Azure CLI : Wenn der Entwickler ein Konto über den Azure CLI-Befehl az login authentifiziert hat, authentifiziert sich mit DefaultAzureCredential diesem Konto.
7. Azure PowerShell: Wenn der Entwickler ein Konto über den Befehl Azure PowerShell Connect-AzAccount authentifiziert hat, authentifiziert sich der DefaultAzureCredential mit diesem Konto.
8. Azure Developer CLI: Wenn sich der Entwickler über den Befehl Azure Developer CLI azd auth login authentifiziert hat, authentifiziert sich der DefaultAzureCredential bei diesem Konto.
9. Interaktiver Browser: Falls aktiviert, wird der Entwickler von DefaultAzureCredential interaktiv über den Standardbrowser des aktuellen Systems authentifiziert. Dieser Anmeldeinformationstyp ist standardmäßig deaktiviert.

Fortsetzungsrichtlinie

Ab Version 1.10.1 versucht, sich mit allen Anmeldeinformationen für Entwickler zu authentifizieren, DefaultAzureCredential bis eine erfolgreich ist, unabhängig von fehlern, die früheren Entwickleranmeldeinformationen aufgetreten sind. Beispielsweise kann ein Entwickleranmeldeinformation versuchen, ein Token abzurufen, und schlägt fehl. DefaultAzureCredential Daher werden die nächsten Anmeldeinformationen im Flow fortgesetzt. Bereitgestellte Dienstanmeldeinformationen beenden den Flow mit einer ausgelösten Ausnahme, wenn sie versuchen können, Token abzurufen, aber keine empfangen. Vor Version 1.10.1 haben Entwickleranmeldeinformationen den Authentifizierungsfluss ebenfalls beendet, wenn der Tokenabruf fehlgeschlagen ist.

Dieses Verhalten ermöglicht es, alle Entwickleranmeldeinformationen auf Ihrem Computer zu testen, während das bereitgestellte Verhalten vorhersagbar ist.

Beispiele

Authentifizieren mit DefaultAzureCredential

Dieses Beispiel zeigt, wie SecretClient über die azure-security-keyvault-secrets-Clientbibliothek mithilfe von DefaultAzureCredential authentifiziert wird.

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

Aktivieren der interaktiven Authentifizierung mit DefaultAzureCredential

Die interaktive Authentifizierung ist in standardmäßig DefaultAzureCredential deaktiviert. In diesem Beispiel werden zwei Möglichkeiten zum Aktivieren des interaktiven Authentifizierungsteils von DefaultAzureCredentialveranschaulicht. Wenn aktiviert, wird auf DefaultAzureCredential die interaktive Authentifizierung des Entwicklers über den Standardbrowser des Systems zurückgegriffen, wenn keine anderen Anmeldeinformationen verfügbar sind. In diesem Beispiel wird dann eine EventHubProducerClient aus der Azure.Messaging.EventHubs-Clientbibliothek mit DefaultAzureCredential aktivierter interaktiver Authentifizierung authentifiziert.

// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Angeben einer benutzerseitig zugewiesenen verwalteten Identität mit DefaultAzureCredential

Viele Azure-Hosts ermöglichen die Zuweisung einer benutzerseitig zugewiesenen verwalteten Identität. Dieses Beispiel veranschaulicht, wie DefaultAzureCredential konfiguriert wird, um eine benutzerseitig zugewiesene Identität bei der Bereitstellung auf einem Azure-Host zu authentifizieren. Anschließend wird BlobClient über die Azure.Storage.Blobs-Clientbibliothek mit Anmeldeinformationen authentifiziert.

// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.

string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

Zusätzlich zum Konfigurieren des ManagedIdentityClientId über Code kann er auch mithilfe der Umgebungsvariablen AZURE_CLIENT_ID festgelegt werden. Diese beiden Ansätze sind bei Verwendung von DefaultAzureCredentialgleichwertig.

Definieren eines benutzerdefinierten Authentifizierungsflusses mit ChainedTokenCredential

DefaultAzureCredential ist zwar im Allgemeinen die schnellste Möglichkeit, mit der Entwicklung von Anwendungen für Azure zu beginnen, erfahrenere Benutzer möchten aber möglicherweise die Anmeldeinformationen anpassen, die bei der Authentifizierung berücksichtigt werden. Mit ChainedTokenCredential können Benutzer mehrere Anmeldeinformationeninstanzen kombinieren, um eine angepasste Kette von Anmeldeinformationen zu definieren. In diesem Beispiel wird das Erstellen eines ChainedTokenCredential veranschaulicht, bei dem versucht wird, sich mithilfe einer verwalteten Identität zu authentifizieren, und ein Fallback auf die Authentifizierung über die Azure CLI erfolgt, wenn die verwaltete Identität in der aktuellen Umgebung nicht verfügbar ist. Anschließend werden die Anmeldeinformationen verwendet, um EventHubProducerClient über die Azure.Messaging.EventHubs-Clientbibliothek zu authentifizieren.

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

var credential = new ChainedTokenCredential(new ManagedIdentityCredential(), new AzureCliCredential());

var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Unterstützung verwalteter Identitäten

Die Authentifizierung verwalteter Identitäten wird entweder über oder DefaultAzureCredentialManagedIdentityCredential direkt für die folgenden Azure-Dienste unterstützt:

• Azure App Service und Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Dokumentation zu virtuellen Computern
• Azure-VM-Skalierungsgruppen

Beispiele

Diese Beispiele veranschaulichen die SecretClient Authentifizierung von aus der Azure.Security.KeyVault.Secrets-Clientbibliothek mithilfe von ManagedIdentityCredential.

Authentifizieren mit einer benutzerseitig zugewiesenen verwalteten Identität

var credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Authentifizieren mit einer systemseitig zugewiesenen verwalteten Identität

var credential = new ManagedIdentityCredential();
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Cloudkonfiguration

Anmeldeinformationen werden standardmäßig beim Microsoft Entra-Endpunkt für die öffentliche Azure-Cloud authentifiziert. Um auf Ressourcen in anderen Clouds wie Azure Government oder einer privaten Cloud zuzugreifen, konfigurieren Sie Anmeldeinformationen mit dem AuthorityHost Argument. AzureAuthorityHosts definiert Autoritäten für bekannte Clouds:

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { AuthorityHost = AzureAuthorityHosts.AzureGovernment });

Nicht für alle Anmeldeinformationen ist diese Konfiguration erforderlich. Anmeldeinformationen, die sich über ein Entwicklungstool authentifizieren, z AzureCliCredential. B. , verwenden die Konfiguration dieses Tools.

Anmeldeinformationsklassen

Authentifizieren von azure gehosteten Anwendungen

Authentifizieren von Dienstprinzipalen

Authentifizieren von Benutzern

Authentifizieren über Entwicklungstools

Hinweis: Alle Implementierungen von Anmeldeinformationen in der Azure Identity-Bibliothek sind threadsicher, und ein einzelner instance für Anmeldeinformationen kann von mehreren Dienstclients verwendet werden.

Umgebungsvariablen

DefaultAzureCredential und EnvironmentCredential können mit Umgebungsvariablen konfiguriert werden. Jeder Authentifizierungstyp erfordert Werte für bestimmte Variablen:

Dienstprinzipal mit Geheimnis

Dienstprinzipal mit Zertifikat

Benutzername und Kennwort

Die Konfiguration wird in der oben genannten Reihenfolge versucht. Wenn zum Beispiel sowohl Werte für ein Clientgeheimnis als auch für ein Zertifikat vorhanden sind, wird das Clientgeheimnis verwendet.

Fortlaufende Zugriffsevaluierung

Ab Version 1.10.0 ist der Zugriff auf Ressourcen, die durch continuous Access Evaluation (CAE) geschützt sind, auf Anforderungsbasis möglich. Dieses Verhalten kann durch Festlegen der -Eigenschaft von TokenRequestContext über den IsCaeEnabled zugehörigen Konstruktor aktiviert werden. CAE wird für Anmeldeinformationen für Entwickler und verwaltete Identitäten nicht unterstützt.

Zwischenspeichern von Tokens

Tokenzwischenspeicherung ist ein Feature, das von der Azure Identity-Bibliothek bereitgestellt wird und Apps Folgendes ermöglicht:

• Cachetoken im Arbeitsspeicher (Standard) oder auf dem Datenträger (opt-in).
• Verbessern sie Resilienz und Leistung.
• Verringern Sie die Anzahl von Anforderungen, die an Microsoft Entra ID zum Abrufen von Zugriffstoken gesendet werden.

Die Azure Identity-Bibliothek bietet sowohl In-Memory- als auch persistente Datenträgerzwischenspeicherung. Weitere Informationen finden Sie in der Dokumentation zur Tokenzwischenspeicherung.

Problembehandlung

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

Fehlerbehandlung

Fehler, die sich aus der Authentifizierung ergeben, 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 angefordert wird, und alle nachfolgenden Aufrufe möglicherweise das Token aktualisieren müssen. Um diese Fehler von Fehlern im Dienstclient zu unterscheiden, lösen Azure Identity-Klassen den AuthenticationFailedException mit Details zur Fehlerquelle in der Ausnahmemeldung sowie möglicherweise der Fehlermeldung aus. Je nach Anwendung können diese Fehler möglicherweise 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 fehlgeschlagenen Anforderungen an Microsoft Entra ID- oder verwaltete Identitätsendpunkte ergeben, finden Sie in der Microsoft Entra-ID-Dokumentation zu Autorisierungsfehlercodes.

Protokollierung

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

Die einfachste Möglichkeit, die Protokolle anzuzeigen, um Authentifizierungsprobleme zu debuggen, besteht darin, die Konsolenprotokollierung zu aktivieren.

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

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

VORSICHT: 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 eine Beeinträchtigung der Kontosicherheit zu vermeiden.

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

Bei der Behandlung von Authentifizierungsproblemen können Sie auch die Protokollierung vertraulicher Informationen aktivieren. Um diesen Protokollierungstyp zu aktivieren, legen Sie die IsLoggingContentEnabled -Eigenschaft auf fest true. Um nur Details zu dem Konto zu protokollieren, das für den Authentifizierungs- und Autorisierungsversuch verwendet wurde, legen Sie auf fest IsAccountIdentifierLoggingEnabledtrue.

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

Threadsicherheit

Wir garantieren, dass alle Anmeldeinformationen instance Methoden threadsicher und voneinander unabhängig sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Anmeldeinformationsinstanzen wiederzuverwenden, 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, über die Sie mehr über ihre Verwendung erfahren können, einschließlich zusätzlicher Dokumentation und Beispiele.

Bekannte Probleme

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

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.