Freigeben über

Azure Container Registry-Authentifizierung mit Dienstprinzipalen

  • Artikel

Sie können einen Dienstprinzipal von Microsoft Entra verwenden, um den Push, Pull oder anderen Zugriff auf Ihre Containerregistrierung zu gewähren. Mithilfe eines Dienstprinzipals können Sie den Zugriff für „monitorlose“ Dienste und Anwendungen ermöglichen.

Was ist ein Dienstprinzipal?

Dienstprinzipale von Microsoft Entra ermöglichen den Zugriff auf Azure-Ressourcen innerhalb Ihres Abonnements. Sie können sich einen Dienstprinzipal als Benutzeridentität für einen Dienst vorstellen, wobei „Dienst“ jede Anwendung, jeder Dienst oder jede Plattform sein kann, die auf die Ressourcen zugreifen muss. Sie haben die Möglichkeit, einen Dienstprinzipal mit Zugriffsrechten so zu konfigurieren, dass diese nur für die von Ihnen angegebenen Ressourcen gelten. Anschließend legen Sie für Ihre Anwendung bzw. Ihren Dienst fest, dass diese bzw. dieser die Anmeldeinformationen des Dienstprinzipals verwendet, um auf diese Ressourcen zuzugreifen.

Im Rahmen der Azure Container Registry können Sie einen Microsoft Entra-Dienstprinzipal mit Pull-, Push- und Pull- oder anderen Berechtigungen für Ihre private Registrierung in Azure erstellen. Eine vollständige Liste finden Sie unter Azure Container Registry – Rollen und Berechtigungen.

Gründe für die Verwendung eines Dienstprinzipals

Mithilfe eines Microsoft Entra-Dienstprinzipals können Sie bereichsbezogenen Zugriff auf Ihre private Containerregistrierung gewähren. Erstellen Sie für Ihre einzelnen Anwendungen oder Dienste verschiedene Dienstprinzipale, die jeweils über abgestimmte Zugriffsrechte für die Registrierung verfügen. Und da Sie die Anmeldeinformationen nicht an Dienste und Anwendungen weitergeben müssen, haben Sie die Möglichkeit, ausschließlich für den gewählten Dienstprinzipal (und somit für die Anwendung) Anmeldeinformationen weiterzugeben oder Zugriffsrechte zu widerrufen.

Konfigurieren Sie beispielsweise Ihre Webanwendung für die Verwendung eines Dienstprinzipals, der ihr nur Zugriff auf Image pull ermöglicht, während Ihr Buildsystem einen Dienstprinzipal verwendet, der ihm sowohl Zugriff auf push als auch pull bietet. Wenn die Entwicklung Ihrer Anwendung von einer anderen Person übernommen wird, können Sie die Anmeldeinformationen für den Dienstprinzipal weitergeben, ohne das Buildsystem zu beeinflussen.

Einsatzbereiche eines Dienstprinzipals

Sie sollten einen Dienstprinzipal verwenden, um in monitorlosen Szenarien Zugriff auf die Registrierung bieten. Das heißt, dies betrifft Anwendungen, Dienste oder Skripte, die Containerimages in automatisierter oder anderweitig unbeaufsichtigter Weise pushen oder pullen müssen. Beispiel:

  • Pull: Bereitstellen von Containern aus einer Registrierung für Orchestrierungssysteme, z. B. Kubernetes, DC/OS und Docker Swarm. Sie können auch Pullvorgänge aus Containerregistrierungen in andere Azure-Dienste durchführen, z.B. App Service, Batch, Service Fabric und weitere Dienste.

    Tipp

    Ein Dienstprinzipal wird in mehreren Kubernetes-Szenarien empfohlen, um Images aus einer Azure-Containerregistrierung zu pullen. Mit Azure Kubernetes Service (AKS) können Sie auch einen automatisierten Mechanismus zur Authentifizierung bei einer Zielregistrierung verwenden, indem Sie die verwaltete Identitätdes Clusters aktivieren.

    • Push: Erstellen von Containerimages und deren Übertragung per Pushvorgang in eine Registrierung mithilfe von Lösungen für Continuous Integration und Continuous Deployment wie Azure Pipelines oder Jenkins.

