Create an Azure service principal with Azure CLI
Automated tools that use Azure services should always have restricted permissions to ensure that Azure resources are secure. Therefore, instead of having applications sign in as a fully privileged user, Azure offers service principals. An Azure service principal is an identity created for use with applications, hosted services, and automated tools. This identity is used to access resources.
In this tutorial, you learn how to:
- Create a service principal
- Sign in using a service principal and password
- Sign in using a service principal and certificate
- Manage service principal roles
- Create an Azure resource using a service principal
- Reset service principal credentials
- In a subscription, you must have
User Access Administratoror
Role Based Access Control Administratorpermissions, or higher, to create a service principal. For a list of roles available for Azure role-based access control (Azure RBAC), see Azure built-in roles.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
Create a service principal
Use the az ad sp create-for-rbac Azure CLI reference command to create a service principal. This example doesn't specify a
--name parameter, so a name containing a time stamp is automatically created.
az ad sp create-for-rbac
If you aren't adhering to resource naming conventions and plan to create a role and scope for your new service principal later, the
az ad sp create-for-rbac command without parameters is an acceptable solution. However, without a role and scope, the new service principal doesn't have access to resources. It just exists.
When you create a service principal without parameters, also complete these steps:
- Record your system-assigned password as you can't retrieve it again. If you lose the password, reset it using az ad sp credential reset as explained in Reset service principal credentials.
- Set the role assignment for your new service principal by using az role assignment create as explained in Manage service principal roles.
Create a service principal with role and scope
As a best practice, always assign a specific
--scopes when you create a service principal. Follow these steps:
Determine the correct role.
When determining role, always use the principle of least privilege. For example, don't give your service principal
contributorpermissions to a subscription if the service principal only needs to access Azure storage within a resource group. Consider a specialize role like storage blob data contributor. For a complete list of available roles in Azure RBAC, see Azure built-in roles.
Get a value for the scopes parameter.
Find and copy the Resource ID of the Azure resource the new service principal needs to access. This information is usually found in the Azure portal's Properties or Endpoints page of each resource. Here are common
--scopesexamples, but rely on your Resource ID for an actual format and value.
Scope Example Subscription
Storage account file service
For more scope examples, see Understand scope for Azure RBAC.
Create the service principal.
In this example, a new service principal named myServicePrincipalName1 is created with reader permissions to all resources in resource group RG1.
# Bash script az ad sp create-for-rbac --name myServicePrincipalName1 \ --role reader \ --scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG1
--scopesparameter accepts a space-delimited list of scopes. In this example, a new service principal named myServicePrincipalName2 is created with reader permissions to all resources in resource group myRG1. This service principal is also given reader permissions to myVM located in myRG2.
# Bash script az ad sp create-for-rbac --name myServicePrincipalName2 \ --role reader \ --scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG1 /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG2/providers/Microsoft.Compute/virtualMachines/myVM
If you decide that you granted too few or too many permissions to your new service principal, alter the permissions by managing service principal roles.
Create a service principal using variables
You can also create a service principal using variables:
# Bash script
subscriptionID=$(az account show --query id --output tsv)
# Verify the ID of the active subscription
echo "Using subscription ID $subscriptionID"
echo "Creating SP for RBAC with name $servicePrincipalName, with role $roleName and in scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup"
az ad sp create-for-rbac --name $servicePrincipalName \
--role $roleName \
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.
Now that you've learned how to create an Azure service principal, proceed to the next step to learn how to use service principals with password-based authentication.