How to use managed identities for App Service and Azure Functions

This article shows you how to create a managed identity for App Service and Azure Functions applications and how to use it to access other resources.

Important

Managed identities for App Service and Azure Functions won't behave as expected if your app is migrated across subscriptions/tenants. The app needs to obtain a new identity, which is done by disabling and re-enabling the feature. Downstream resources also need to have access policies updated to use the new identity.

Note

Managed identities are not available for apps deployed in Azure Arc.

A managed identity from Azure Active Directory (Azure AD) allows your app to easily access other Azure AD-protected resources such as Azure Key Vault. The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. For more about managed identities in Azure AD, see Managed identities for Azure resources.

Your application can be granted two types of identities:

• A system-assigned identity is tied to your application and is deleted if your app is deleted. An app can only have one system-assigned identity.
• A user-assigned identity is a standalone Azure resource that can be assigned to your app. An app can have multiple user-assigned identities.

Add a system-assigned identity

Azure portal

1. In the left navigation of your app's page, scroll down to the Settings group.

2. Select Identity.

3. Within the System assigned tab, switch Status to On. Click Save.

   

Note

To find the managed identity for your web app or slot app in the Azure portal, under Enterprise applications, look in the User settings section. Usually, the slot name is similar to <app name>/slots/<slot name>.

Azure CLI

Run the az webapp identity assign command to create a system-assigned identity:

az webapp identity assign --name myApp --resource-group myResourceGroup

Azure PowerShell

For App Service

Run the Set-AzWebApp -AssignIdentity command to create a system-assigned identity for App Service:

Set-AzWebApp -AssignIdentity $true -Name <app-name> -ResourceGroupName <group-name> 

For Functions

Run the Update-AzFunctionApp -IdentityType command to create a system-assigned identity for a function app:

Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType SystemAssigned

ARM template

An Azure Resource Manager template can be used to automate deployment of your Azure resources. To learn more about deploying to App Service and Functions, see Automating resource deployment in App Service and Automating resource deployment in Azure Functions.

Any resource of type Microsoft.Web/sites can be created with an identity by including the following property in the resource definition:

"identity": {
    "type": "SystemAssigned"
}

Adding the system-assigned type tells Azure to create and manage the identity for your application.

For example, a web app's template might look like the following JSON:

{
    "apiVersion": "2016-08-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "SystemAssigned"
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
    ]
}

When the site is created, it has the following additional properties:

"identity": {
    "type": "SystemAssigned",
    "tenantId": "<TENANTID>",
    "principalId": "<PRINCIPALID>"
}

The tenantId property identifies what Azure AD tenant the identity belongs to. The principalId is a unique identifier for the application's new identity. Within Azure AD, the service principal has the same name that you gave to your App Service or Azure Functions instance.

If you need to reference these properties in a later stage in the template, you can do so via the reference() template function with the 'Full' flag, as in this example:

{
    "tenantId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.tenantId]",
    "objectId": "[reference(resourceId('Microsoft.Web/sites', variables('appName')), '2018-02-01', 'Full').identity.principalId]",
}

Add a user-assigned identity

Creating an app with a user-assigned identity requires that you create the identity and then add its resource identifier to your app config.

Azure portal

First, you'll need to create a user-assigned identity resource.

1. Create a user-assigned managed identity resource according to these instructions.

2. In the left navigation for your app's page, scroll down to the Settings group.

3. Select Identity.

4. Within the User assigned tab, click Add.

5. Search for the identity you created earlier and select it. Click Add.

   

Important

If you select Add after you select a user-assigned identity to add, your application will restart.

Azure CLI

1. Create a user-assigned identity.

   az identity create --resource-group <group-name> --name <identity-name>
   

2. Run the az webapp identity assign command to assign the identity to the app.

   az webapp identity assign --resource-group <group-name> --name <app-name> --identities <identity-name>
   

Azure PowerShell

For App Service

Adding a user-assigned identity in App Service is currently not supported.

For Functions

1. Create a user-assigned identity.

   Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
   $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName <group-name>
   

2. Run the Update-AzFunctionApp -IdentityType UserAssigned -IdentityId command to assign the identity in Functions:

   Update-AzFunctionApp -Name <app-name> -ResourceGroupName <group-name> -IdentityType UserAssigned -IdentityId $userAssignedIdentity.Id
   

ARM template

An Azure Resource Manager template can be used to automate deployment of your Azure resources. To learn more about deploying to App Service and Functions, see Automating resource deployment in App Service and Automating resource deployment in Azure Functions.

