Verwenden von kubelogin zur Authentifizierung von Benutzerinnen und Benutzern in Azure Kubernetes Service

  • Artikel

Das kubelogin-Plug-In in Azure ist ein Plug-In für Client-Go-Anmeldeinformationen, das die Microsoft Entra ID-Authentifizierung implementiert. Das kubelogin-Plug-In bietet Features, die im kubectl-Befehlszeilentool nicht verfügbar sind.

Azure Kubernetes Service(AKS)-Cluster, die in Microsoft Entra ID integriert sind und Kubernetes-Version 1.24 und höher ausführen, verwenden automatisch das kubelogin-Format.

Dieser Artikel enthält eine Übersicht und Beispiele dafür, wie Sie kubelogin für alle unterstützten Microsoft Entra-Authentifizierungsmethoden in AKS verwenden.

Begrenzungen

  • Sie können maximal 200 Gruppen in einem JSON Web Token (JWT)-Anspruch von Microsoft Entra ID einschließen. Wenn Sie mehr als 200 Gruppen haben, sollten Sie die Verwendung von Anwendungsrollen in Erwägung ziehen.
  • Gruppen, die in Microsoft Entra ID erstellt wurden, werden nur durch den Wert ihrer ObjectID und nicht durch ihren Anzeigenamen eingeschlossen. Der Befehl sAMAccountName ist nur für Gruppen verfügbar, die über lokales Windows Server Active Directory synchronisiert werden.
  • Bei AKS funktioniert die Dienstprinzipal-Authentifizierungsmethode nur mit verwaltetem Microsoft Entra ID und nicht mit der früheren Version Azure Active Directory.
  • Die Gerätecode-Authentifizierungsmethode funktioniert nicht, wenn eine Richtlinie für bedingten Zugriff von Microsoft Entra auf einen Microsoft Entra-Mandanten festgelegt ist. Verwenden Sie in diesem Szenario die Authentifizierung mit dem interaktiven Webbrowser.

Funktionsweise der Authentifizierung

Für die meisten Interaktionen mit kubelogin verwenden Sie den Unterbefehl convert-kubeconfig. Der Unterbefehl verwendet die kubeconfig-Datei, die in --kubeconfig oder in der Umgebungsvariable KUBECONFIG angegeben ist, um die endgültige kubeconfig-Datei basierend auf der angegebenen Authentifizierungsmethode in das exec-Format zu konvertieren.

Die Authentifizierungsmethoden, die kubelogin implementiert, sind OAuth 2.0-Tokenzuteilungs-Flows von Microsoft Entra. Die folgenden Parameterkennzeichnungen werden häufig in kubelogin-Unterbefehlen verwendet. Im Allgemeinen sind diese Flags bereit zur Benutzung, wenn Sie die kubeconfig-Datei über AKS abrufen.

  • --tenant-id: Die Microsoft Entra Mandanten-ID.
  • --client-id: Die Anwendungs-ID der öffentlichen Clientanwendung. Diese Client-App wird nur bei den Anmeldemethoden Gerätecode, Webbrowser interaktiv und OAuth 2.0 Resource Owner Password Credentials (ROPC) (Workflow-Identität) verwendet.
  • --server-id: Die Anwendungs-ID der Web-App oder des Ressourcenservers. Das Token wird für diese Ressource ausgegeben.

Hinweis

Das Token wird bei keiner Authentifizierungsmethode im Dateisystem zwischengespeichert.

Authentifizierungsmethoden

In den nächsten Abschnitten werden unterstützte Authentifizierungsmethoden und deren Verwendung beschrieben:

  • Gerätecode
  • Azure CLI
  • Webbrowser interaktiv
  • Dienstprinzipal
  • Verwaltete Identität
  • Workloadidentität

Gerätecode

Der Gerätecode ist die Standardauthentifizierungsmethode für den Unterbefehl convert-kubeconfig. Das -l devicecode ist optional. Bei dieser Authentifizierungsmethode wird der Gerätecode abgefragt, damit sich die Benutzerinnen und Benutzer über eine Browsersitzung anmelden können.

Bevor die kubelogin- und exec-Plug-Ins eingeführt wurden, unterstützte die Azure-Authentifizierungsmethode in kubectl nur den Gerätecode-Flow. Es wurde eine frühere Version einer Bibliothek verwendet, die ein Token erzeugt, das den audience-Anspruch mit einem spn:-Präfix aufweist. Es ist nicht kompatibel mit von AKS verwaltetem Microsoft Entra ID, das einen im Auftrag von (on-behalf-of, OBO) Fluss verwendet. Wenn Sie den Unterbefehl convert-kubeconfig ausführen, entfernt kubelogin das Präfix spn: vom Zielgruppenanspruch.

