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
Prerequisites
In a subscription, you must have User Access Administrator or Role Based Access Control Administrator permissions, 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.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
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.
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:
If your account doesn't have permission to create a service principal, az ad sp create-for-rbac
returns an error message containing "Insufficient privileges to complete the operation". Contact
your Microsoft Entra admin to create a service principal.
In a Microsoft Entra ID directory where user setting Users can register applications has been
set to No, you must be a member of one of the following Microsoft Entra ID built-in roles
(which have the action: microsoft.directory/applications/createAsOwner or microsoft.directory/applications/create):
As a best practice, always assign a specific --role and --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 contributor permissions 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 --scopes examples, but rely on your Resource ID for an actual format and value.
# Bash script
az ad sp create-for-rbac --name myServicePrincipalName1 \
--role reader \
--scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG1
The --scopes parameter 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
When working in a PowerShell environment, remove Bash line continuation characters.
# PowerShell script
az ad sp create-for-rbac --name myServicePrincipalName1 --role reader --scopes /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG1
The --scopes parameter 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.
# PowerShell 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
let "randomIdentifier=$RANDOM*$RANDOM"
servicePrincipalName="msdocs-sp-$randomIdentifier"
roleName="azureRoleName"
subscriptionID=$(az account show --query id --output tsv)
# Verify the ID of the active subscription
echo "Using subscription ID $subscriptionID"
resourceGroup="myResourceGroupName"
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 \
--scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup
# PowerShell script
$randomIdentifier = (New-Guid).ToString().Substring(0,8)
$servicePrincipalName="msdocs-sp-$randomIdentifier"
$roleName="azureRoleName"
$subscriptionID=$(az account show --query id --output tsv)
$resourceGroup="myResourceGroupName"
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 --scopes /subscriptions/$subscriptionID/resourceGroups/$resourceGroup
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.
Next Steps
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.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Azure CLI feedback
Azure CLI is an open source project. Select a link to provide feedback: