Authenticate Azure-hosted Java apps to Azure resources by using a user-assigned managed identity

The recommended approach to authenticate an Azure-hosted app to other Azure resources is to use a managed identity. Most Azure services support this approach, including apps hosted on Azure App Service, Azure Container Apps, and Azure Virtual Machines. For more information, see Azure services and resource types supporting managed identities. For more information about different authentication techniques and approaches, see Authenticate Java apps to Azure services by using the Azure Identity library.

In the following sections, you learn about:

• Essential managed identity concepts.
• How to create a user-assigned managed identity for your app.
• How to assign roles to the user-assigned managed identity.
• How to authenticate by using the user-assigned managed identity from your app code.

Essential managed identity concepts

A managed identity enables your app to securely connect to other Azure resources without the use of secret keys or other application secrets. Internally, Azure tracks the identity and which resources it's allowed to connect to. Azure uses this information to automatically obtain Microsoft Entra tokens for the app to allow it to connect to other Azure resources.

There are two types of managed identities to consider when configuring your hosted app:

• System-assigned managed identities are enabled directly on an Azure resource and are tied to its life cycle. When the resource is deleted, Azure automatically deletes the identity for you. System-assigned identities provide a minimalistic approach to using managed identities.
• User-assigned managed identities are created as standalone Azure resources and offer greater flexibility and capabilities. They're ideal for solutions involving multiple Azure resources that need to share the same identity and permissions. For example, if multiple virtual machines need to access the same set of Azure resources, a user-assigned managed identity provides reusability and optimized management.

Tip

Learn more about selecting and managing system-assigned and user-assigned managed identities in the Managed identity best practice recommendations article.

The following sections describe the steps to enable and use a user-assigned managed identity for an Azure-hosted app. If you need to use a system-assigned managed identity, see Authenticate Azure-hosted Java apps to Azure resources using a system-assigned managed identity.

Create a user-assigned managed identity

User-assigned managed identities are created as standalone resources in your Azure subscription using the Azure portal or the Azure CLI. Azure CLI commands can be run in the Azure Cloud Shell or on a workstation with the Azure CLI installed.

Azure portal

1. In the Azure portal, enter Managed identities in the main search bar and select the matching result under the Services section.

2. On the Managed Identities page, select + Create.

   

3. On the Create User Assigned Managed Identity page, select a subscription, resource group, and region for the user-assigned managed identity, and then provide a name.

4. Select Review + create to review and validate your inputs.

   

5. Select Create to create the user-assigned managed identity.

6. After the identity is created, select Go to resource.

7. On the new identity's Overview page, copy the Client ID value to use for later when you configure the application code.

Azure CLI

Use the Azure CLI command az identity create to create a managed identity:

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

The command output prints the client ID of the created user-assigned managed identity. The client ID is used to configure application code that relies on the identity.

You can always view the managed identity properties again using the az identity show command:

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

Assign the managed identity to your app

A user-assigned managed identity can be associated with one or more Azure resources. All of the resources that use that identity gain the permissions applied through the identity's roles.

Azure portal

1. In the Azure portal, navigate to the resource that hosts your app code, such as an Azure App Service or Azure Container Apps instance.

2. From the resource's Overview page, expand Settings and select Identity from the navigation.

3. On the Identity page, switch to the User assigned tab.

4. Select + Add to open the Add user assigned managed identity panel.

5. On the Add user assigned managed identity panel, use the Subscription dropdown to filter the search results for your identities. Use the User assigned managed identities search box to locate the user-assigned managed identity you enabled for the Azure resource hosting your app.

6. Select the identity and choose Add at the bottom of the panel to continue.

   

Azure CLI

The Azure CLI provides different commands to assign a user-assigned managed identity to different types of hosting services.

1. To assign a user-assigned managed identity to a resource such as an Azure App Service web app using the Azure CLI, you'll need the resource ID of the identity. Use the az identity show command to retrieve the resource ID:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query id
   

2. Once you have the resource ID, use the Azure CLI command az <resourceType> identity assign command to associate the user-assigned managed identity with different resources, such as the following:

   For Azure App Service, use the Azure CLI command az webapp identity assign:

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <webapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   For Azure Container Apps, use the Azure CLI command az containerapp identity assign:

   az containerapp identity assign \
       --resource-group <resource-group-name> \
       --name <containerapp-name> \
       --user-assigned <user-assigned-identity-resource-id>
   

   For Azure Virtual Machines, use the Azure CLI command az vm identity assign:

   az vm identity assign \
       --resource-group <resource-group-name> \
       --name <vm-name> \
       --identities <user-assigned-identity-resource-id>
   

Assign roles to the managed identity

Next, determine which roles your app needs and assign those roles to the managed identity. You can assign roles to a managed identity at the following scopes:

• Resource: The assigned roles only apply to that specific resource.
• Resource group: The assigned roles apply to all resources contained in the resource group.
• Subscription: The assigned roles apply to all resources contained in the subscription.

The following example shows how to assign roles at the resource group scope, since many apps manage all their related Azure resources using a single resource group.