Wenn Ihre Anforderungen die Verwendung von Funktionen aus früheren Versionen beinhalten, fügen Sie das Argument --legacy hinzu. Wenn Sie die kubeconfig-Datei in einem früheren Azure Active Directory-Cluster verwenden, fügt kubelogin automatisch das Flag --legacy hinzu.

Bei dieser Anmeldemethode werden das Zugriffstoken und das Aktualisierungstoken im Verzeichnis ${HOME}/.kube/cache/kubelogin zwischengespeichert. Verwenden Sie den Parameter --token-cache-dir, um diese Einstellung zu überschreiben.

Wenn Ihr integrierter AKS Microsoft Entra-Cluster Kubernetes 1.24 oder früher verwendet, müssen Sie das kubeconfig-Dateiformat manuell konvertieren, indem Sie die folgenden Befehle ausführen:

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Führen Sie zum Bereinigen der zwischengespeicherten Token den folgenden Befehl aus:

kubelogin remove-tokens

Hinweis

Die Gerätecode-Anmeldemethode funktioniert nicht, wenn die Richtlinie für bedingten Zugriff in einem Microsoft Entra-Mandanten konfiguriert ist. Verwenden Sie in diesem Szenario die Methode Webbrowser interaktiv.

Azure CLI

Die Azure CLI-Authentifizierungsmethode verwendet den angemeldeten Kontext, den die Azure CLI zum Abrufen des Zugriffstokens herstellt. Das Token wird im selben Microsoft Entra-Mandanten wie az login ausgegeben. Kubelogin schreibt keine Token in die Tokencachedatei, da sie bereits von der Azure CLI verwaltet werden.

Hinweis

Diese Authentifizierungsmethode funktioniert nur mit dem von AKS verwalteten Microsoft Entra ID.

Das folgende Beispiel zeigt, wie Sie die Azure CLI-Methode verwenden, um sich zu authentifizieren:

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Wenn sich das Azure CLI-Konfigurationsverzeichnis außerhalb des Verzeichnisses ${HOME} befindet, geben Sie den Parameter --azure-config-dir mit dem Unterbefehl convert-kubeconfig an. Der Befehl generiert die kubeconfig-Datei mit der konfigurierten Umgebungsvariable. Sie können dieselbe Konfiguration erhalten, indem Sie die Umgebungsvariable AZURE_CONFIG_DIR auf dieses Verzeichnis festlegen, wenn Sie den kubectl-Befehl ausführen.

Webbrowser interaktiv

Die Authentifizierungsmethode Webbrowser interaktiv öffnet automatisch einen Webbrowser zur Anmeldung der Benutzerin bzw. des Benutzers. Nachdem die Benutzerin bzw. der Benutzer authentifiziert wurde, leitet der Browser mithilfe der überprüften Anmeldeinformationen an den lokalen Webserver um. Diese Authentifizierungsmethode entspricht der Richtlinie für bedingten Zugriff.

Wenn Sie sich mithilfe dieser Methode authentifizieren, wird das Zugriffstoken im Verzeichnis ${HOME}/.kube/cache/kubelogin zwischengespeichert. Sie können diesen Pfad mit dem Parameter --token-cache-dir überschreiben.

Bearer token

Das folgende Beispiel zeigt, wie Sie ein Bearertoken mit interaktivem Flow des Webbrowsers verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Besitznachweistoken (Proof-of-Possession, PoP)

Das folgende Beispiel zeigt, wie Sie ein PoP-Token mit interaktivem Flow verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Dienstprinzipal

Diese Authentifizierungsmethode verwendet einen Dienstprinzipal, um eine Benutzerin oder einen Benutzer anzumelden. Sie können die Anmeldeinformationen bereitstellen, indem Sie eine Umgebungsvariable festlegen oder die Anmeldeinformationen in einem Befehlszeilenargument verwenden. Die unterstützten Anmeldeinformationen, die Sie verwenden können, sind ein Kennwort oder ein PFX-Clientzertifikat (Personal Information Exchange).

Bevor Sie diese Methode verwenden, sollten Sie folgende Einschränkungen beachten:

  • Diese Methode funktioniert nur mit verwaltetem Microsoft Entra ID.
  • Der Dienstprinzipal darf ein Mitglied von maximal 200 Microsoft Entra-Gruppen sein.

