Authenticate with the service principal - Azure Container Registry (2023)

  • Article
  • 8 minutes to read

You can use an Azure Active Directory (Azure AD) service principal to provide push, pull, or other access to your container registry. By using a service principal, you can provide "headless" access to applications and services.

What is a service principal?

Azure ADservice managerProvide access to Azure resources in your subscription. You can think of a service principal as a user identity for a service, where "service" is any application, service, or platform that needs access to resources. You can configure a service principal with scoped access only to resources that you specify. Then configure your app or service to use the service principal's credentials to access those resources.

In the context of Azure Container Registry, you can create an Azure AD service principal with pull, push, pull, or other permissions for your private registry in Azure. For a complete list, seeAzure Container Registry roles and permissions.

Why use a service principal?

By using an Azure AD service principal, you can provide scoped access to your private container registry. Create different service principals for each of your applications or services, each with custom access rights to your registry. And because you can avoid sharing credentials between services and applications, you can rotate credentials or revoke access only for the service (and therefore application) principal of your choice.

For example, configure your web application to use a service principal that provides an imagefemale dogaccess only while your build system uses a service principal, giving bothPressjfemale dogAccess. If your application development changes hands, you can switch your service principal credentials without affecting the build system.

When to use a service principal

You must use a service principal to provide access to the registry inheadless scenarios. That is, an application, service, or script designed to send or receive container images automatically or unattended. For example:

For individual access to a record, e.g. B. If you manually push a container image to your development workstation, we recommend using your ownAzure AD Identityinstead of registry access (e.g. withlogar acr az).

Create a service principal

To create a service principal with access to your container registry, run the following script inblue cloud shellor a local installation ofCLI do Azure. The script is formatted for the bash shell.

Before running the script, update theACR_NAME-Variable with the name of your container registry. HimSERVICE_MAIN_NAMEThe value must be unique within your Azure Active Directory tenant. If you have one ""http://acr-service-principal" already exists."Error, please provide a different service principal name.

You can change the optional--Rolevalue notcreate az ad sp for rbaccommand if you want to grant other permissions. For a complete list of features, seeACR roles and permissions.

After running the script, make a note of the service principalI COULDjpassword. Once you have your credentials, you can configure your applications and services to authenticate your container registry as a service principal.

#!/bin/bash# This script requires Azure CLI version 2.25.0 or later. Check the version with `az --version`.# Customize for your environment.# ACR_NAME: The name of your Azure Container Registry# SERVICE_PRINCIPAL_NAME: Must be unique within your tenant ADACR_NAME=$containerRegistrySERVICE_PRINCIPAL_NAME=$servicePrincipal# Get the full registry IDACR_REGISTRY_ID = $(az acr show --name $ACR_NAME --query "id" --output tsv)# echo $registryId# Creates the service principal with rights to the registry area.# Default permissions apply to the registry Docker pull access. Change the value of the --role# argument as desired:# acrpull: pull only# acrpush: push and pull# Property: push, pull, and role assignmentPASSWORD=$(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) # Displays the service principal's credentials; Use them in your # services and applications to authenticate with the container registry. echo "Service Principal ID: $USER_NAME" echo "Service Principal Password: $PASSWORD"

Use an existing service principal

To grant registry access to an existing service principal, you must grant the service principal a new role. As with creating a new service principal, you can grant pull, push, pull, owner access, and more.

The following script uses theCreate z role assignmentissue an orderfemale dogPermissions for a service principal that you specify in theSERVICE_MAIN_IDVariable. adjust to--Rolevalue if you want to grant a different level of access.

#!/bin/bash# Adapt to your environment. ACR_NAME is the name of the Azure Container Registry # and SERVICE_PRINCIPAL_ID is the appId of the service principal or one of its servicePrincipalNames values. az acr show --name $ACR_NAME --query id --output tsv)# Assign the desired role to the service principal. Change the value of the '--role' argument as desired:# acrpull: just pull# acrpush: push and pull# Owner: move, pull, and assign roles az Create role assignment --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID -- role draw