Any resource of type Microsoft.Web/sites can be created with an identity by including the following block in the resource definition, replacing <RESOURCEID> with the resource ID of the desired identity:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

Note

An application can have both system-assigned and user-assigned identities at the same time. In this case, the type property would be SystemAssigned,UserAssigned

Adding the user-assigned type tells Azure to use the user-assigned identity specified for your application.

For example, a web app's template might look like the following JSON:

{
    "apiVersion": "2016-08-01",
    "type": "Microsoft.Web/sites",
    "name": "[variables('appName')]",
    "location": "[resourceGroup().location]",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
        }
    },
    "properties": {
        "name": "[variables('appName')]",
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "hostingEnvironment": "",
        "clientAffinityEnabled": false,
        "alwaysOn": true
    },
    "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
    ]
}

When the site is created, it has the following additional properties:

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {
            "principalId": "<PRINCIPALID>",
            "clientId": "<CLIENTID>"
        }
    }
}

The principalId is a unique identifier for the identity that's used for Azure AD administration. The clientId is a unique identifier for the application's new identity that's used for specifying which identity to use during runtime calls.

Configure target resource

You may need to configure the target resource to allow access from your app or function. For example, if you request a token to access Key Vault, you must also add an access policy that includes the managed identity of your app or function. Otherwise, your calls to Key Vault will be rejected, even if you use a valid token. The same is true for Azure SQL Database. To learn more about which resources support Azure Active Directory tokens, see Azure services that support Azure AD authentication.

Important

The back-end services for managed identities maintain a cache per resource URI for around 24 hours. If you update the access policy of a particular target resource and immediately retrieve a token for that resource, you may continue to get a cached token with outdated permissions until that token expires. There's currently no way to force a token refresh.

Connect to Azure services in app code

With its managed identity, an app can obtain tokens for Azure resources that are protected by Azure Active Directory, such as Azure SQL Database, Azure Key Vault, and Azure Storage. These tokens represent the application accessing the resource, and not any specific user of the application.

App Service and Azure Functions provide an internally accessible REST endpoint for token retrieval. The REST endpoint can be accessed from within the app with a standard HTTP GET, which can be implemented with a generic HTTP client in every language. For .NET, JavaScript, Java, and Python, the Azure Identity client library provides an abstraction over this REST endpoint and simplifies the development experience. Connecting to other Azure services is as simple as adding a credential object to the service-specific client.

HTTP GET

A raw HTTP GET request looks like the following example:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: localhost:4141
X-IDENTITY-HEADER: 853b9a84-5bfa-4b22-a3f3-0b9a43d9ad8a

And a sample response might look like the following:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi…",
    "expires_on": "1586984735",
    "resource": "https://vault.azure.net",
    "token_type": "Bearer",
    "client_id": "5E29463D-71DA-4FE0-8E69-999B57DB23B0"
}

This response is the same as the response for the Azure AD service-to-service access token request. To access Key Vault, you will then add the value of access_token to a client connection with the vault.

.NET

Note

When connecting to Azure SQL data sources with Entity Framework Core, consider using Microsoft.Data.SqlClient, which provides special connection strings for managed identity connectivity. For an example, see Tutorial: Secure Azure SQL Database connection from App Service using a managed identity.

For .NET apps and functions, the simplest way to work with a managed identity is through the Azure Identity client library for .NET. For detailed guidance, see Tutorial: Connect to Azure databases from App Service without secrets using a managed identity.

See the respective documentation headings of the client library for information:

• Add Azure Identity client library to your project
• Access Azure service with a system-assigned identity
• Access Azure service with a user-assigned identity

The linked examples use DefaultAzureCredential. It's useful for the majority of the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

JavaScript

For Node.js apps and JavaScript functions, the simplest way to work with a managed identity is through the Azure Identity client library for JavaScript. For detailed guidance, see Tutorial: Connect to Azure databases from App Service without secrets using a managed identity.

See the respective documentation headings of the client library for information:

• Add Azure Identity client library to your project
• Access Azure service with a system-assigned identity
• Access Azure service with a user-assigned identity

The linked examples use DefaultAzureCredential. It's useful for the majority of the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

For more code examples of the Azure Identity client library for JavaScript, see Azure Identity examples.

Python

For Python apps and functions, the simplest way to work with a managed identity is through the Azure Identity client library for Python. For detailed guidance, see Tutorial: Connect to Azure databases from App Service without secrets using a managed identity.

See the respective documentation headings of the client library for information:

