Verwenden von Kubelogin zum Authentifizieren von Benutzern in Azure Kubernetes Service (AKS)

Das kubelogin-Plug-In in Azure ist ein client-go-Anmeldeinformations-Plug-In, das die Microsoft Entra-Authentifizierung implementiert. Das kubelogin-Plug-In bietet Funktionen, die im kubectl-Befehlszeilenstool nicht verfügbar sind. Weitere Informationen finden Sie in der Einführung zu kubelogin Einführung und kubectl.

Dieser Artikel bietet eine Übersicht und Beispiele zur Verwendung von kubelogin für die für AKS empfohlenen unterstützten Microsoft Entra-Authentifizierungsmethoden.

Einschränkungen der Kubelogin-Authentifizierung in AKS

  • Gruppen, die in Microsoft Entra erstellt werden, werden nur durch ihren ObjectID-Wert und nicht durch ihren Anzeigenamen eingeschlossen. Der Befehl sAMAccountName ist nur für Gruppen verfügbar, die aus dem lokalen Windows Server Active Directory synchronisiert werden.
  • Die Methode für die Dienstprinzipalauthentifizierung funktioniert nur mit verwalteter Microsoft Entra ID Integration, nicht bei der Legacy-Microsoft Entra ID-Integration.
  • Der Dienstprinzipal kann Mitglied von maximal 200 Microsoft Entra Gruppen sein. Wenn Sie mehr als 200 Gruppen haben, sollten Sie Anwendungsrollen verwenden.
  • Die Gerätecode-Authentifizierungsmethode funktioniert nicht, wenn eine Microsoft Entra-Richtlinie für den bedingten Zugriff auf einen Microsoft Entra-Mandanten festgelegt ist. Verwenden Sie in diesem Szenario stattdessen die interaktive Webbrowserauthentifizierung.
  • Die Azure CLI-Authentifizierungsmethode funktioniert nur mit Microsoft Entra.

Funktionsweise der Kubelogin-Authentifizierung in AKS

AKS-Cluster mit Kubernetes Version 1.24 oder höher verwenden automatisch das Kubelogin exec-Plug-In-Format. Cluster mit Kubernetes-Versionen vor 1.24 erfordern eine manuelle Konvertierung in dieses Format.

Verwenden Sie für die meisten Interaktionen mit Kubelogin den convert-kubeconfig Unterbefehl. Der Unterbefehl verwendet die kubeconfig-Datei, die Sie in --kubeconfig oder in der KUBECONFIG Umgebungsvariable angeben, 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-Token-Grant-Flows. Das Cacheverhalten hängt von der Authentifizierungsmethode ab. Gerätecode-, interaktive Webbrowser- und Resource-Owner-Password-Credential-(ROPC)-Authentifizierungen speichern Authentifizierungsdatensätze im kubelogin-Cacheverzeichnis. Methoden wie Azure CLI und Azure Developer CLI verwenden den vom jeweiligen Befehlszeilentool verwalteten Cache anstelle des Kubelogin-Caches.

Gerätecodeauthentifizierung

Der Gerätecode ist die Standardauthentifizierungsmethode für den Unterbefehl convert-kubeconfig. Bei dieser Authentifizierungsmethode wird der Gerätecode abgefragt, damit sich der Benutzer über eine Browsersitzung anmelden kann.

Hinweis

Bevor die Plug-Ins kubelogin und exec eingeführt wurden, unterstützte die Azure-Authentifizierungsmethode in kubectl ausschließlich den Gerätecodeflow. Es wurde eine frühere Version einer Bibliothek verwendet, die ein Token erzeugt, das das audience-Anspruch mit einem spn:-Präfix enthält. Es ist nicht kompatibel mit Microsoft Entra, das einen on-behalf-of (OBO) Flow verwendet. Wenn Sie den Unterbefehl convert-kubeconfig ausführen, entfernt kubelogin das spn:-Präfix aus dem Zielgruppenanspruch.

Parameter für die Gerätecodeauthentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der Gerätecodeauthentifizierung verwenden können:

