How to use managed identities for App Service and Azure Functions

Note

Starting June 1, 2024, all newly created App Service apps will have the option to generate a unique default hostname using the naming convention <app-name>-<random-hash>.<region>.azurewebsites.net. Existing app names will remain unchanged.

Example: myapp-ds27dh7271aah175.westus-01.azurewebsites.net

For further details, refer to Unique Default Hostname for App Service Resource.

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

Because managed identities don't support cross-directory scenarios, they won't behave as expected if your app is migrated across subscriptions or tenants. To recreate the managed identities after such a move, see Will managed identities be recreated automatically if I move a subscription to another directory?. 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 Microsoft Entra ID allows your app to easily access other Microsoft Entra 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 Microsoft Entra ID, see Managed identities for Azure resources.

Your application can be granted two types of identities:

  • A system-assigned identity is tied to the app and is deleted if the 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, and one user-assigned identity can be assigned to multiple Azure resources, such as two App Service apps.

The managed identity configuration is specific to the slot. To configure a managed identity for a deployment slot in the portal, navigate to the slot first. To find the managed identity for your web app or deployment slot in your Microsoft Entra tenant from the Azure portal, search for it directly from the Overview page of your tenant. Usually, the slot name is similar to <app-name>/slots/<slot-name>.

This video shows you how to use managed identities for App Service.

The steps in the video are also described in the following sections.

Add a system-assigned identity

  1. Access your app's settings in the Azure portal under the Settings group in the left navigation pane.

  2. Select Identity.

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

    Screenshot that shows where to switch Status to On and then select Save.

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.

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. Select User assigned > Add.

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

    Managed identity in App Service

    Once you select Add, the app restarts.

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 Microsoft Entra tokens, see Azure services that support Microsoft Entra authentication.

Important

The back-end services for managed identities maintain a cache per resource URI for around 24 hours. This means that it can take several hours for changes to a managed identity's group or role membership to take effect. Today, it is not possible to force a managed identity's token to be refreshed before its expiry. If you change a managed identity’s group or role membership to add or remove permissions, you may therefore need to wait several hours for the Azure resource using the identity to have the correct access. For alternatives to groups or role memberships, see Limitation of using managed identities for authorization.

Connect to Azure services in app code

With its managed identity, an app can obtain tokens for Azure resources that are protected by Microsoft Entra ID, 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.

A raw HTTP GET request uses the two supplied environment variables and looks like the following example:

GET /MSI/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1
Host: <ip-address-:-port-in-IDENTITY_ENDPOINT>
X-IDENTITY-HEADER: <value-of-IDENTITY_HEADER>

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": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

This response is the same as the response for the Microsoft Entra 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.

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 Microsoft Entra ID. System-assigned identities are also automatically removed from Microsoft Entra ID when you delete the app resource itself.

  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: Select the User assigned tab, select the checkbox for the identity, and select Remove. Select Yes to confirm.

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 Microsoft Entra resource URI of the resource for which a token should be obtained. This could be one of the Azure services that support Microsoft Entra 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