Create an Azure service principal with the Azure CLI

Automated tools that use Azure services should always have restricted permissions. Instead of having applications sign in as a fully privileged user, Azure offers service principals.

What is an Azure service principal?

An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. This access is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level. For security reasons, it's always recommended to use service principals with automated tools rather than allowing them to log in with a user identity.

This article shows you the steps for creating, getting information about, and resetting an Azure service principal with the Azure CLI.

Create a service principal

Create an Azure service principal with the az ad sp create-for-rbac command.

The appId and tenant keys appear in the output of az ad sp create-for-rbac and are used in service principal authentication. Record their values, but they can be retrieved at any point with az ad sp list.

When creating a service principal, you choose the type of sign-in authentication it uses. There are two types of authentication available for Azure service principals: password-based authentication, and certificate-based authentication.

Note

If your account doesn't have permission to create a service principal, az ad sp create-for-rbac will return an error message containing "Insufficient privileges to complete the operation." Contact your Azure Active Directory admin to create a service principal.

Warning

When you create an Azure service principal using the az ad sp create-for-rbac command, the output includes credentials that you must protect. Be sure that you do not include these credentials in your code or check the credentials into your source control. As an alternative, consider using managed identities if available to avoid the need to use credentials.

We recommend using Contributor for the --role parameter at a minimum. To reduce your risk of a compromised service principal, assign a more specific role and narrow the scope to a resource or resource group. See Steps to add a role assignment for more information.

Password-based authentication

Without any authentication parameters, password-based authentication is used with a random password created for you.

az ad sp create-for-rbac --name ServicePrincipalName --role Contributor

Important

As of Azure CLI 2.0.68, the --password parameter to create a service principal with a user-defined password is no longer supported to prevent the accidental use of weak passwords.

The output for a service principal with password authentication includes the password key. Make sure you copy this value - it can't be retrieved. If you forget the password, reset the service principal credentials.

Certificate-based authentication

For certificate-based authentication, use the --cert argument. This argument requires that you hold an existing certificate. Make sure any tool that uses this service principal has access to the certificate's private key. Certificates should be in an ASCII format such as PEM, CER, or DER. Pass the certificate as a string, or use the @path format to load the certificate from a file.

Note

When using a PEM file, the CERTIFICATE must be appended to the PRIVATE KEY within the file.

az ad sp create-for-rbac --name ServicePrincipalName --role Contributor --cert "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"
az ad sp create-for-rbac --name ServicePrincipalName --role Contributor --cert @/path/to/cert.pem

The --keyvault argument can be added to use a certificate in Azure Key Vault. In this case, the --cert value is the name of the certificate.

az ad sp create-for-rbac --name ServicePrincipalName --role Contributor --cert CertName --keyvault VaultName

To create a self-signed certificate for authentication, use the --create-cert argument:

az ad sp create-for-rbac --name ServicePrincipalName --role Contributor --create-cert

Console output:

Creating a role assignment under the scope of "/subscriptions/myId"
Please copy C:\myPath\myNewFile.pem to a safe place.
When you run 'az login', provide the file path in the --password argument
{
  "appId": "myAppId",
  "displayName": "myDisplayName",
  "fileWithCertAndPrivateKey": "C:\\myPath\\myNewFile.pem",
  "name": "http://myName",
  "password": null,
  "tenant": "myTenantId"
}

Contents of the new PEM file:

-----BEGIN PRIVATE KEY-----
myPrivateKeyValue
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
myCertificateValue
-----END CERTIFICATE-----

Note

The az ad sp create-for-rbac --create-cert command creates the service principal and a PEM file. The PEM file contains a correctly formatted PRIVATE KEY and CERTIFICATE.

The --keyvault argument can be added to store the certificate in Azure Key Vault. When using --keyvault, the --cert argument is required.

az ad sp create-for-rbac --name ServicePrincipalName --role Contributor --create-cert --cert CertName --keyvault VaultName

Unless you store the certificate in Key Vault, the output includes the fileWithCertAndPrivateKey key. This key's value tells you where the generated certificate is stored. Make sure that you copy the certificate to a secure location, or you can't sign in with this service principal.

If you lose access to a certificate's private key, reset the service principal credentials.

Retrieve certificate from Key Vault

For certificate stored in Key Vault, retrieve the certificate with its private key with az keyvault secret show and convert it to a PEM file. In the Key Vault, the name of the certificate's secret is the same as the certificate name.