Parameter Description
-l devicecode (wahlweise) Gibt die Kubelogin-Authentifizierungsmethode an. Dieser Parameter ist optional, da Gerätecode die Standardmethode ist.
--legacy Verwendet Legacy-Verhalten für Cluster, die mit Legacy-Microsoft Entra ID-Integration konfiguriert sind. Wenn die Kubeconfig-Datei für einen solchen Cluster ist, fügt Kubelogin automatisch das --legacy Flag hinzu.
--cache-dir Überschreibt den Standardpfad des Tokencacheverzeichnisses, das ${HOME}/.kube/cache/kubelogin ist.

Azure CLI-Authentifizierung

Die Azure CLI -Authentifizierungsmethode (Befehl: -l azurecli) verwendet den angemeldeten Kontext, den die Azure CLI zum Abrufen des Zugriffstokens herstellt. Das Token wird in demselben Microsoft Entra-Mandanten wie az login ausgegeben. Kubelogin schreibt keine Token in die Tokencachedatei, da die Azure CLI sie bereits verwaltet.

Parameter für die Azure CLI-Authentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der Azure CLI-Authentifizierung verwenden können:

Parameter Description
-l azurecli Gibt die Kubelogin-Authentifizierungsmethode an.
--azure-config-dir Gibt das Azure CLI-Konfigurationsverzeichnis an. Das Standardverzeichnis ist ${HOME}/.azure.

Anmelden bei Azure

Melden Sie sich mit dem az login Befehl bei Azure an.

az login

Interaktive Authentifizierung des Webbrowsers

Die interaktive Authentifizierungsmethode öffnet automatisch einen Webbrowser, um den Benutzer anzumelden (Befehl: -l interactive). 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.

Sie können entweder ein Bearertoken oder ein PoP-Token (Proof-of-Possession) mit dieser Authentifizierungsmethode verwenden.

Parameter für die Bearertokenauthentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der Bearertokenauthentifizierung verwenden können:

Parameter Description
-l interactive Gibt die Kubelogin-Authentifizierungsmethode an.
--cache-dir Überschreibt den Standardpfad des Tokencacheverzeichnisses, das ${HOME}/.kube/cache/kubelogin ist.

Parameter für die PoP-Tokenauthentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der PoP-Tokenauthentifizierung verwenden können:

Parameter Description
-l interactive Gibt die Kubelogin-Authentifizierungsmethode an.
--pop-enabled Aktiviert die PoP-Tokenauthentifizierung.
--pop-claims Gibt die PoP-Tokenansprüche in einem Schlüsselwert-Paarformat an. Beispiel: u=/ARM/ID/OF/CLUSTER.

Dienstprinzipalauthentifizierung

Die Dienstprinzipal-Authentifizierungsmethode (Befehl: -l spn) nutzt einen Dienstprinzipal, um den Benutzer zu authentifizieren. Sie können die Anmeldeinformation durch Setzen einer Umgebungsvariablen oder durch Verwendung der Anmeldeinformationen in einem Befehlszeilenargument bereitstellen. Die unterstützten Anmeldeinformationen, die Sie verwenden können, sind ein Kennwort oder ein PFX-Clientzertifikat (Personal Information Exchange).

Parameter für die Authentifizierung des Dienstprinzipals

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der Dienstprinzipalauthentifizierung verwenden können:

Parameter Description
-l spn Gibt die Kubelogin-Authentifizierungsmethode an.
--client-id Die Anwendungs-ID (Client-ID) des Dienstprinzipals.
--client-secret Das Kundengeheimnis des Dienstherrn.

Authentifizierung der verwalteten Identität

Verwenden Sie die Verwaltete Identität (Befehl: -l msi) Authentifizierungsmethode 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 virtueller Computer (VM), Virtual Machine Scale Sets oder Azure Cloud Shell.

Sie können die standardverwaltete Identität verwenden, die der Ressource oder einer bestimmten vom Benutzer zugewiesenen verwalteten Identität zugewiesen ist.

Parameter für die verwaltete Identitätsauthentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit verwalteter Identitätsauthentifizierung verwenden können:

