Create an Azure service principal with 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. Service principals are user identities created in Azure associated with an existing account. Service principals can have their access roles customized and restricted to only read or write from specific resources.

This article runs you through the steps for creating, getting information about, and resetting a service principal.

Create a service principal

Create a service principal with the az ad sp create-for-rbac command. When creating a service principal, you choose the type of sign-in authentication it uses. The available types of authentication, and details about them, are:

  • By default, password-based authentication is used with a random password generated by the CLI. If you want password-based authentication, this method is recommended.

    az ad sp create-for-rbac --name ServicePrincipalName
    
  • The --password argument uses a user-supplied password for password authentication. When creating a password, make sure you follow the Azure Active Directory password rules and restrictions. Don't use a weak password or reuse a password.

    az ad sp create-for-rbac --name ServicePrincipalName --password <Choose a strong password>
    

    Important

    For security reasons, the --password argument for service principal creation will be deprecated in a future release. If you want to use password-based authentication, avoid --password and let the CLI generate a secure password for you.

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.

  • Use the --cert argument for certificate-based authentication. This method 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.

    az ad sp create-for-rbac --name ServicePrincipalName --cert "-----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----"
    
    az ad sp create-for-rbac --name ServicePrincipalName --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 --cert CertName --keyvault VaultName
    
  • --create-cert creates a self-signed certificate for authentication.

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

    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 --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.

For certificates stored in Key Vault, retrieve the certificate's private key with az keyvault secret show. In Key Vault, the name of the certificate's secret is the same as the certificate name. If you lose access to a certificate's private key, reset the service principal credentials.

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.

Note

If your account doesn't have permission to create a service principal, you see an error message containing "Insufficient privileges to complete the operation." Contact your Azure Active Directory admin to create a service principal.

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:

The default role for a service principal is Contributor. This role has full permissions to read and write to an Azure account, and isn't appropriate for applications. 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

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

The changes can be verified by listing the assigned roles:

az role assignment list --assignee APP_ID

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.

Sign in using a service principal

Test the new service principal's credentials and permissions by signing in under it within the Azure CLI. Sign in as the new service principal using the appId, tenant, and credentials values. Use the authentication type that the service principal was created with.

To sign in with a password, provide it as an argument parameter.

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.

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

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