az keyvault secret download --file /path/to/cert.pfx --vault-name VaultName --name CertName --encoding base64
openssl pkcs12 -in cert.pfx -passin pass: -out cert.pem -nodes

Get an existing service principal

A list of the service principals in a tenant can be retrieved with az ad sp list. By default this command returns the first 100 service principals for your tenant. To get all of a tenant's service principals, use the --all argument. Getting this list can take a long time, so it's recommended that you filter the list with one of the following arguments:

  • --display-name requests service principals that have a prefix that match the provided name. The display name of a service principal is the value set with the --name parameter during creation. If you didn't set --name during service principal creation, the name prefix is azure-cli-.
  • --spn filters on exact service principal name matching. The service principal name always starts with https://. if the value you used for --name wasn't a URI, this value is https:// followed by the display name.
  • --show-mine requests only service principals created by the signed-in user.
  • --filter takes an OData filter, and performs server-side filtering. This method is recommended over filtering client-side with the CLI's --query argument. To learn about OData filters, see OData expression syntax for filters.

The information returned for service principal objects is verbose. To get only the information necessary for sign-in, use the query string [].{id:appId, tenant:appOwnerTenantId}. For example, to get the sign-in information for all service principals created by the currently logged in user:

az ad sp list --show-mine --query "[].{id:appId, tenant:appOwnerTenantId}"

Important

az ad sp list or az ad sp show get the user and tenant, but not any authentication secrets or the authentication method. Secrets for certificates in Key Vault can be retrieved with az keyvault secret show, but no other secrets are stored by default. If you forget an authentication method or secret, reset the service principal credentials.

Manage service principal roles

The Azure CLI has the following commands to manage role assignments:

We recommend you use the Contributor role at minimum for a service principal. This role has full permissions to read and write to an Azure account. The Reader role is more restrictive, with read-only access. For more information on Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

This example adds the Reader role and removes the Contributor one:

az role assignment create --assignee APP_ID --role Reader
az role assignment delete --assignee APP_ID --role Contributor

Note

If your account doesn't have permission to assign a role, you see an error message that your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write'." Contact your Azure Active Directory admin to manage roles.

Adding a role doesn't restrict previously assigned permissions. When restricting a service principal's permissions, the Contributor role should be removed.

The changes can be verified by listing the assigned roles:

az role assignment list --assignee APP_ID

Sign in using a service principal

Test the new service principal's credentials and permissions by signing in. To sign in with a service principal, you need the appId, tenant, and credentials.

To sign in with a service principal using a password:

az login --service-principal --username APP_ID --password PASSWORD --tenant TENANT_ID

To sign in with a certificate, it must be available locally as a PEM or DER file, in ASCII format. When using a PEM file, the PRIVATE KEY and CERTIFICATE must be appended together within the file.

az login --service-principal --username APP_ID --tenant TENANT_ID --password /path/to/cert

To learn more about signing in with a service principal, see Sign in with the Azure CLI.

Create a resource using service principal

The following section provides an example of how to create an resource for Azure Storage with a service principal, using the following commands:

To sign in with a service principal, you need the appId, tenant, and password returned as the response when you created your service principal.

  1. Log in as the service principal.

    az login --service-principal --username APP_ID --password PASSWORD --tenant TENANT_ID
    
  2. Create a resource group to hold all resources used for the same quickstart, tutorial, or development project.

    az group create --location WESTUS --name MY_RESOURCE_GROUP
    
  3. Create a resource to an Azure service. Replace <SERVICENAME> with the name of the Azure service.

    For Azure Storage, valid values for the <KIND> parameter are:

    • BlobStorage
    • BlockBlobStorage
    • FileStorage
    • Storage
    • StorageV2
    az storage account create --name MY_RESOURCE_<SERVICENAME> --resource-group MY_RESOURCE_GROUP --kind <KIND> --sku F0 --location WESTUS --yes
    
  4. Get resource keys for the new resource, which you use in your code to authenticate to the Azure service.

    az storage account keys list --name MY_RESOURCE_<SERVICENAME> --resource-group MY_RESOURCE_GROUP
    

Reset credentials

If you forget the credentials for a service principal, use az ad sp credential reset. The reset command takes the same arguments as az ad sp create-for-rbac.

az ad sp credential reset --name APP_ID

See also