Parameter Description
-l msi Gibt die Kubelogin-Authentifizierungsmethode an.
--client-id Die Anwendungs-ID (Client-ID) der vom Benutzer zugewiesenen verwalteten Identität. Wenn Sie diesen Parameter nicht angeben, wird die standardmäßige verwaltete Identität verwendet.

Workload-Identitätsauthentifizierung

Die Workload-Identitätsmethode (Befehl: -l workloadidentity) verwendet Identitätsanmeldeinformationen, die mit Microsoft Entra verbunden sind, um den Zugriff auf AKS-Cluster zu authentifizieren. Die Methode verwendet die integrierte Authentifizierung von Microsoft Entra. Sie funktioniert, indem die folgenden Umgebungsvariablen festgelegt werden:

Variable Description
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 Kubernetes-Token (Projected Service Account, JWT).
AZURE_AUTHORITY_HOST Die Basis-URL einer Microsoft Entra-Autorität. Beispiel: https://login.microsoftonline.com/.

Sie können eine Workload-Identität verwenden, um von CI/CD-Systemen wie GitHub oder Argo CD aus auf Kubernetes-Cluster zuzugreifen, ohne in den externen Systemen Anmeldeinformationen für Dienstprinzipale zu speichern. Um OpenID Connect (OIDC) Federation von GitHub aus zu konfigurieren, sehen Sie sich das Beispiel mit dem OIDC-Partnerverbund an.

Parameter für die Workload-Identitätsauthentifizierung

In der folgenden Tabelle sind Parameter aufgeführt, die Sie mit der Workload-Identitätsauthentifizierung verwenden können:

Parameter Description
-l workloadidentity Gibt die Kubelogin-Authentifizierungsmethode an.

Azure Entwickler-CLI-Authentifizierung

Die Authentifizierungsmethode der Azure Developer CLI (Befehl: -l azd) verwendet den Anmeldekontext, den die Azure Developer CLI zum Abrufen des Zugriffstokens bereitstellt. Das Token wird in demselben Microsoft Entra-Mandanten wie azd auth login ausgegeben. Kubelogin schreibt keine Token in den Tokencache, da die Azure Developer CLI sie verwaltet.

Diese Authentifizierungsmethode funktioniert nur mit verwaltetem Microsoft Entra in AKS. Weitere Informationen finden Sie in der Übersicht über die Azure Developer CLI.

Azure Pipelines-Authentifizierung

Die Azure Pipelines (Befehl: -l azurepipelines) Authentifizierungsmethode verwendet eine Azure Resource Manager Dienstverbindung und das Systemzugriffstoken der Pipeline zur Authentifizierung. Diese Methode funktioniert nur in Azure Pipelines. Die Pipeline muss über eine Azure Resource Manager Dienstverbindung verfügen und Skripts den Zugriff auf das OAuth-Token ermöglichen.

Wenn Sie eine AzureCLI@2 Aufgabe mit einer Azure Resource Manager Dienstverbindung verwenden, kann Kubelogin die Mandanten-ID, Client-ID und Dienstverbindungs-ID verwenden, die Azure Pipelines als Umgebungsvariablen bereitstellt. Weitere Informationen finden Sie unter Azure Pipelines Dienstverbindungen.

Warning

Kubelogin unterstützt auch die RoPC-Authentifizierungsmethode (Resource Owner Password Credential). Microsoft empfiehlt, ROPC nicht zu verwenden, da sie nicht mit mehrstufiger Authentifizierung und einigen Hybrididentitätsszenarien kompatibel ist. Weitere Informationen finden Sie in den Microsoft Identity Platform ROPC-Anleitungen.

Exportieren des Kubeconfig-Dateipfads

Bevor Sie den convert-kubeconfig Unterbefehl ausführen, exportieren Sie den Kubeconfig-Dateipfad in die KUBECONFIG Umgebungsvariable. Beispiel:

export KUBECONFIG=/path/to/kubeconfig

Konvertieren der Kubeconfig-Datei