Umgebungsvariablen

Das folgende Beispiel zeigt, wie Sie einen geheimen Clientschlüssel mithilfe von Umgebungsvariablen einrichten:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Führen Sie dann den folgenden Befehl aus:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Befehlszeilenargument

Das folgende Beispiel zeigt, wie Sie einen geheimen Clientschlüssel in einem Befehlszeilenargument einrichten:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Warnung

Die Befehlszeilenargumentmethode speichert den geheimen Schlüssel in der kubeconfig-Datei.

Clientzertifikat

Das folgende Beispiel zeigt, wie Sie einen geheimen Clientschlüssel mithilfe eines Clientzertifikats einrichten:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Führen Sie dann den folgenden Befehl aus:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

PoP-Token und Umgebungsvariablen

Das folgende Beispiel zeigt, wie Sie ein PoP-Token mithilfe eines geheimen Clientschlüssels aus Umgebungsvariablen einrichten:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Verwaltete Identität

Verwenden Sie die Authentifizierungsmethode mit einer verwalteten Identität für Anwendungen, die eine Verbindung mit Ressourcen herstellen, die die Microsoft Entra-Authentifizierung unterstützen. Beispiele hierfür sind der Zugriff auf Azure-Ressourcen wie ein Azure-VM, ein VM-Skalierungsgruppe oder die Azure Cloud Shell.

Standardmäßige verwaltete Identität

Das folgende Beispiel zeigt, wie Sie die standardmäßige verwaltete Identität verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Spezifische Identität

Das folgende Beispiel zeigt, wie Sie eine verwaltete Identität mit einer spezifischen Identität verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Workloadidentität

Die Workload-Identitätsauthentifizierungsmethode verwendet Identitätsanmeldeinformationen, die mit Microsoft Entra verbunden sind, um den Zugriff auf AKS-Cluster zu authentifizieren. Die Methode verwendet die integrierte Microsoft Entra-Authentifizierung. Sie funktioniert durch Festlegen der folgenden Umgebungsvariablen:

  • AZURE_CLIENT_ID: Die Microsoft Entra-Anwendungs-ID, die mit der Workloadidentität verbunden wird.
  • AZURE_TENANT_ID: Die Microsoft Entra Mandanten-ID.
  • AZURE_FEDERATED_TOKEN_FILE: Die Datei, die eine signierte Bestätigung der Workload-Identität enthält, wie z. B. ein Kubernetes Projected Service Account (JWT) Token.
  • AZURE_AUTHORITY_HOST: Die Basis-URL einer Microsoft Entra Authority. Beispiel: https://login.microsoftonline.com/.

Sie können eine Workloadidentität verwenden, um auf Kubernetes-Cluster aus einem CI/CD-System wie GitHub oder ArgoCD zuzugreifen, ohne Dienstprinzipalanmeldeinformationen in den externen Systemen zu speichern. Informationen zum Konfigurieren des OpenID Connect (OIDC)-Partnerverbunds von GitHub finden Sie im OIDC-Verbundbeispiel.

Das folgende Beispiel zeigt, wie Sie eine Workloadidentität verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

Führen Sie diesen kubectl-Befehl aus, um Knoteninformationen abzurufen:

kubectl get nodes

Verwenden von kubelogin mit AKS

AKS verwendet ein Paar von Microsoft Entra-Anwendungen von Erstanbietern. Diese Anwendungs-IDs sind in allen Umgebungen identisch.

Die Serveranwendungs-ID von Microsoft Entra ID für AKS, die serverseitig verwendet wird, lautet 6dae42f8-4368-4678-94ff-3960e28e3630. Der Zugriffstoken, das auf AKS-Cluster zugreift, muss für diese Anwendung ausgestellt werden. In den meisten kubelogin-Authentifizierungsmethoden müssen Sie --server-id mit kubelogin get-token verwenden.

Die Clientanwendungs-ID von Microsoft Entra für AKS, die von kubelogin zum Ausführen der öffentlichen Clientauthentifizierung im Auftrag des Benutzers bzw. der Benutzerin verwendet wird, lautet 80faf920-1908-4b52-b5ef-a8e7bedfc67a. Die Clientanwendungs-ID wird als Teil der Authentifizierungsmethoden Gerätecode und Webbrowser interaktiv verwendet.

Zugehöriger Inhalt