Integrieren von Microsoft Entra-ID in Azure Kubernetes Service (AKS) mithilfe der Azure CLI (Legacy)

  • Artikel

Warnung

Das in diesem Dokument beschriebene Feature, der Microsoft Entra-Integration (Legacy) wurde am 1. Juni 2023 eingestellt. Zum jetzigen Zeitpunkt können keine neuen Cluster mit Microsoft Entra-Integration (Legacy) erstellt werden.

AKS verfügt über eine neue verbesserte von AKS verwaltete Microsoft Entra ID-Umgebung, in der Sie die Server- oder Clientanwendungen nicht verwalten müssen. Wenn Sie die Migration durchführen möchten, folgen Sie den hier angegebenen Anweisungen.

Azure Kubernetes Service (AKS) kann für die Verwendung von Microsoft Entra ID für die Benutzerauthentifizierung konfiguriert werden. In dieser Konfiguration melden Sie sich bei einem AKS-Cluster über ein Microsoft Entra-Authentifizierungstoken an. Clusterbetreiber können auch die rollenbasierte Zugriffssteuerung von Kubernetes (Kubernetes RBAC) auf der Grundlage einer Benutzeridentität oder Verzeichnisgruppenmitgliedschaft konfigurieren.

In diesem Artikel wird erläutert, wie Sie die erforderlichen Microsoft Entra-Komponenten erstellen, anschließend einen Microsoft Entra-fähiges Cluster bereitstellen und dann eine grundlegende Kubernetes-Rolle im AKS-Cluster erstellen.

Begrenzungen

  • Microsoft Entra ID kann nur für Kubernetes RBAC-fähige Cluster aktiviert werden.
  • Die Integration von Microsoft Entra-Legacy kann nur während der Clustererstellung aktiviert werden.

Voraussetzungen

Azure CLI-Version 2.0.61 oder höher muss installiert und konfiguriert sein. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zum Durchführen einer Installation oder eines Upgrades finden Sei bei Bedarf unter Installieren der Azure CLI.

Wechseln Sie zu https://shell.azure.com, um Cloud Shell in Ihrem Browser zu öffnen.

Aus Konsistenzgründen und um die Ausführung der Befehle in diesem Artikel zu erleichtern, erstellen Sie eine Variable für den gewünschten AKS-Clusternamen. Im folgenden Beispiel wird der Name myakscluster verwendet:

aksname="myakscluster"

Übersicht zur Microsoft Entra-Authentifizierung

Die Microsoft Entra ID-Authentifizierung wird für AKS-Cluster mit OpenID Connect bereitgestellt. OpenID Connect ist eine Identitätsebene, die auf dem OAuth 2.0-Protokoll aufbaut. Weitere Informationen zu OpenID Connect finden Sie in der OpenID Connect-Dokumentation.

Innerhalb des Kubernetes-Clusters werden Authentifizierungstoken mithilfe der Webhooktokenauthentifizierung überprüft. Die Webhooktokenauthentifizierung wird als Teil des AKS-Clusters konfiguriert und verwaltet. Weitere Informationen zur Webhooktokenauthentifizierung finden Sie in der Dokumentation zur Webhookauthentifizierung.

Hinweis

Beim Konfigurieren von Microsoft Entra ID für die AKS-Authentifizierung werden zwei Microsoft Entra-Anwendungen konfiguriert. Dieser Vorgang muss von einem Azure-Mandantenadministrator ausgeführt werden.

Erstellen der Microsoft Entra-Serverkomponente

Für die Integration mit AKS erstellen und verwenden Sie eine Microsoft Entra-Anwendung, die als Endpunkt für die Identitätsanforderungen fungiert. Die erste Microsoft Entra-Anwendung, die Sie benötigen, ruft die Microsoft Entra-Gruppenmitgliedschaft für einen Benutzer ab.

Erstellen Sie die Serveranwendungskomponente mit dem Befehl az ad app create, und aktualisieren Sie anschließend die Gruppenmitgliedschaftsansprüche mit dem Befehl az ad app update. Im folgenden Beispiel wird die Variable aksname (im Abschnitt Voraussetzungen definiert) verwendet, und es wird eine Variable erstellt.

# Create the Azure AD application
serverApplicationId=$(az ad app create \
    --display-name "${aksname}Server" \
    --identifier-uris "https://${aksname}Server" \
    --query appId -o tsv)

# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All

