Edit

Tutorial: Use a user-assigned managed identity on a Windows VM to access Azure Resource Manager

  • Article

This tutorial explains how to create a user-assigned identity, assign it to a Windows Virtual Machine (VM), and then use that identity to access the Azure Resource Manager API. Managed Service Identities are automatically managed by Azure. They enable authentication to services that support Microsoft Entra authentication, without needing to embed credentials into your code.

You learn how to:

  • Create a user-assigned managed identity
  • Assign your user-assigned identity to your Windows VM
  • Grant the user-assigned identity access to a Resource Group in Azure Resource Manager
  • Get an access token using the user-assigned identity and use it to call Azure Resource Manager
  • Read the properties of a Resource Group

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. See Install Azure PowerShell to get started. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Prerequisites

  • If you're not familiar with the managed identities for Azure resources feature, see this overview. If you don't have an Azure account, sign up for a free account before you continue.

Configure Azure PowerShell locally

To use Azure PowerShell locally for this article (rather than using Cloud Shell), complete the following steps:

  1. Install the latest version of Azure PowerShell if you haven't already.

  2. Sign in to Azure:

    Connect-AzAccount

  3. Install the latest version of PowerShellGet.

    Install-Module -Name PowerShellGet -AllowPrerelease

    You may need to Exit out of the current PowerShell session after you run this command for the next step.

  4. Install the prerelease version of the Az.ManagedServiceIdentity module to perform the user-assigned managed identity operations in this article:

    Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease

Enable

For a scenario that is based on a user-assigned identity, you need to perform the following steps:

  • Create an identity
  • Assign the newly created identity

Create identity

This section shows how to create a user-assigned identity. A user-assigned identity is created as a standalone Azure resource. Using the New-AzUserAssignedIdentity, Azure creates an identity in your Microsoft Entra tenant that can be assigned to one or more Azure service instances.

Important

When you create user-assigned managed identities, the name must start with a letter or number, and may include a combination of alphanumeric characters, hyphens (-) and underscores (_). For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

New-AzUserAssignedIdentity -ResourceGroupName myResourceGroupVM -Name ID1

The response contains details for the user-assigned identity created, similar to the following example. Note the Id and ClientId values for your user-assigned identity, because they are used in subsequent steps:

{
Id: /subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ID1
ResourceGroupName : myResourceGroupVM
Name: ID1
Location: westus
TenantId: 733a8f0e-ec41-4e69-8ad8-971fc4b533f8
PrincipalId: e591178e-b785-43c8-95d2-1397559b2fb9
ClientId: af825a31-b0e0-471f-baea-96de555632f9
ClientSecretUrl: https://control-westus.identity.azure.net/subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ID1/credentials?tid=733a8f0e-ec41-4e69-8ad8-971fc4b533f8&oid=e591178e-b785-43c8-95d2-1397559b2fb9&aid=af825a31-b0e0-471f-baea-96de555632f9
Type: Microsoft.ManagedIdentity/userAssignedIdentities
}

Assign identity

This section shows how to Assign the user-assigned identity to a Windows VM. A user-assigned identity can be used by clients on multiple Azure resources. Use the following commands to assign the user-assigned identity to a single VM. Use the Id property returned in the previous step for the -IdentityID parameter.

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myVM
Update-AzVM -ResourceGroupName TestRG -VM $vm -IdentityType "UserAssigned" -IdentityID "/subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ID1"

Grant access

This section shows how to grant your user-assigned identity access to a Resource Group in Azure Resource Manager. Managed identities for Azure resources provide identities that your code can use to request access tokens to authenticate to resource APIs that support Microsoft Entra authentication. In this tutorial, your code will access the Azure Resource Manager API.

Before your code can access the API, you need to grant the identity access to a resource in Azure Resource Manager. In this case, the Resource Group in which the VM is contained. Update the value for <SUBSCRIPTIONID> as appropriate for your environment.

$spID = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroupVM -Name ID1).principalid
New-AzRoleAssignment -ObjectId $spID -RoleDefinitionName "Reader" -Scope "/subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/"

The response contains details for the role assignment created, similar to the following example:

RoleAssignmentId: /subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.Authorization/roleAssignments/f9cc753d-265e-4434-ae19-0c3e2ead62ac
Scope: /subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM
DisplayName: ID1
SignInName:
RoleDefinitionName: Reader
RoleDefinitionId: acdd72a7-3385-48ef-bd42-f606fba81ae7
ObjectId: e591178e-b785-43c8-95d2-1397559b2fb9
ObjectType: ServicePrincipal
CanDelegate: False

Access data

Get an access token

Tip

Steps in this article might vary slightly based on the portal you start from.

For the remainder of the tutorial, you will work from the VM we created earlier.

  1. Sign in to the Azure portal.

  2. In the portal, navigate to Virtual Machines and go to the Windows virtual machine and in the Overview, click Connect.

  3. Enter the Username and Password you used when you created the Windows VM.

  4. Now that you have created a Remote Desktop Connection with the virtual machine, open PowerShell in the remote session.

  5. Using PowerShell's Invoke-WebRequest, make a request to the local managed identities for Azure resources endpoint to get an access token for Azure Resource Manager. The client_id value is the value returned when you created the user-assigned managed identity.

    $response = Invoke-WebRequest -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&client_id=af825a31-b0e0-471f-baea-96de555632f9&resource=https://management.azure.com/' -Method GET -Headers @{Metadata="true"}
$content = $response.Content | ConvertFrom-Json
$ArmToken = $content.access_token

Read properties

Use the access token retrieved in the previous step to access Azure Resource Manager, and read the properties of the Resource Group you granted your user-assigned identity access. Replace <SUBSCRIPTION ID> with the subscription ID of your environment.

(Invoke-WebRequest -Uri https://management.azure.com/subscriptions/80c696ff-5efa-4909-a64d-f1b616f423ca/resourceGroups/myResourceGroupVM?api-version=2016-06-01 -Method GET -ContentType "application/json" -Headers @{Authorization ="Bearer $ArmToken"}).content

The response contains the specific Resource Group information, similar to the following example:

{"id":"/subscriptions/<SUBSCRIPTIONID>/resourceGroups/myResourceGroupVM","name":"myResourceGroupVM","location":"eastus","properties":{"provisioningState":"Succeeded"}}

Next steps

In this tutorial, you learned how to create a user-assigned identity and attach it to an Azure Virtual Machine to access the Azure Resource Manager API. To learn more about Azure Resource Manager see:

Azure Resource Manager