Edit

Share via

Create an Azure service principal with Azure CLI

  • Article

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.

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

Output console:

{
  "appId": "myAppId",
  "displayName": "myServicePrincipalName",
  "password": "myServicePrincipalPassword",
  "tenant": "myTentantId"
}

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:

Note

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):

For more information about user settings in Microsoft Entra ID, see Restrict who can create applications.

Create a service principal with role and scope

As a best practice, always assign a specific --role and --scopes when you create a service principal. Follow these steps:

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

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

    Scope Example
    Subscription /subscriptions/mySubscriptionID
    Resource group /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName
    Virtual machine /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myVMname
    Storage account file service /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName/providers/Microsoft.Storage/storageAccounts/myStorageAccountName/fileServices/default
    Data factory /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName/providers/Microsoft.DataFactory/factories/myDataFactoryName

    For more scope examples, see Understand scope for Azure RBAC.

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

    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

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

For a complete list of service principal properties, use az ad sp list and see Get an existing 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.

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.

Use password-based authentication