Erstellen Sie nun mit dem Befehl az ad sp create einen Dienstprinzipal für die Server-App. Dieser Dienstprinzipal authentifiziert sich in der Azure Platform. Rufen Sie anschließend mit dem Befehl az ad sp credential reset das Dienstprinzipalgeheimnis ab, und weisen Sie es der Variablen serverApplicationSecret für die Verwendung in einem der folgenden Schritte zu:

# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId

# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
    --name $serverApplicationId \
    --credential-description "AKSPassword" \
    --query password -o tsv)

Der Microsoft Entra-Dienstprinzipal benötigt die Berechtigungen zum Ausführen der folgenden Aktionen:

  • Verzeichnisdaten lesen
  • Anmelden und Benutzerprofil lesen

Weisen Sie diese Berechtigungen mit dem Befehl az ad app permission add zu:

az ad app permission add \
    --id $serverApplicationId \
    --api 00000003-0000-0000-c000-000000000000 \
    --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role

Gewähren Sie schließlich mit dem Befehl az ad app permission grant die im vorherigen Schritt zugewiesenen Berechtigungen für die Serveranwendung. Dieser Schritt schlägt fehl, wenn das aktuelle Konto keinem Mandantenadministrator gehört. Sie müssen auch Berechtigungen für die Microsoft Entra-Anwendung hinzufügen, um Informationen anzufordern, für die andernfalls die Zustimmung des Administrators erforderlich wäre. Verwenden Sie dazu den Befehl az ad app permission admin-consent:

az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id  $serverApplicationId

Erstellen der Microsoft Entra-Clientkomponente

Die zweite Microsoft Entra-Anwendung wird beim Anmelden eines Benutzers beim AKS-Cluster mit der Kubernetes-CLI (kubectl) verwendet. Diese Clientanwendung empfängt die Authentifizierungsanforderung vom Benutzer und überprüft dessen Anmeldeinformationen und Berechtigungen. Erstellen Sie mit dem Befehl az ad app create die Microsoft Entra-App für die Clientkomponente:

clientApplicationId=$(az ad app create \
    --display-name "${aksname}Client" \
    --native-app \
    --reply-urls "https://${aksname}Client" \
    --query appId -o tsv)

Erstellen Sie mit dem Befehl az ad sp create einen Dienstprinzipal für die Clientanwendung:

az ad sp create --id $clientApplicationId

Rufen Sie mit dem Befehl az ad app show die oAuth2-ID für die Server-App ab, um den Authentifizierungsflow zwischen den beiden App-Komponenten zu ermöglichen. Diese oAuth2-ID wird im nächsten Schritt verwendet.

oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)

Fügen Sie mit dem Befehl az ad app permission add die Berechtigungen für die Client- und Serveranwendungskomponenten hinzu, um den Kommunikationsfluss oAuth2 zu verwenden: Gewähren Sie anschließend mit dem Befehl az ad app permission grant Berechtigungen für die Clientanwendung zur Kommunikation mit der Serveranwendung:

az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId

Bereitstellen des Clusters

Die beiden Microsoft Entra-Anwendungen sind nun erstellt. Jetzt müssen Sie das AKS-Cluster selbst erstellen. Erstellen Sie zuerst mit dem Befehl az group create eine Ressourcengruppe. Im folgenden Beispiel wird die Ressourcengruppe in der Region EastUS erstellt:

Erstellen einer Ressourcengruppe für den Cluster:

az group create --name myResourceGroup --location EastUS

Rufen Sie mit dem Befehl az account show die Mandanten-ID Ihres Azure-Abonnements ab. Erstellen Sie anschließend mit dem Befehl az aks create den AKS-Cluster. Im Befehl zum Erstellen des AKS-Clusters werden die IDs der Server- und der Clientanwendung, das Dienstprinzipal-Geheimnis der Serveranwendung und Ihre Mandanten-ID angegeben:

tenantId=$(az account show --query tenantId -o tsv)

az aks create \
    --resource-group myResourceGroup \
    --name $aksname \
    --node-count 1 \
    --generate-ssh-keys \
    --aad-server-app-id $serverApplicationId \
    --aad-server-app-secret $serverApplicationSecret \
    --aad-client-app-id $clientApplicationId \
    --aad-tenant-id $tenantId

Rufen Sie schließlich mit dem Befehl az aks get-credentials die Anmeldeinformationen für den Clusteradministrator ab. In einem der folgenden Schritte rufen Sie die Clusteranmeldeinformationen für reguläre Benutzer ab, um den Microsoft Entra-Authentifizierungsablauf in Aktion sehen zu können.