• Add Azure Identity client library to your project
• Access Azure service with a system-assigned identity
• Access Azure service with a user-assigned identity

The linked examples use DefaultAzureCredential. It's useful for the majority of the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

Java

For Java apps and functions, the simplest way to work with a managed identity is through the Azure Identity client library for Java. For detailed guidance, see Tutorial: Connect to Azure databases from App Service without secrets using a managed identity.

See the respective documentation headings of the client library for information:

• Add Azure Identity client library to your project
• Access Azure service with a system-assigned identity
• Access Azure service with a user-assigned identity

The linked examples use DefaultAzureCredential. It's useful for the majority of the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

For more code examples of the Azure Identity client library for Java, see Azure Identity Examples.

PowerShell

Use the following script to retrieve a token from the local endpoint by specifying a resource URI of an Azure service:

$resourceURI = "https://<AAD-resource-URI-for-resource-to-obtain-token>"
$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"
$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI
$accessToken = $tokenResponse.access_token

For more information on the REST endpoint, see REST endpoint reference.

Remove an identity

When you remove a system-assigned identity, it's deleted from Azure Active Directory. System-assigned identities are also automatically removed from Azure Active Directory when you delete the app resource itself.

Azure portal

1. In the left navigation of your app's page, scroll down to the Settings group.

2. Select Identity. Then follow the steps based on the identity type:

   • System-assigned identity: Within the System assigned tab, switch Status to Off. Click Save.
   • User-assigned identity: Click the User assigned tab, select the checkbox for the identity, and click Remove. Click Yes to confirm.

Azure CLI

To remove the system-assigned identity:

az webapp identity remove --name <app-name> --resource-group <group-name>

To remove one or more user-assigned identities:

az webapp identity remove --name <app-name> --resource-group <group-name> --identities <identity-name1>,<identity-name2>,...

You can also remove the system assigned identity by specifying [system] in --identities.

Azure PowerShell

For App Service

Run the Set-AzWebApp -AssignIdentity command to remove a system-assigned identity for App Service:

Set-AzWebApp -AssignIdentity $false -Name <app-name> -ResourceGroupName <group-name> 

For Functions

To remove all identities in Azure PowerShell (Azure Functions only):

# Update an existing function app to have IdentityType "None".
Update-AzFunctionApp -Name $functionAppName -ResourceGroupName $resourceGroupName -IdentityType None

ARM template

To remove all identities in an ARM template:

"identity": {
    "type": "None"
}

Note

There is also an application setting that can be set, WEBSITE_DISABLE_MSI, which just disables the local token service. However, it leaves the identity in place, and tooling will still show the managed identity as "on" or "enabled." As a result, use of this setting is not recommended.

REST endpoint reference

An app with a managed identity makes this endpoint available by defining two environment variables:

• IDENTITY_ENDPOINT - the URL to the local token service.
• IDENTITY_HEADER - a header used to help mitigate server-side request forgery (SSRF) attacks. The value is rotated by the platform.

The IDENTITY_ENDPOINT is a local URL from which your app can request tokens. To get a token for a resource, make an HTTP GET request to this endpoint, including the following parameters:

Parameter name	In	Description
resource	Query	The Azure AD resource URI of the resource for which a token should be obtained. This could be one of the Azure services that support Azure AD authentication or any other resource URI.
api-version	Query	The version of the token API to be used. Use 2019-08-01.
X-IDENTITY-HEADER	Header	The value of the IDENTITY_HEADER environment variable. This header is used to help mitigate server-side request forgery (SSRF) attacks.
client_id	Query	(Optional) The client ID of the user-assigned identity to be used. Cannot be used on a request that includes principal_id, mi_res_id, or object_id. If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.
principal_id	Query	(Optional) The principal ID of the user-assigned identity to be used. object_id is an alias that may be used instead. Cannot be used on a request that includes client_id, mi_res_id, or object_id. If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.
mi_res_id	Query	(Optional) The Azure resource ID of the user-assigned identity to be used. Cannot be used on a request that includes principal_id, client_id, or object_id. If all ID parameters (client_id, principal_id, object_id, and mi_res_id) are omitted, the system-assigned identity is used.

Important

If you are attempting to obtain tokens for user-assigned identities, you must include one of the optional properties. Otherwise the token service will attempt to obtain a token for a system-assigned identity, which may or may not exist.

Next steps

• Tutorial: Connect to SQL Database from App Service without secrets using a managed identity
• Access Azure Storage securely using a managed identity
• Call Microsoft Graph securely using a managed identity
• Connect securely to services with Key Vault secrets