Für den individuellen Zugriff auf eine Registrierung, etwa, wenn Sie manuell ein Containerimage auf Ihre Entwicklungsarbeitsstation pullen, empfehlen wir, dass Sie stattdessen Ihre eigene Microsoft Entra-Identität für den Registrierungszugriff verwenden (beispielsweise mit az acr login).

Erstellen eines Dienstprinzipals

Führen Sie zum Erstellen eines Dienstprinzipals mit Zugriff auf die Containerregistrierung das folgende Skript in Azure Cloud Shell oder in einer lokalen Installation der Azure CLI aus. Das Skript ist für die Bash-Shell formatiert.

Aktualisieren Sie vor dem Ausführen des Skripts die Variable ACR_NAME mit dem Namen Ihrer Containerregistrierung. Der SERVICE_PRINCIPAL_NAME-Wert muss innerhalb Ihres Microsoft Entra-Mandanten eindeutig sein. Wird der Fehler 'http://acr-service-principal' already exists. angezeigt, geben Sie einen anderen Namen für den Dienstprinzipal an.

Optional können Sie den Wert --role im Befehl az ad sp create-for-rbac ändern, falls Sie andere Berechtigungen gewähren möchten. Eine vollständige Liste der Rollen finden Sie unter ACR-Rollen und -Berechtigungen.

Nachdem Sie das Skript ausgeführt haben, notieren Sie die ID und das Kennwort des Dienstprinzipals. Sobald Sie über dessen Anmeldeinformationen verfügen, können Sie Ihre Anwendungen und Dienste so konfigurieren, dass diese bei Ihrer Containerregistrierung als Dienstprinzipal authentifiziert werden.

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

Verwenden eines vorhandenen Dienstprinzipals

Damit Sie einem vorhandenen Dienstprinzipal den Zugriff auf die Registrierung gewähren können, müssen Sie dem Dienstprinzipal eine neue Rolle zuweisen. Wie bei der Erstellung eines neuen Dienstprinzipals können Sie unter anderem Pull-, Push- und Pull- sowie Besitzerzugriff gewähren.

Das folgende Skript verwendet den Befehl az role assignment create, um einem Dienstprinzipal Pull-Berechtigungen zuzuweisen, den Sie in der Variablen SERVICE_PRINCIPAL_ID festlegen. Passen Sie den Wert --role an, wenn Sie eine andere Zugriffsebene zuweisen möchten.

#!/bin/bash
# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_ID=$servicePrincipal

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull

Beispielskripts

Die obigen Beispielskripts für die Azure CLI auf GitHub sowie Versionen für Azure PowerShell finden Sie hier:

Authentifizieren mit dem Dienstprinzipal

Sobald Sie einem Dienstprinzipal Zugriff auf Ihre Containerregistrierung gewährt haben, können Sie seine Anmeldeinformationen für den Zugriff auf „monitorlose“ Dienste und Anwendungen konfigurieren oder sie mit dem Befehl docker login eingeben. Verwenden Sie die folgenden Werte:

  • Benutzername: Anwendungs-ID (Client) des Dienstprinzipals
  • Kennwort: Kennwort (geheimer Clientschlüssel) des Dienstprinzipals

Der Wert Benutzername wird im Format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx angegeben.

Tipp

Sie können das Kennwort (geheimer Clientschlüssel) eines Dienstprinzipals neu generieren, indem Sie den Befehl az ad sp credential reset ausführen.

Verwenden von Anmeldeinformationen mit Azure-Diensten

Sie können die Anmeldeinformationen des Dienstprinzipals in jedem Azure-Dienst verwenden, der mit einer Azure-Containerregistrierung authentifiziert wird. Dienstprinzipal-Anmeldeinformationen können anstelle der Administratoranmeldeinformationen der Registrierung in einer Vielzahl von Szenarien verwendet werden.

Verwenden mit Docker-Anmeldung