az aks get-credentials --resource-group myResourceGroup --name $aksname --admin

Erstellen einer Kubernetes RBAC-Bindung

Bevor ein Microsoft Entra-Konto mit dem AKS-Cluster verwendet werden kann, muss eine Rollenbindung oder eine Clusterrollenbindung erstellt werden. Rollen definieren die zu erteilenden Berechtigungen, und Bindungen wenden diese auf die gewünschten Benutzer an. Diese Zuweisungen können auf einen bestimmten Namespace oder im gesamten Cluster angewendet werden. Weitere Informationen finden Sie unter Verwenden der Kubernetes RBAC-Autorisierung.

Rufen Sie mit dem Befehl az ad signed-in-user show den Benutzerprinzipalnamen (UPN) für den derzeit angemeldeten Benutzer ab. Dieses Benutzerkonto wird im nächsten Schritt für die Microsoft Entra-Integration aktiviert.

az ad signed-in-user show --query userPrincipalName -o tsv

Wichtig

Wenn sich der Benutzer, für den die Kubernetes RBAC-Bindung gewährt wird, auf demselben Microsoft Entra-Mandanten befindet, sollten Sie Berechtigungen gemäß userPrincipalName zuweisen. Befindet sich der Benutzer in einem anderen Microsoft Entra-Mandanten, müssen Sie stattdessen die objectId-Eigenschaft abfragen und verwenden.

Erstellen Sie ein YAML-Manifest mit dem Namen basic-azure-ad-binding.yaml, und fügen Sie die folgenden Inhalte ein. Ersetzen Sie in der letzten Zeile userPrincipalName_or_objectId durch den UPN oder die Objekt-ID in der Ausgabe des vorherigen Befehls:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: contoso-cluster-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: userPrincipalName_or_objectId

Erstellen Sie die ClusterRoleBinding mit dem Befehl kubectl apply, und geben Sie den Dateinamen Ihres YAML-Manifests an:

kubectl apply -f basic-azure-ad-binding.yaml

Access-Cluster mit Microsoft Entra ID

Testen wir nun die Integration der Microsoft Entra-Authentifizierung für das AKS-Cluster. Legen Sie den kubectl-Konfigurationskontext auf die Verwendung regulärer Benutzeranmeldeinformationen fest. Dieser Kontext übergibt alle Authentifizierungsanforderungen über Microsoft Entra ID zurück.

az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing

Verwenden Sie nun den Befehl kubectl get pods, um Pods für alle Namespaces anzuzeigen:

kubectl get pods --all-namespaces

Sie erhalten eine Anmeldeaufforderung, sich in einem Webbrowser mit Microsoft Entra-Anmeldeinformationen zu authentifizieren. Nach erfolgreicher Authentifizierung zeigt der Befehl kubectl die Pods im AKS-Cluster an, wie in der folgenden Beispielausgabe veranschaulicht:

kubectl get pods --all-namespaces

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BYMK7UXVD to authenticate.

NAMESPACE     NAME                                    READY   STATUS    RESTARTS   AGE
kube-system   coredns-754f947b4-2v75r                 1/1     Running   0          23h
kube-system   coredns-754f947b4-tghwh                 1/1     Running   0          23h
kube-system   coredns-autoscaler-6fcdb7d64-4wkvp      1/1     Running   0          23h
kube-system   heapster-5fb7488d97-t5wzk               2/2     Running   0          23h
kube-system   kube-proxy-2nd5m                        1/1     Running   0          23h
kube-system   kube-svc-redirect-swp9r                 2/2     Running   0          23h
kube-system   kubernetes-dashboard-847bb4ddc6-trt7m   1/1     Running   0          23h
kube-system   metrics-server-7b97f9cd9-btxzz          1/1     Running   0          23h
kube-system   tunnelfront-6ff887cffb-xkfmq            1/1     Running   0          23h

Das für kubectl empfangene Authentifizierungstoken wird zwischengespeichert. Sie werden nur erneut aufgefordert, sich anzumelden, wenn das Token abgelaufen ist oder die Kubernetes-Konfigurationsdatei neu erstellt wird.

Wenn wie in der folgenden Beispielausgabe nach erfolgreicher Anmeldung im Webbrowser eine Meldung zu einem Authentifizierungsfehler angezeigt wird, untersuchen Sie die folgenden möglichen Probleme:

