Zugangsdatenketten in der Azure Identity-Bibliothek für Go

Die Azure Identity-Clientbibliothek stellt Anmeldeinformationen bereit – öffentliche Typen, die die TokenCredential-Schnittstelle der Azure Core-Bibliothek implementieren. Anmeldeinformationen stellen einen eindeutigen Authentifizierungsfluss zum Abrufen eines Zugriffstokens aus der Microsoft Entra-ID dar. Diese Anmeldedaten können miteinander verkettet werden, um eine geordnete Abfolge von Authentifizierungsmechanismen zu bilden, die versucht werden sollen.

Funktionsweise von verketteten Anmeldeinformationen

Zur Laufzeit versucht eine Anmeldeinformationskette, sich mit den ersten Anmeldeinformationen der Sequenz zu authentifizieren. Wenn diese Anmeldeinformationen kein Zugriffstoken abrufen, werden die nächsten Anmeldeinformationen in der Sequenz ausprobiert usw., bis erfolgreich ein Zugriffstoken abgerufen wurde. Das folgende Sequenzdiagramm veranschaulicht dieses Verhalten:

Gründe für die Verwendung von Berechtigungsketten

Verkettete Anmeldeinformationen können die folgenden Vorteile bieten:

• Umweltbewusstsein: Wählt automatisch die passendsten Zugangsdaten basierend auf der Umgebung aus, in der die App läuft. Ohne es müssten Sie Code wie diesen schreiben:

  // Set up credential based on environment (Azure or local development)
  if os.Getenv("WEBSITE_HOSTNAME") != "" {
      clientID := azidentity.ClientID("abcd1234-...")
      opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
      credential, err = azidentity.NewManagedIdentityCredential(&opts)
  
      if err != nil {
        // TODO: handle error
      }
  } else {
      // Use Azure CLI Credential
      credential, err = azidentity.NewAzureCLICredential(nil)
  
      if err != nil {
        // TODO: handle error
      }
  }
  

• Nahtlose Übergänge: Ihre App kann von der lokalen Entwicklung zu Ihrer Staging- oder Produktionsumgebung wechseln, ohne den Authentifizierungscode zu ändern.

• Verbesserte Resilienz: Enthält einen Fallbackmechanismus, der zu den nächsten Anmeldeinformationen wechselt, wenn die vorherigen keinen Zugriffstoken erhalten.

Auswählen der verketteten Anmeldeinformationen

Mit Go gibt es zwei Möglichkeiten für die Verkettung von Anmeldeinformationen:

• Vorkonfigurierte Kette verwenden: Verwenden Sie die vorkonfigurierte Kette, die DefaultAzureCredential vom Typ implementiert wird. Informationen zu diesem Ansatz finden Sie im Abschnitt DefaultAzureCredential-Übersicht.
• Erstellen einer benutzerdefinierten Anmeldeinformationskette: Beginnen Sie mit einer leeren Kette, und schließen Sie nur das ein, was Sie benötigen. Informationen zu diesem Ansatz finden Sie im Abschnitt ChainedTokenCredential-Übersicht.

Übersicht über DefaultAzureCredential

DefaultAzureCredential ist eine vorkonfigurierte Kette von Anmeldeinformationen. Es wurde entwickelt, um viele Umgebungen zusammen mit den am häufigsten verwendeten Authentifizierungsflüssen und Entwicklertools zu unterstützen. In grafischer Form sieht die zugrunde liegende Kette wie folgt aus:

Die Reihenfolge, in der DefaultAzureCredential, versucht, Anmeldeinformationen zu erhalten, folgt.

Auftrag	Berechtigung	Beschreibung
1	Umgebung.	Liest eine Auflistung von Umgebungsvariablen, um zu bestimmen, ob ein Anwendungsdienstprinzipal (Anwendungsbenutzer) für die App konfiguriert ist. Wenn ja, verwendet DefaultAzureCredential diese Werte, um die App bei Azure zu authentifizieren. Diese Methode wird am häufigsten in Serverumgebungen verwendet, kann aber auch bei der lokalen Entwicklung verwendet werden.
2	Workloadidentität	Wenn die App auf einem Azure-Host mit aktivierter Workload-Identität bereitgestellt wird, authentifizieren Sie dieses Konto.
3	Verwaltete Identität	Wenn die App auf einem Azure-Host mit aktivierter verwalteter Identität bereitgestellt wird, authentifizieren Sie die App mit dieser verwalteten Identität bei Azure.
4	Azure-Befehlszeilenschnittstelle	Wenn sich der Entwickler bei Azure mithilfe des befehls az login der Azure CLI authentifiziert hat, authentifizieren Sie die App mit demselben Konto bei Azure.
5	Azure Developer CLI	Wenn sich der Entwickler mit dem azd auth login-Befehl der Azure Developer CLI bei Azure authentifiziert hat, authentifizieren Sie sich mit diesem Konto.
6	Azure PowerShell	Wenn sich der Entwickler mit dem Cmdlet von Connect-AzAccount Azure PowerShell bei Azure authentifiziert hat, authentifizieren Sie sich mit diesem Konto.

In der einfachsten Form können Sie die parameterlose Version von DefaultAzureCredential wie folgt verwenden:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

So passen Sie DefaultAzureCredential an

In den folgenden Abschnitten werden Strategien zum Steuern beschrieben, welche Anmeldeinformationen in der Kette enthalten sind.

Ausschließen einer Kategorie des Anmeldeinformationstyps