Sie können docker login unter Verwendung eines Dienstprinzipals ausführen. Im folgenden Beispiel wird die Anwendungs-ID des Dienstprinzipals in der Umgebungsvariablen $SP_APP_ID und das Kennwort in der Variablen $SP_PASSWD übergeben. Bewährte Methoden zur Verwaltung von Docker-Anmeldeinformationen finden Sie in der Befehlsreferenz zu Docker-Login.

# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

Nach der Anmeldung speichert Docker die Anmeldeinformationen zwischen.

Verwenden mit Zertifikat

Wenn Sie Ihrem Dienstprinzipal ein Zertifikat hinzugefügt haben, können Sie sich mit der zertifikatbasierten Authentifizierung bei der Azure CLI anmelden und dann den Befehl az acr login verwenden, um auf eine Registrierung zuzugreifen. Die Verwendung eines Zertifikats als Geheimnis anstelle eines Kennworts bietet zusätzliche Sicherheit bei der Verwendung der CLI.

Ein selbstsigniertes Zertifikat kann erstellt werden, wenn Sie einen Dienstprinzipal erstellen. Fügen Sie alternativ einem vorhandenen Dienstprinzipal ein oder mehrere Zertifikate hinzu. Wenn Sie z. B. eines der Skripts in diesem Artikel verwenden, um einen Dienstprinzipal mit Rechten zum Pullen oder Pushen von Images aus einer Registrierung zu erstellen oder zu aktualisieren, fügen Sie mithilfe des az ad sp credential reset-Befehls ein Zertifikat hinzu.

Um den Dienstprinzipal mit einem Zertifikat zum Anmelden bei der Azure CLI zu verwenden, muss das Zertifikat im PEM-Format vorliegen und den privaten Schlüssel enthalten. Wenn das Zertifikat nicht im erforderlichen Format vorliegt, verwenden Sie ein Tool wie openssl, um es zu konvertieren. Wenn Sie az login ausführen, um sich mithilfe des Dienstprinzipals bei der CLI anzumelden, geben Sie auch die Anwendungs-ID und die Active Directory-Mandanten-ID des Dienstprinzipals an. Das folgende Beispiel zeigt diese Werte als Umgebungsvariablen:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID  --password /path/to/cert/pem/file

Führen Sie dann az acr login aus, um sich bei der Registrierung zu authentifizieren:

az acr login --name myregistry

Die CLI verwendet das Token, das bei Ihrer Ausführung von az login erstellt wurde, um Ihre Sitzung bei der Registrierung zu authentifizieren.

Erstellen eines Dienstprinzipals für mandantenübergreifende Szenarien

Ein Dienstprinzipal kann auch in Azure-Szenarien verwendet werden, die das Pullen von Images aus einer Containerregistrierung in einem Microsoft Entra ID (Mandant) in einen Dienst oder eine App in einer anderen erfordern. Beispielsweise kann eine Organisation eine App in Mandant A ausführen, die ein Image aus einer freigegebenen Containerregistrierung in Mandant B pullen muss.

So erstellen Sie einen Dienstprinzipal, der sich in einem mandantenübergreifenden Szenario bei einer Containerregistrierung authentifizieren kann:

  • Erstellen einer mehrinstanzenfähigen App (Dienstprinzipal) in Mandant A
  • Die App in Mandant B bereitstellen.
  • Dem Dienstprinzipal Berechtigungen zum Pullen aus der Registrierung in Mandant B erteilen.
  • Den Dienst oder die App in Mandant A für die Authentifizierung mit dem neuen Dienstprinzipal aktualisieren.

Beispielschritte finden Sie unter Pullen von Images aus einer Containerregistrierung in einen AKS-Cluster in einem anderen AD-Mandanten.

Verlängerung des Dienstprinzipals

Der Dienstprinzipal wird mit einer Gültigkeitsdauer von einem Jahr erstellt. Sie haben die Möglichkeit, die Gültigkeitsdauer um mehr als ein Jahr zu verlängern, oder Sie können mithilfe des Befehls az ad sp credential reset ein Ablaufdatum Ihrer Wahl angeben.

Nächste Schritte