Azure portal

1. Navigate to the Overview page of the resource group that contains the app with the user-assigned managed identity.

2. Select Access control (IAM) on the left navigation.

3. On the Access control (IAM) page, select + Add on the top menu and then choose Add role assignment to navigate to the Add role assignment page.

   

4. The Add role assignment page presents a tabbed, multi-step workflow to assign roles to identities. On the initial Role tab, use the search box at the top to locate the role you want to assign to the identity.

5. Select the role from the results and then choose Next to move to the Members tab.

6. For the Assign access to option, select Managed identity.

7. For the Members option, choose + Select members to open the Select managed identities panel.

8. On the Select managed identities panel, use the Subscription and Managed identity dropdowns to filter the search results for your identities. Use the Select search box to locate the user-assigned managed identity you enabled for the Azure resource hosting your app.

   

9. Select the identity and choose Select at the bottom of the panel to continue.

10. Select Review + assign at the bottom of the page.

11. On the final Review + assign tab, select Review + assign to complete the workflow.

Azure CLI

1. To assign a role to a user-assigned managed identity using the Azure CLI, you'll need the principal ID of the identity. Use the az identity show command to retrieve the principal ID:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query principalId
   

2. Use the az role definition list command to explore which roles a managed identity can be assigned:

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

3. Assign a role to a managed identity using the az role assignment create command:

   az role assignment create \
       --assignee <your-principal-id> \
       --role <role-name> \
       --scope <scope>
   

   For example, to allow the managed identity with the ID of 99999999-9999-9999-9999-999999999999 read, write, and delete access to Azure Storage blob containers and data to all storage accounts in the msdocs-sdk-auth-example resource group, assign the application service principal to the Storage Blob Data Contributor role using the following command:

   az role assignment create \
       --assignee 99999999-9999-9999-9999-999999999999 \
       --role "Storage Blob Data Contributor" \
       --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-sdk-auth-example"
   

For information on assigning permissions at the resource or subscription level using the Azure CLI, see the article Assign Azure roles using the Azure CLI.

Authenticate to Azure services from your app

The Azure Identity library offers different credentials as implementations of TokenCredential. Each implementation supports different scenarios and Microsoft Entra authentication flows. For user-assigned managed identities, specify the identity's client ID, resource ID, or object ID when you configure the credential.

Implement the code

Add the azure-identity dependency to your pom.xml file:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

You access Azure services by using specialized client classes from the Azure SDK client libraries. The following code examples show you how to configure the credential for user-assigned managed identity authentication.

Use DefaultAzureCredential

Use DefaultAzureCredential as the credential for Azure-hosted apps. For user-assigned managed identities, configure the client ID by using the managedIdentityClientId method:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;

// Configure DefaultAzureCredential with the user-assigned managed identity's client ID
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .managedIdentityClientId("<user-assigned-managed-identity-client-id>")
    .build();

// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

Use ManagedIdentityCredential

If you want to explicitly use the managed identity credential and avoid the credential chain lookup in DefaultAzureCredential, use ManagedIdentityCredential directly. For user-assigned managed identities, you can specify the identity by using the client ID, resource ID, or object ID.

Client ID

Use the client ID to identify a managed identity when you configure applications or services that need to authenticate by using that identity.

Retrieve the client ID assigned to a user-assigned managed identity by using the following command:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query clientId \
    --output tsv

Configure ManagedIdentityCredential with the client ID:

import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;

// Specify the client ID of the user-assigned managed identity
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .clientId("<user-assigned-managed-identity-client-id>")
    .build();

// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

Resource ID

The resource ID is the full Azure Resource Manager (ARM) path to the user-assigned managed identity resource.

Retrieve the resource ID assigned to a user-assigned managed identity by using the following command:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query id \
    --output tsv

Configure ManagedIdentityCredential with the resource ID:

import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;

// Specify the resource ID of the user-assigned managed identity
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .resourceId("/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>")
    .build();

// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

Object ID

The object ID is the unique identifier of the managed identity's service principal in Microsoft Entra ID.

Retrieve the object ID assigned to a user-assigned managed identity by using the following command:

az identity show \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query principalId \
    --output tsv

Configure ManagedIdentityCredential with the object ID:

import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;

// Specify the object ID of the user-assigned managed identity
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .objectId("<user-assigned-managed-identity-object-id>")
    .build();

// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://<your-key-vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

Next steps

This article covered authentication using a user-assigned managed identity. This form of authentication is one of multiple ways you can authenticate in the Azure SDK for Java. The following articles describe other ways to authenticate:

• Authenticate Azure-hosted Java apps to Azure resources by using a system-assigned managed identity
• Authenticate Java apps to Azure services during local development by using developer accounts
• Authenticate Java apps to Azure services during local development by using service principals

If you run into issues related to Azure-hosted application authentication, see Troubleshoot Azure-hosted application authentication.

After you master authentication, see Configure logging in the Azure SDK for Java for information on the logging functionality provided by the SDK.