Um alle Developer tool oder Deployed service Anmeldeinformationen auszuschließen, setzen Sie die Umgebungsvariable AZURE_TOKEN_CREDENTIALS auf prod bzw. dev. Wenn ein Wert prod verwendet wird, sieht die zugrunde liegende Anmeldeinformationskette wie folgt aus:

Diagramm, das DefaultAzureCredential zeigt, wobei AZURE_TOKEN_CREDENTIALS auf "prod" festgelegt sind.

Wenn ein Wert dev verwendet wird, sieht die Kette wie folgt aus:

Diagramm, das zeigt, dass DefaultAzureCredential mit AZURE_TOKEN_CREDENTIALS auf "dev" gesetzt ist.

Von Bedeutung

Die AZURE_TOKEN_CREDENTIALS Umgebungsvariable wird in azidentity Modulversionen 1.10.0 und höher unterstützt.

Um sicherzustellen, dass die Umgebungsvariable definiert ist, legen Sie die Option RequireAzureTokenCredentials auf :true

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

Verwenden einer bestimmten Anmeldeinformation

Um alle Anmeldeinformationen außer einem auszuschließen, legen Sie die Umgebungsvariable AZURE_TOKEN_CREDENTIALS auf den Anmeldeinformationsnamen fest. Sie können beispielsweise die DefaultAzureCredential Kette AzureCLICredential reduzieren, indem Sie auf ".AZURE_TOKEN_CREDENTIALSAzureCLICredential Der Zeichenfolgenvergleich wird ohne Groß-/Kleinschreibung durchgeführt. Gültige Zeichenfolgenwerte für die Umgebungsvariable sind:

• AzureCLICredential
• AzureDeveloperCLICredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Von Bedeutung

Die Umgebungsvariable AZURE_TOKEN_CREDENTIALS unterstützt einzelne Anmeldeinformationsnamen in azidentity Modulversionen 1.11.0 und höher.

Um sicherzustellen, dass die Umgebungsvariable definiert ist, legen Sie die Option RequireAzureTokenCredentials auf :true

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

Übersicht über ChainedTokenCredential

ChainedTokenCredential ist eine leere Kette, der Sie den Anforderungen Ihrer App entsprechende Anmeldeinformationen hinzufügen. Zum Beispiel:

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

azdCLI, err := azidentity.NewAzureDeveloperCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{azCLI, azdCLI}, nil)
if err != nil {
  // handle error
}

Im vorherigen Codebeispiel wird eine maßgeschneiderte Anmeldeinformationskette erstellt, die aus zwei Anmeldeinformationen besteht. AzureCLICredential wird zuerst versucht, gegebenenfalls gefolgt von AzureDeveloperCLICredential. In grafischer Form sieht die Kette wie folgt aus:

Tipp

Um die Leistung zu verbessern, optimieren Sie die Sortierung von Anmeldeinformationen in ChainedTokenCredential von den meisten bis zu den am wenigsten verwendeten Anmeldeinformationen.

Verwendungsleitfaden für DefaultAzureCredential

DefaultAzureCredential ist zweifellos die einfachste Möglichkeit, mit der Azure Identity-Bibliothek zu beginnen, aber mit diesem Komfort kommt es zu Kompromissen. Nachdem Sie Ihre App in Azure bereitgestellt haben, sollten Sie die Authentifizierungsanforderungen der App verstehen. Ersetzen Sie aus diesem Grund DefaultAzureCredential durch eine bestimmte TokenCredential Implementierung, z. B. ManagedIdentityCredential.

Hier ist der Grund:

• Debugging-Herausforderungen: Wenn die Authentifizierung fehlschlägt, kann es schwierig sein, die beleidigenden Anmeldeinformationen zu debuggen und zu identifizieren. Sie müssen die Protokollierung aktivieren, um den Fortschritt von einer Anmeldeinformation zum nächsten sowie den Status „Erfolg/Fehler“ der einzelnen Anmeldeinformationen anzuzeigen. Weitere Informationen finden Sie unter Debuggen verketteter Anmeldeinformationen.
• Leistungsaufwand: Der Prozess des sequenziellen Ausprobierens mehrerer Anmeldeinformationen kann Leistungseinbußen verursachen. Wenn sie beispielsweise auf einem lokalen Entwicklungscomputer ausgeführt wird, ist die verwaltete Identität nicht verfügbar. Daher schlägt ManagedIdentityCredential in der lokalen Entwicklungsumgebung imme fehl, es sei denn, dies ist explizit über die entsprechende Eigenschaft mit demexclude-Präfix deaktiviert.
• Unvorhersehbares Verhalten: DefaultAzureCredential überprüft das Vorhandensein bestimmter Umgebungsvariablen. Es ist möglich, dass jemand diese Umgebungsvariablen auf der Systemebene auf dem Hostcomputer hinzufügen oder ändern kann. Diese Änderungen gelten global und ändern daher das Verhalten von DefaultAzureCredential zur Laufzeit in jeder App, die auf diesem Computer ausgeführt wird.

Debuggen von verketteten Anmeldeinformationen

Um ein unerwartetes Problem zu diagnostizieren oder zu verstehen, was verkettete Anmeldeinformationen tun, aktivieren Sie die Protokollierung in Ihrer App. Filtern Sie die Protokolle optional nur auf die Ereignisse, die aus der Azure Identity-Clientbibliothek ausgegeben werden. Zum Beispiel:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Anweisungen zum Beheben von Fehlern bei bestimmten Anmeldeinformationstypen finden Sie in der Anleitung zur Problembehandlung.