Create an Azure service principal with Azure CLI 2.0

If you plan to manage your app or service with Azure CLI 2.0, you should run it under an Azure Active Directory (AAD) service principal rather than your own credentials. This topic steps you through creating a security principal with Azure CLI 2.0.


You can also create a service principal through the Azure portal. Read Use portal to create Active Directory application and service principal that can access resources for more details.

What is a 'service principal'?

An Azure service principal is a security identity used by user-created apps, services, and automation tools to access specific Azure resources. Think of it as a 'user identity' (login and password or certificate) with a specific role, and tightly controlled permissions to access your resources. It only needs to be able to do specific things, unlike a general user identity. It improves security if you only grant it the minimum permissions level needed to perform its management tasks.

Right now, Azure CLI 2.0 only supports the creation of password-based authentication credentials. In this topic, we cover creating a service principal with a specific password, and optionally assigning specific roles to it.

Verify your own permission level

First, you must have sufficient permissions in both your Azure Active Directory and your Azure subscription. Specifically, you must be able to create an app in the Active Directory, and assign a role to the service principal.

The easiest way to check whether your account has adequate permissions is through the portal. See Check required permission in portal.

Create a service principal for your application

You must have one of the following to identify the app you want to create a service principal for:

  • The unique name or URI of your deployed app (such as "MyDemoWebApp" in the examples), or
  • the Application ID, the unique GUID associated with your deployed app, service, or object

These values identify your application when creating a service principal.

Get information about your application

Get identity information about your application with the az ad app list.

The Azure Cloud Shell (in public preview) is a web-based shell that is preconfigured to simplify using Azure tools. With Cloud Shell, you always have the most up-to-date version of the tools available and you don’t have to install, update or separately log in. Click the Try It button at the top right of a code block to launch the Cloud Shell. Then, use the Copy button to copy and paste the sample code into the Cloud Shell.

You can also open the Cloud Shell from the Azure portal by clicking the Cloud Shell button on the top navigation.

az ad app list --display-name MyDemoWebApp
    "appId": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
    "appPermissions": null,
    "availableToOtherTenants": false,
    "displayName": "MyDemoWebApp",
    "homepage": "",
    "identifierUris": [
    "objectId": "bd07205b-629f-4a2e-945e-1ee5dadf610b9",
    "objectType": "Application",
    "replyUrls": []

The --display-name option filters the returned list of apps to show those with displayName starting with MyDemoWebApp.

Create the service principal

Use az ad sp create-for-rbac to create the service principal.

az ad sp create-for-rbac --name {appId} --password "{strong password}" 
  "appId": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
  "displayName": "MyDemoWebApp",
  "name": "http://MyDemoWebApp",
  "password": {strong password},

Don't create an insecure password. Follow the Azure AD password rules and restrictions guidance.

Get information about the service principal

az ad sp show --id a487e0c1-82af-47d9-9a0b-af184eb87646d
  "appId": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
  "displayName": "MyDemoWebApp",
  "objectId": "0ceae62e-1a1a-446f-aa56-2300d176659bde",
  "objectType": "ServicePrincipal",
  "servicePrincipalNames": [

Sign in using the service principal

You can now log in as the new service principal for your app using the appId and password from az ad sp show. Supply the tenant value from the results of az ad sp create-for-rbac.

az login --service-principal -u a487e0c1-82af-47d9-9a0b-af184eb87646d --password {password} --tenant {tenant}

You will see this output after a successful sign-on:

    "cloudName": "AzureCloud",
    "id": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
    "isDefault": true,
    "state": "Enabled",
    "user": {
      "name": "https://MyDemoWebApp",
      "type": "servicePrincipal"

Use the id, password, and tenant values as the credentials for running your app.

Managing roles


Azure Role-Based Access Control (RBAC) is a model for defining and managing roles for user and service principals. Roles have sets of permissions associated with them, which determine the resources a principal can read, access, write, or manage. For more information on RBAC and roles, see RBAC: Built-in roles.

The Azure CLI 2.0 provides the following commands to manage role assignments:

The default role for a service principal is Contributor. It may not be the best choice for an app's interactions with Azure services, given its broad permissions. The Reader role is more restrictive and is a good choice for read-only access. You can view details on role-specific permissions or create custom ones through the Azure portal.

In this example, add the Reader role to our prior example, and delete the Contributor one:

az role assignment create --assignee a487e0c1-82af-47d9-9a0b-af184eb87646d --role Reader
az role assignment delete --assignee a487e0c1-82af-47d9-9a0b-af184eb87646d --role Contributor

Verify the changes by listing the currently assigned roles:

az role assignment list --assignee a487e0c1-82af-47d9-9a0b-af184eb87646d
    "id": "/subscriptions/34345f33-0398-4a99-a42b-f6613d1664ac/providers/Microsoft.Authorization/roleAssignments/c27f78a7-9d3b-404b-ab59-47818f9af9ac",
    "name": "c27f78a7-9d3b-404b-ab59-47818f9af9ac",
    "properties": {
      "principalId": "790525226-46f9-4051-b439-7079e41dfa31",
      "principalName": "http://MyDemoWebApp",
      "roleDefinitionId": "/subscriptions/34345f33-0398-4a99-a42b-f6613d1664ac/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
      "roleDefinitionName": "Reader",
      "scope": "/subscriptions/34345f33-0398-4a99-a42b-f6613d1664ac"
    "type": "Microsoft.Authorization/roleAssignments"

If your account does not have sufficient permissions to assign a role, you see an error message. The message states your account "does not have authorization to perform action 'Microsoft.Authorization/roleAssignments/write' over scope '/subscriptions/{guid}'."

Change the credentials of a security principal

It's a good security practice to review permissions and update passwords regularly. You may also want to manage and modify the security credentials as your app changes.

Reset a service principal password

Use az ad sp reset-credentials to reset the current password for the service principal.

az ad sp reset-credentials --name 20bce7de-3cd7-49f4-ab64-bb5b443838c3 --password {new-password}
  "appId": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
  "name": "a487e0c1-82af-47d9-9a0b-af184eb87646d",
  "password": {new-password},

The CLI generates a secure password if you leave out the --password option.