sample scripts

You can find previous sample Azure CLI scripts on GitHub, as well as Azure PowerShell versions:

Authenticate to the service principal

Once you have a service principal granted access to your container registry, you can configure your credentials to access services and applications without an interface or sign in with theLogin do DockerDomain. Use the following values:

  • username- EmployerApplication Identification (Client)
  • password- EmployerPassword (client secret)

IT ISusernameThe value has the formatxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.


You can regenerate the password (client secret) for a service principal using theReset az ad sp credentialsDomain.

Use credentials with Azure services

You can use the service principal credentials of any Azure service that authenticates to an Azure container registry. Use service principal credentials instead of registry administrator credentials for a variety of scenarios.

For example, use credentials to get an image of an Azure container registryAzure-Containerinstanzen.

Use with Docker login

you can runLogin do DockerUsing a service principal. In the following example, the service principal's Application ID is passed to the environment variable$SP_APP_ID, and the password in the variable$SP_PASSWD. For best practices for managing Docker credentials, seeLogin do Dockercommand reference.

# Sign in to Docker using the service docker master login credentials --username $SP_APP_ID --password $SP_PASSWD

After logging in, Docker caches the credentials.

use with certificate

If you've added a certificate to your service principal, you can sign in to the Azure CLI using certificate-based authentication and then thelogar acr azCommand to access a record. Using a certificate as a secret instead of a password provides additional security when using the CLI.

A self-signed certificate can be created ifCreate a service principal. Or, add one or more certificates to an existing service principal. For example, if you use one of the scripts in this article to create or update a service principal with rights to extract or upload images from a record, use this to add a certificateReset az ad sp credentialsDomain.

How to use service principal with certificate forSign in to the Azure CLI, the certificate must be in PEM format and contain the private key. If your certificate is not in the required format, use a tool likeabslto convert it. when you runregistrar isTo log in to the CLI using the service principal, also provide the service principal application ID and Active Directory tenant ID. The following example displays these values ​​as environment variables:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID --password /ruta/al/cert/pem/archivo

so runlogar acr azto authenticate no record:

az acr login --name my registration

CLI uses token created at runtimeregistrar isto authenticate your session after registration.

Create a service principal for cross-tenant scenarios

A service principal can also be used in Azure scenarios that require pulling images from a container registry in one Azure Active Directory (tenant) to a service or application in another. For example, an organization might run an application in Tenant A that needs to pull an image from a shared container registry in Tenant B.

To create a service principal that can authenticate to a container registry in a cross-tenant scenario:

  • To... createmultiuser application(service provider) in tenant A
  • Deploy the app to Tenant B
  • Give the service principal permissions to extract from registry in tenant B
  • Update the service or application in Tenant A to authenticate with the new service principal

For example steps, seePull images from a container registry to an AKS cluster in a different AD tenant.

Major service renewal

The service customer is created with a validity of one year. You have the option to extend the validity beyond one year, or you can include the expiration date of your choice.Reset az ad sp credentialsDomain.

Next steps

  • Observe-osAuthentication Overviewfor other scenarios to authenticate against an Azure container registry.

  • For an example of using an Azure keystore to store and retrieve service principal credentials for a container registry, see the tutorial forCreate and deploy a container image using ACR tasks.

Top Articles
Latest Posts
Article information

Author: Errol Quitzon

Last Updated: 03/14/2023

Views: 6110

Rating: 4.9 / 5 (79 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Errol Quitzon

Birthday: 1993-04-02

Address: 70604 Haley Lane, Port Weldonside, TN 99233-0942

Phone: +9665282866296

Job: Product Retail Agent

Hobby: Computer programming, Horseback riding, Hooping, Dance, Ice skating, Backpacking, Rafting

Introduction: My name is Errol Quitzon, I am a fair, cute, fancy, clean, attractive, sparkling, kind person who loves writing and wants to share my knowledge and understanding with you.