Azure Container Registry-autentisering med tjänstens huvudnamn

  • Artikel

Du kan använda microsoft entra-tjänstens huvudnamn för att tillhandahålla push-, pull- eller annan åtkomst till ditt containerregister. Genom att använda tjänstens huvudnamn kan du ge åtkomst till "huvudlösa" tjänster och program.

Vad är ett huvudnamn för tjänsten?

Microsoft Entra ID-tjänstens huvudnamn ger åtkomst till Azure-resurser i din prenumeration. Du kan se tjänstens huvudnamn som en användaridentitet för en tjänst, där "tjänsten" är alla program, tjänster eller plattformar som behöver åtkomst till resurserna. Du kan konfigurera ett huvudnamn för tjänsten med åtkomsträttigheter som endast är begränsade till de resurser som du anger. Konfigurera sedan programmet eller tjänsten så att den använder tjänstens huvudnamns autentiseringsuppgifter för att komma åt dessa resurser.

När det gäller Azure Container Registry kan du skapa ett Microsoft Entra-tjänsthuvudnamn med pull-, push- och pull-behörigheter eller andra behörigheter till ditt privata register i Azure. En fullständig lista finns i Roller och behörigheter för Azure Container Registry.

Varför ska du använda tjänstens huvudnamn?

Genom att använda tjänstens huvudnamn för Microsoft Entra kan du ge begränsad åtkomst till ditt privata containerregister. Skapa olika tjänsthuvudnamn för var och en av dina program eller tjänster, var och en med skräddarsydda åtkomsträttigheter till ditt register. Och eftersom du kan undvika att dela autentiseringsuppgifter mellan tjänster och program kan du rotera autentiseringsuppgifter eller återkalla åtkomst för endast tjänstens huvudnamn (och därmed programmet) som du väljer.

Konfigurera till exempel webbappen så att den använder ett huvudnamn för tjänsten som endast ger avbildningsåtkomst pull , medan byggsystemet använder ett huvudnamn för tjänsten som ger både push och pull åtkomst. Om utvecklingen av ditt program ändras kan du rotera autentiseringsuppgifterna för tjänstens huvudnamn utan att påverka byggsystemet.

När du ska använda tjänstens huvudnamn

Du bör använda tjänstens huvudnamn för att tillhandahålla registeråtkomst i huvudlösa scenarier. Det vill: ett program, en tjänst eller ett skript som måste skicka eller hämta containeravbildningar på ett automatiserat eller på annat sätt obevakat sätt. Till exempel:

  • Pull: Distribuera containrar från ett register till orkestreringssystem, inklusive Kubernetes, DC/OS och Docker Swarm. Du kan också hämta från containerregister till relaterade Azure-tjänster som App Service, Batch, Service Fabric och andra.

    Dricks

    Ett huvudnamn för tjänsten rekommenderas i flera Kubernetes-scenarier för att hämta avbildningar från ett Azure-containerregister. Med Azure Kubernetes Service (AKS) kan du också använda en automatiserad mekanism för att autentisera med ett målregister genom att aktivera klustrets hanterade identitet.

    • Push: Skapa containeravbildningar och skicka dem till ett register med hjälp av lösningar för kontinuerlig integrering och distribution som Azure Pipelines eller Jenkins.

För individuell åtkomst till ett register, till exempel när du manuellt hämtar en containeravbildning till din utvecklingsarbetsstation, rekommenderar vi att du använder din egen Microsoft Entra-identitet i stället för registeråtkomst (till exempel med az acr-inloggning).

Skapa ett huvudnamn för tjänsten

Om du vill skapa ett huvudnamn för tjänsten med åtkomst till ditt containerregister kör du följande skript i Azure Cloud Shell eller en lokal installation av Azure CLI. Skriptet är formaterat för Bash-gränssnittet.

Innan du kör skriptet uppdaterar du variabeln ACR_NAME med namnet på containerregistret. Värdet SERVICE_PRINCIPAL_NAME måste vara unikt i din Microsoft Entra-klientorganisation. Om du får ett "'http://acr-service-principal' already exists."-fel anger du ett annat namn för tjänstens huvudnamn.

Du kan också ändra --role värdet i kommandot az ad sp create-for-rbac om du vill bevilja olika behörigheter. En fullständig lista över roller finns i ACR-roller och behörigheter.

När du har kört skriptet noterar du tjänstens huvudnamns ID och lösenord. När du har dess autentiseringsuppgifter kan du konfigurera dina program och tjänster för att autentisera till containerregistret som tjänstens huvudnamn.

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

Använda ett befintligt huvudnamn för tjänsten

