Azure Container Registry-verificatie met service-principals

  • Artikel

U kunt een Microsoft Entra-service-principal gebruiken om push-, pull- of andere toegang te bieden tot uw containerregister. Met behulp van een service-principal kunt u toegang bieden tot 'headless'-services en -toepassingen.

Wat is een service-principal?

Microsoft Entra ID-service-principals bieden toegang tot Azure-resources binnen uw abonnement. U kunt een service-principal beschouwen als een gebruikersidentiteit voor een service, waarbij 'service' elke toepassing, service of platform is die toegang nodig heeft tot de resources. U kunt een service-principal configureren met alleen toegangsrechten die zijn afgestemd op de resources die u opgeeft. Configureer vervolgens uw toepassing of service om de referenties van de service-principal te gebruiken voor toegang tot deze resources.

In de context van Azure Container Registry kunt u een Microsoft Entra-service-principal maken met pull-, push- en pull-machtigingen of andere machtigingen voor uw privéregister in Azure. Zie Azure Container Registry-rollen en -machtigingen voor een volledige lijst.

Waarom een service-principal gebruiken?

Met behulp van een Microsoft Entra-service-principal kunt u bereiktoegang bieden tot uw privécontainerregister. Maak verschillende service-principals voor elk van uw toepassingen of services, elk met op maat gemaakte toegangsrechten voor uw register. En omdat u het delen van referenties tussen services en toepassingen kunt voorkomen, kunt u referenties roteren of de toegang intrekken voor alleen de service-principal (en dus de toepassing) die u kiest.

Configureer bijvoorbeeld uw webtoepassing voor het gebruik van een service-principal die deze alleen toegang biedt tot installatiekopieën pull , terwijl uw buildsysteem gebruikmaakt van een service-principal die deze zowel push als pull toegang biedt. Als de ontwikkeling van uw toepassing verandert, kunt u de referenties van de service-principal roteren zonder dat dit van invloed is op het buildsysteem.

Wanneer gebruikt u een service-principal?

U moet een service-principal gebruiken om registertoegang te bieden in headless scenario's. Dat wil gezegd: een toepassing, service of script dat containerinstallatiekopieën op een geautomatiseerde of op een andere manier zonder toezicht moet pushen of ophalen. Voorbeeld:

  • Pull: Containers implementeren vanuit een register voor indelingssystemen, waaronder Kubernetes, DC/OS en Docker Swarm. U kunt ook ophalen uit containerregisters voor gerelateerde Azure-services, zoals App Service, Batch, Service Fabric en andere.

    Tip

    Een service-principal wordt aanbevolen in verschillende Kubernetes-scenario's om installatiekopieën op te halen uit een Azure-containerregister. Met Azure Kubernetes Service (AKS) kunt u ook een geautomatiseerd mechanisme gebruiken om te verifiëren met een doelregister door de beheerde identiteit van het cluster in te schakelen.

    • Push: Bouw containerinstallatiekopieën en push deze naar een register met behulp van continue integratie- en implementatieoplossingen zoals Azure Pipelines of Jenkins.

Voor afzonderlijke toegang tot een register, bijvoorbeeld wanneer u handmatig een containerinstallatiekopie naar uw ontwikkelwerkstation haalt, raden we u aan uw eigen Microsoft Entra-identiteit te gebruiken voor registertoegang (bijvoorbeeld bij az acr login).

Een service-principal maken

Als u een service-principal wilt maken met toegang tot uw containerregister, voert u het volgende script uit in Azure Cloud Shell of een lokale installatie van de Azure CLI. Het script is opgemaakt voor de Bash-shell.

Werk de ACR_NAME variabele bij met de naam van het containerregister voordat u het script uitvoert. De SERVICE_PRINCIPAL_NAME waarde moet uniek zijn binnen uw Microsoft Entra-tenant. Als u een ''http://acr-service-principal' already exists.'-fout ontvangt, geeft u een andere naam op voor de service-principal.

U kunt desgewenst de --role waarde wijzigen in de opdracht az ad sp create-for-rbac als u verschillende machtigingen wilt verlenen. Zie ACR-rollen en -machtigingen voor een volledige lijst met rollen.

Nadat u het script hebt uitgevoerd, noteert u de id en het wachtwoord van de service-principal. Zodra u de referenties hebt, kunt u uw toepassingen en services configureren voor verificatie bij uw containerregister als de service-principal.

#!/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"

Een bestaande service-principal gebruiken

Als u registertoegang wilt verlenen aan een bestaande service-principal, moet u een nieuwe rol toewijzen aan de service-principal. Net als bij het maken van een nieuwe service-principal kunt u onder andere pull-, push- en pull- en eigenaartoegang verlenen.