error: You must be logged in to the server (Unauthorized)
  • Sie haben die entsprechende Objekt-ID oder den UPN definiert, je nachdem, ob das Benutzerkonto im gleichen Microsoft Entra-Mandanten vorhanden ist oder nicht.
  • Der Benutzer ist kein Mitglied der über 200 Gruppen.
  • Das Geheimnis, das in der Anwendungsregistrierung für den Server definiert ist, entspricht dem mit --aad-server-app-secret konfigurierten Wert.
  • Stellen Sie sicher, dass immer nur eine Version von kubectl auf Ihrem Computer installiert ist. In Konflikt stehende Versionen können während der Autorisierung Probleme verursachen. Verwenden Sie zur Installation der aktuellen Version az aks install-cli.

Häufig gestellte Fragen zur Migration der Microsoft Entra-Integration zur AKS-verwalteten Microsoft Entra ID

1. Was ist der Plan für die Migration?

Microsoft Entra-Integration (Legacy) wird am 1. Juni 2023 eingestellt. Nach diesem Datum können Sie keine neuen Cluster mit Microsoft Entra ID (Legacy) erstellen. Ab dem 1. August 2023 migrieren wir alle AKS-Cluster (Legacy)-AKS zur AKS-verwalteten Microsoft Entra ID. Wir senden zweiwöchentlich Benachrichtigungs-E-Mails an die betroffenen Abonnementadministratoren, um sie an die Migration zu erinnern.

2. Was passiert, wenn ich nichts unternehme?

Ihre Microsoft Entra-Integration (Legacy)-AKS-Cluster funktionieren nach dem 1. Juni 2023 weiterhin. Ab dem 1. August 2023 migrieren wir Ihre Cluster automatisch zur AKS-verwalteten Microsoft Entra ID. Während der Migration kann es zu Ausfallzeiten des API-Servers kommen.

Der kubeconfig-Inhalt ändert sich nach der Migration. Sie müssen die neuen Anmeldeinformationen mithilfe von az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> in der kubeconfig-Datei zusammenführen.

Wir empfehlen, Ihr AKS-Cluster manuell vor dem 1. August auf die von AKS verwaltete Microsoft Entra ID upzudaten. Auf diese Weise können Sie die Ausfallzeiten außerhalb der Geschäftszeiten planen, wenn dies bequemer ist.

3. Warum erhalte ich nach der manuellen Migration weiterhin die Benachrichtigungs-E-Mail?

Es dauert mehrere Tage, bis die E-Mail gesendet wird. Wenn Ihr Cluster noch nicht migriert wurde, bevor wir den E-Mail-Sendevorgang initiieren, erhalten Sie möglicherweise trotzdem eine Benachrichtigung.

4. Wie kann ich überprüfen, ob mein Cluster zur AKS-verwalteten Microsoft Entra ID migriert wird?

Vergewissern Sie sich, dass Ihr AKS-Cluster mithilfe des az aks show-Befehls zur AKS-verwalteten Microsoft Entra-ID migriert wurde.

az aks show -g <RGName> -n <ClusterName>  --query "aadProfile"

Wenn Ihr Cluster die von AKS verwaltete Microsoft Entra ID verwendet, zeigt die Ausgabe managed ist true an. Beispiel:

    {
      "adminGroupObjectIDs": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ],
      "adminUsers": null,
      "clientAppId": null,
      "enableAzureRbac": null,
      "managed": true,
      "serverAppId": null,
      "serverAppSecret": null,
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }

Nächste Schritte

Das vollständige Skript mit den Befehlen aus diesem Artikel finden Sie im [Skript zur Microsoft Entra-Integration im Repository mit AKS-Beispielen][complete-script].

Informationen zur Verwendung von Microsoft Entra-Benutzern und -Gruppen für die Steuerung des Zugriffs auf Clusterressourcen finden Sie unter Steuern des Zugriffs auf Clusterressourcen per rollenbasierter Zugriffssteuerung von Kubernetes und mit Microsoft Entra-Identitäten in Azure Kubernetes Service.

Weitere Informationen zum Schutz von Kubernetes-Clustern finden Sie unter Zugriffs- und Identitätsoptionen für AKS.

Best Practices zur Identitäts- und Ressourcenkontrolle finden Sie unter Best Practices für Authentifizierung und Autorisierung in AKS.