Om du vill bevilja registeråtkomst till ett befintligt huvudnamn för tjänsten måste du tilldela tjänstens huvudnamn en ny roll. Precis som när du skapar ett nytt huvudnamn för tjänsten kan du bland annat bevilja pull-, push- och pull-åtkomst och ägaråtkomst.

Följande skript använder kommandot az role assignment create för att bevilja pull-behörigheter till ett tjänsthuvudnamn som du anger i variabeln SERVICE_PRINCIPAL_ID . Justera värdet --role om du vill bevilja en annan åtkomstnivå.

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

Exempelskript

Du hittar föregående exempelskript för Azure CLI på GitHub, samt versioner för Azure PowerShell:

Autentisera med tjänstens huvudnamn

När du har ett huvudnamn för tjänsten som du har beviljat åtkomst till containerregistret kan du konfigurera dess autentiseringsuppgifter för åtkomst till "huvudlösa" tjänster och program eller ange dem med hjälp av docker login kommandot . Ange följande värden:

  • Användarnamn – tjänstens huvudnamns program-ID (klient)
  • Lösenord – tjänstens huvudnamns lösenord (klienthemlighet)

Användarnamnvärdet har formatet xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Dricks

Du kan återskapa lösenordet (klienthemligheten) för tjänstens huvudnamn genom att köra kommandot az ad sp credential reset .

Använda autentiseringsuppgifter med Azure-tjänster

Du kan använda autentiseringsuppgifter för tjänstens huvudnamn från valfri Azure-tjänst som autentiserar med ett Azure-containerregister. Använd autentiseringsuppgifterna för tjänstens huvudnamn i stället för registrets administratörsautentiseringsuppgifter för en mängd olika scenarier.

Använda med docker-inloggning

Du kan köra docker login med tjänstens huvudnamn. I följande exempel skickas program-ID:t för tjänstens huvudnamn i miljövariabeln $SP_APP_IDoch lösenordet i variabeln $SP_PASSWD. Rekommenderade metoder för att hantera Docker-autentiseringsuppgifter finns i kommandoreferensen för docker-inloggning .

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

När du har loggat in cachelagrar Docker autentiseringsuppgifterna.

Använda med certifikat

Om du har lagt till ett certifikat i tjänstens huvudnamn kan du logga in på Azure CLI med certifikatbaserad autentisering och sedan använda kommandot az acr login för att komma åt ett register. Att använda ett certifikat som en hemlighet i stället för ett lösenord ger ytterligare säkerhet när du använder CLI.

Du kan skapa ett självsignerat certifikat när du skapar ett huvudnamn för tjänsten. Du kan också lägga till ett eller flera certifikat i ett befintligt huvudnamn för tjänsten. Om du till exempel använder något av skripten i den här artikeln för att skapa eller uppdatera ett huvudnamn för tjänsten med behörighet att hämta eller skicka avbildningar från ett register lägger du till ett certifikat med kommandot az ad sp credential reset .

Om du vill använda tjänstens huvudnamn med certifikat för att logga in på Azure CLI måste certifikatet vara i PEM-format och innehålla den privata nyckeln. Om certifikatet inte är i det format som krävs använder du ett verktyg som openssl för att konvertera det. När du kör az login för att logga in på CLI med tjänstens huvudnamn anger du även tjänstens huvudnamns program-ID och Active Directory-klient-ID. I följande exempel visas dessa värden som miljövariabler:

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

Kör sedan az acr login för att autentisera med registret:

az acr login --name myregistry

CLI använder den token som skapades när du körde az login för att autentisera sessionen med registret.

Skapa tjänstens huvudnamn för scenarier mellan klientorganisationer

Ett huvudnamn för tjänsten kan också användas i Azure-scenarier som kräver att avbildningar hämtas från ett containerregister i ett Microsoft Entra-ID (klientorganisation) till en tjänst eller app i en annan. En organisation kan till exempel köra en app i Klient A som behöver hämta en avbildning från ett delat containerregister i klient B.

Så här skapar du ett tjänsthuvudnamn som kan autentisera med ett containerregister i ett scenario mellan klientorganisationer:

  • Skapa en app för flera klienter (tjänstens huvudnamn) i klientorganisation A
  • Etablera appen i klient B
  • Ge tjänstens huvudnamn behörighet att hämta från registret i klient B
  • Uppdatera tjänsten eller appen i klient A för att autentisera med det nya tjänstens huvudnamn

Exempel på steg finns i Hämta avbildningar från ett containerregister till ett AKS-kluster i en annan AD-klientorganisation.

Förnyelse av tjänstens huvudnamn

Tjänstens huvudnamn skapas med ett års giltighet. Du har alternativ för att förlänga giltigheten ytterligare än ett år, eller ange det förfallodatum som du väljer med hjälp av az ad sp credential reset kommandot .

Nästa steg