In het volgende script wordt de opdracht az role assignment create gebruikt om pull-machtigingen te verlenen aan een service-principal die u in de SERVICE_PRINCIPAL_ID variabele opgeeft. Pas de --role waarde aan als u een ander toegangsniveau wilt verlenen.

#!/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

Voorbeeldscripts

U vindt de voorgaande voorbeeldscripts voor Azure CLI op GitHub, evenals versies voor Azure PowerShell:

Verifiëren met de service-principal

Zodra u een service-principal hebt die u toegang hebt verleend tot uw containerregister, kunt u de referenties voor toegang tot 'headless'-services en -toepassingen configureren of deze invoeren met behulp van de docker login opdracht. Gebruik de volgende waarden:

  • Gebruikersnaam - toepassings-id van service-principal (client)
  • Wachtwoord : het wachtwoord van de service-principal (clientgeheim)

De waarde gebruikersnaam heeft de notatie xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Tip

U kunt het wachtwoord (clientgeheim) van een service-principal opnieuw genereren door de opdracht az ad sp credential reset uit te voeren.

Referenties gebruiken met Azure-services

U kunt service-principalreferenties gebruiken vanuit elke Azure-service die wordt geverifieerd met een Azure-containerregister. Gebruik referenties van de service-principal in plaats van de beheerdersreferenties van het register voor verschillende scenario's.

Gebruiken met docker-aanmelding

U kunt uitvoeren docker login met behulp van een service-principal. In het volgende voorbeeld wordt de toepassings-id van de service-principal doorgegeven in de omgevingsvariabele $SP_APP_IDen het wachtwoord in de variabele $SP_PASSWD. Zie de referentie voor docker-aanmeldingsopdrachten voor aanbevolen procedures voor het beheren van Docker-referenties .

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

Zodra u bent aangemeld, slaat Docker de referenties in de cache op.

Gebruiken met certificaat

Als u een certificaat hebt toegevoegd aan uw service-principal, kunt u zich aanmelden bij de Azure CLI met verificatie op basis van certificaten en vervolgens de opdracht az acr login gebruiken om toegang te krijgen tot een register. Het gebruik van een certificaat als geheim in plaats van een wachtwoord biedt extra beveiliging wanneer u de CLI gebruikt.

Een zelfondertekend certificaat kan worden gemaakt wanneer u een service-principal maakt. Of voeg een of meer certificaten toe aan een bestaande service-principal. Als u bijvoorbeeld een van de scripts in dit artikel gebruikt om een service-principal te maken of bij te werken met rechten voor het ophalen of pushen van installatiekopieën uit een register, voegt u een certificaat toe met behulp van de opdracht az ad sp credential reset .

Als u de service-principal met een certificaat wilt gebruiken om u aan te melden bij de Azure CLI, moet het certificaat de PEM-indeling hebben en de persoonlijke sleutel bevatten. Als uw certificaat niet de vereiste indeling heeft, gebruikt u een hulpprogramma, bijvoorbeeld openssl om het te converteren. Wanneer u az login uitvoert om u aan te melden bij de CLI met behulp van de service-principal, geeft u ook de toepassings-id van de service-principal en de Active Directory-tenant-id op. In het volgende voorbeeld ziet u deze waarden als omgevingsvariabelen:

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

Voer vervolgens az acr login uit om te verifiëren met het register:

az acr login --name myregistry

De CLI gebruikt het token dat is gemaakt toen u de sessie uitvoerde az login om uw sessie te verifiëren met het register.

Service-principal maken voor scenario's tussen tenants

Een service-principal kan ook worden gebruikt in Azure-scenario's waarvoor installatiekopieën uit een containerregister in één Microsoft Entra-id (tenant) naar een service of app in een andere moeten worden opgehaald. Een organisatie kan bijvoorbeeld een app uitvoeren in Tenant A die een installatiekopie moet ophalen uit een gedeeld containerregister in Tenant B.

Een service-principal maken die kan worden geverifieerd met een containerregister in een scenario voor meerdere tenants:

  • Een multitenant-app (service-principal) maken in Tenant A
  • De app inrichten in Tenant B
  • De service-principal machtigingen verlenen om uit het register in Tenant B te halen
  • De service of app in Tenant A bijwerken om te verifiëren met behulp van de nieuwe service-principal

Zie bijvoorbeeld Pull-installatiekopieën uit een containerregister naar een AKS-cluster in een andere AD-tenant.

Verlenging van service-principal

De service-principal wordt gemaakt met een geldigheidsduur van één jaar. U hebt opties om de geldigheid verder dan één jaar uit te breiden, of u kunt de vervaldatum van uw keuze opgeven met behulp van de az ad sp credential reset opdracht.

Volgende stappen