Verwenden von Kubelogin zum Authentifizieren von Benutzern in Azure Kubernetes Service

  • Artikel

Das Kubelogin-Plug-In in Azure ist ein Client-go-Anmeldeinformations-Plug-In, das die Microsoft Entra-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 oder höher ausführen, verwenden automatisch das Kubelogin-Format.

Dieser Artikel enthält eine Übersicht und Beispiele für die Verwendung von Kubelogin für alle unterstützten Microsoft Entra-Authentifizierungsmethoden in AKS.

Begrenzungen

  • Sie können maximal 200 Gruppen in einen Microsoft Entra JSON-Webtokenanspruch (JWT) einschließen. Wenn Sie über mehr als 200 Gruppen verfügen, sollten Sie anwendungsrollen verwenden.
  • Gruppen, die in der Microsoft Entra-ID erstellt werden, werden nur durch ihren ObjectID-Wert und nicht durch ihren Anzeigenamen eingeschlossen. Der sAMAccountName Befehl ist nur für Gruppen verfügbar, die aus lokalem Windows Server Active Directory synchronisiert werden.
  • In AKS funktioniert die Dienstprinzipalauthentifizierungsmethode nur mit verwalteter Microsoft Entra-ID und nicht mit der früheren Version von Azure Active Directory.
  • Die Authentifizierungsmethode für Gerätecode funktioniert nicht, wenn eine Microsoft Entra-Richtlinie für bedingten Zugriff auf einen Microsoft Entra-Mandanten festgelegt ist. Verwenden Sie in diesem Szenario die interaktive Webbrowserauthentifizierung.

Funktionsweise der Authentifizierung

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

Die von Kubelogin implementierten Authentifizierungsmethoden sind Microsoft Entra OAuth 2.0-Tokenerteilungsflüsse. Die folgenden Parameterkennzeichnungen werden häufig in Kubelogin-Unterbefehlen verwendet. Im Allgemeinen können diese Flags verwendet werden, wenn Sie die Kubeconfig-Datei von AKS erhalten.

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

Hinweis

Bei jeder Authentifizierungsmethode wird das Token nicht 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

Gerätecode ist die Standardauthentifizierungsmethode für den convert-kubeconfig Unterbefehl. Das -l devicecode ist optional. Diese Authentifizierungsmethode fordert den Gerätecode des Benutzers auf, sich über eine Browsersitzung anzumelden.

Bevor die Kubelogin- und Exec-Plug-Ins eingeführt wurden, unterstützte die Azure-Authentifizierungsmethode in Kubectl nur den Gerätecodefluss. Es wurde eine frühere Version einer Bibliothek verwendet, die ein Token erzeugt, das den audience Anspruch mit einem spn: Präfix hat. Sie ist nicht kompatibel mit der von AKS verwalteten Microsoft Entra-ID, die einen OBO-Fluss (On-behalf-of) verwendet. Wenn Sie den convert-kubeconfig Unterbefehl ausführen, entfernt Kubelogin das spn: Präfix aus dem Zielgruppenanspruch.

Wenn Ihre Anforderungen die Verwendung von Funktionen aus früheren Versionen umfassen, fügen Sie das --legacy Argument hinzu. Wenn Sie die Kubeconfig-Datei in einer früheren Version von Azure Active Directory-Cluster verwenden, fügt Kubelogin automatisch das --legacy Flag hinzu.

Bei dieser Anmeldemethode werden das Zugriffstoken und das Aktualisierungstoken im Verzeichnis ${HOME}/.kube/cache/kubelogin zwischengespeichert. Um diesen Pfad außer Kraft zu setzen, schließen Sie den --token-cache-dir Parameter ein.

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 den folgenden Befehl aus, um zwischengespeicherte Token zu sauber:

kubelogin remove-tokens

Hinweis

Die Methode für die Gerätecodeanmeldung funktioniert nicht, wenn eine Richtlinie für bedingten Zugriff auf einen Microsoft Entra-Mandanten konfiguriert ist. Verwenden Sie in diesem Szenario die interaktive Webbrowsermethode.

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 ausgegeben wie az login. Kubelogin schreibt keine Token in die Tokencachedatei, da sie bereits von der Azure CLI verwaltet werden.

Hinweis

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

Das folgende Beispiel zeigt, wie Die Azure CLI-Methode zur Authentifizierung verwendet wird:

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, verwenden Sie den --azure-config-dir Parameter mit dem convert-kubeconfig Unterbefehl. Der Befehl generiert die Kubeconfig-Datei, wobei die Umgebungsvariable konfiguriert ist. Sie können dieselbe Konfiguration erhalten, indem Sie die AZURE_CONFIG_DIR Umgebungsvariable auf dieses Verzeichnis festlegen, wenn Sie einen Kubectl-Befehl ausführen.

Webbrowser interaktiv

Die interaktive Authentifizierungsmethode des Webbrowsers öffnet automatisch einen Webbrowser, um sich beim Benutzer anzumelden. Nachdem 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 überschreiben, indem Sie den --token-cache-dir Parameter verwenden.

Bearer token

Das folgende Beispiel zeigt, wie Sie ein Bearertoken mit dem interaktiven Webbrowserablauf verwenden:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

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

kubectl get nodes

Proof-of-Possession-Token

Das folgende Beispiel zeigt, wie Sie ein PoP-Token (Proof-of-Possession) mit dem interaktiven Fluss des Webbrowsers 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 sich beim 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 die folgenden Einschränkungen berücksichtigen:

  • Diese Methode funktioniert nur mit verwalteter Microsoft Entra-ID.
  • Der Dienstprinzipal kann 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 einrichten, das einen geheimen Clientschlüssel verwendet, der von Umgebungsvariablen abgerufen wird:

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 Methode für die verwaltete Identitätsauthentifizierung 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 virtueller Azure-Computer, ein Skalierungssatz für virtuelle Computer oder Azure Cloud Shell.

Verwaltete Standardidentitä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 bestimmten 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. Dies funktioniert durch Festlegen der folgenden Umgebungsvariablen:

  • AZURE_CLIENT_ID: Die Microsoft Entra-Anwendungs-ID, die mit der Workload-Identität verbunden ist.
  • AZURE_TENANT_ID: Die Microsoft Entra-Mandanten-ID.
  • AZURE_FEDERATED_TOKEN_FILE: Die Datei, die eine signierte Assertion der Workload-Identität enthält, z. B. ein projiziertes Kubernetes-Dienstkonto (JWT)-Token.
  • AZURE_AUTHORITY_HOST: Die Basis-URL einer Microsoft Entra-Autorität. Beispielsweise https://login.microsoftonline.com/.

Sie können eine Workload-Identität verwenden, um auf Kubernetes-Cluster von CI/CD-Systemen wie GitHub oder ArgoCD zuzugreifen, ohne Dienstprinzipalanmeldeinformationen in den externen Systemen zu speichern. Informationen zum Konfigurieren des OpenID-Verbinden (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

So verwenden Sie Kubelogin mit AKS

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

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

Die AKS Microsoft Entra-Clientanwendungs-ID, die kubelogin zum Ausführen der öffentlichen Clientauthentifizierung im Namen des Benutzers verwendet.80faf920-1908-4b52-b5ef-a8e7bedfc67a Die Clientanwendungs-ID wird in interaktiven Authentifizierungsmethoden für Gerätecode und Webbrowser verwendet.

Zugehöriger Inhalt