Führen Sie den convert-kubeconfig Unterbefehl aus, um die Kubeconfig-Datei zu konvertieren, um das exec-Plug-In für die ausgewählte Authentifizierungsmethode zu verwenden.

kubelogin convert-kubeconfig

kubelogin convert-kubeconfig -l azurecli

# Bearer token authentication
kubelogin convert-kubeconfig -l interactive

# Proof-of-Possession (PoP) token authentication
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

  1. Führen Sie den convert-kubeconfig Unterbefehl aus, um die Kubeconfig-Datei zu konvertieren, um das exec-Plug-In zu verwenden.

    kubelogin convert-kubeconfig -l spn

  2. Legen Sie die Umgebungsvariablen für die Client-ID und den geheimen Clientschlüssel oder das Clientzertifikat fest. Beispiel:

    export AZURE_CLIENT_ID=<service-principal-client-id>
export AZURE_CLIENT_SECRET=<service-principal-client-secret>

# Default managed identity authentication
kubelogin convert-kubeconfig -l msi

# Specific managed identity authentication
kubelogin convert-kubeconfig -l msi --client-id <managed-identity-client-id>

kubelogin convert-kubeconfig -l workloadidentity

Konvertieren der Kubeconfig-Datei mithilfe der Azure Developer CLI

  1. Melden Sie sich mit der Azure Developer CLI an.

    azd auth login

  2. Konvertieren Sie die Kubeconfig-Datei, um die Azure Developer CLI-Authentifizierungsmethode zu verwenden.

    kubelogin convert-kubeconfig -l azd

Konvertieren der Kubeconfig-Datei in Azure Pipelines

Konvertieren Sie in einer AzureCLI@2-Aufgabe, die eine Azure Resource Manager-Dienstverbindung verwendet, die kubeconfig-Datei so, dass sie die Azure Pipelines-Authentifizierung verwendet.

kubelogin convert-kubeconfig -l azurepipelines

Entfernen zwischengespeicherter Token

Entfernen Sie zwischengespeicherte Token mithilfe des kubelogin remove-cache-dir Befehls.

kubelogin remove-cache-dir

Abrufen von Knoteninformationen

Abrufen von Knoteninformationen mithilfe des kubectl get Befehls.

kubectl get nodes

So verwenden Sie kubelogin-Anwendungs-IDs mit AKS

AKS verwendet zwei Erstanbieteranwendungen von Microsoft Entra. Diese Anwendungs-IDs sind in allen Umgebungen identisch.

Application Anwendungs-ID (GUID) Verwendet in
AKS-Serveranwendung (--server-id) 6dae42f8-4368-4678-94ff-3960e28e3630 Die Zielgruppe des Tokens für alle unterstützten kubelogin-Authentifizierungsmethoden beim Zugriff auf AKS.
Öffentliche AKS-Clientanwendung (--client-id) 80faf920-1908-4b52-b5ef-a8e7bedfc67a Gerätecode, interaktive Webbrowserauthentifizierung und ROPC-Authentifizierung.

Wenn Sie kubelogin get-token direkt für AKS aufrufen, geben Sie die AKS-Serveranwendungs-ID mit --server-id an. Modespezifische Parameter finden Sie in der Kubelogin-Referenzget-token.

Hinweis

Die Anwendungs-ID des öffentlichen AKS-Clients in diesem Abschnitt ist der Wert --client-id für die Gerätecode-, interaktive Webbrowser- und ROPC-Authentifizierung. Bei der Authentifizierung mit Dienstprinzipal und verwalteter Identität identifiziert --client-id stattdessen den Dienstprinzipal oder die benutzerseitig zugewiesene verwaltete Identität.

Rufen Sie beispielsweise ein Token mithilfe der Gerätecodeauthentifizierung und der AKS-Anwendungs-IDs ab:

kubelogin get-token \
    --login devicecode \
    --server-id 6dae42f8-4368-4678-94ff-3960e28e3630 \
    --client-id 80faf920-1908-4b52-b5ef-a8e7bedfc67a \
    --tenant-id <microsoft-entra-tenant-id>

Verwandte Inhalte

  • Zuletzt aktualisiert um