Tutorial: Use a Windows VM/VMSS to access Azure resources

Use a Windows VM system-assigned managed identity to access Azure Storage

This tutorial shows you how to use a system-assigned managed identity for a Windows virtual machine (VM) to access Azure Storage. You learn how to:

Enable

Enabling a system-assigned managed identity is a one-click experience. You can either enable it during the creation of a VM or in the properties of an existing VM.

To enable a system-assigned managed identity on a new VM:

1. Sign in to the Azure portal.

2. Create a virtual machine with system-assigned identity enabled.

Create storage account

In this section, you create a storage account.

1. Select the + Create a resource button found on the upper-left corner of the Azure portal.

2. Select Storage, then Storage account - blob, file, table, queue.

3. In the Name field, enter a name for the storage account.

4. Deployment model and Account kind should be set to Resource manager and Storage (general purpose v1).

5. Ensure the Subscription and Resource Group match the ones you specified when you created your VM in the previous step.

6. Select Create.

   

Create a blob container and upload a file to the storage account

Files require blob storage so you need to create a blob container in which to store the file. You then upload a file to the blob container in the new storage account.

1. Navigate to your newly created storage account.

2. In the Blob Service section, select Containers.

3. Select + Container on the top of the page.

4. In the New container field, enter a name for the container, then in the Public access level option, keep the default value.

   

5. Using an editor of your choice, create a file titled hello world.txt on your local machine. Open the file and add the text Hello world!, then save it.

6. Select the container name to upload the file to the newly created container, then select Upload.

7. In the Upload blob pane, in the Files section, select the folder icon and browse to the file hello_world.txt on your local machine. Then select the file and Upload.

Grant access

This section shows how to grant your VM access to an Azure Storage container. You can use the VM's system-assigned managed identity to retrieve the data in the Azure storage blob.

1. Navigate to your newly created storage account.

2. Select Access control (IAM).

3. Select Add > Add role assignment to open the Add role assignment page.

4. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	Storage Blob Data Reader
   Assign access to	Managed identity
   System-assigned	Virtual Machine
   Select	<your virtual machine>

   

Access data 

Azure Storage natively supports Microsoft Entra authentication, so it can directly accept access tokens obtained using a managed identity. This approach uses Azure Storage's integration with Microsoft Entra ID, and is different from supplying credentials on the connection string.

Here's a .NET code example of opening a connection to Azure Storage. The example uses an access token and then reads the contents of the file you created earlier. This code must run on the VM to be able to access the VM's managed identity endpoint. .NET Framework 4.6 or higher is required to use the access token method. Replace the value of <URI to blob file> accordingly. You can obtain this value by navigating to file you created and uploaded to blob storage and copying the URL under Properties the Overview page.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.IO;
using System.Net;
using System.Web.Script.Serialization;
using Microsoft.WindowsAzure.Storage.Auth;
using Microsoft.WindowsAzure.Storage.Blob;

namespace StorageOAuthToken
{
    class Program
    {
        static void Main(string[] args)
        {
            //get token
            string accessToken = GetMSIToken("https://storage.azure.com/");

            //create token credential
            TokenCredential tokenCredential = new TokenCredential(accessToken);

            //create storage credentials
            StorageCredentials storageCredentials = new StorageCredentials(tokenCredential);

            Uri blobAddress = new Uri("<URI to blob file>");

            //create block blob using storage credentials
            CloudBlockBlob blob = new CloudBlockBlob(blobAddress, storageCredentials);

            //retrieve blob contents
            Console.WriteLine(blob.DownloadText());
            Console.ReadLine();
        }

        static string GetMSIToken(string resourceID)
        {
            string accessToken = string.Empty;
            // Build request to acquire MSI token
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=" + resourceID);
            request.Headers["Metadata"] = "true";
            request.Method = "GET";

            try
            {
                // Call /token endpoint
                HttpWebResponse response = (HttpWebResponse)request.GetResponse();

                // Pipe response Stream to a StreamReader, and extract access token
                StreamReader streamResponse = new StreamReader(response.GetResponseStream());
                string stringResponse = streamResponse.ReadToEnd();
                JavaScriptSerializer j = new JavaScriptSerializer();
                Dictionary<string, string> list = (Dictionary<string, string>)j.Deserialize(stringResponse, typeof(Dictionary<string, string>));
                accessToken = list["access_token"];
                return accessToken;
            }
            catch (Exception e)
            {
                string errorText = String.Format("{0} \n\n{1}", e.Message, e.InnerException != null ? e.InnerException.Message : "Acquire token failed");
                return accessToken;
            }
        }
    }
}

The response contains the contents of the file:

Hello world! :)

Disable

To disable the system-assigned identity on your VM, set the status of the system-assigned identity to Off.

Use a Windows VM system-assigned managed identity to access Azure Storage via a SAS credential

This tutorial shows you how to use a system-assigned identity for a Windows virtual machine (VM) to obtain a storage Shared Access Signature (SAS) credential.

A service SAS provides the ability to grant limited access to objects in a storage account for limited time and for a specific service (in this case, a blob service). SAS does this without exposing an account access key. You can use a SAS credential as usual for storage operations; for example, when using a storage SDK. This tutorial demonstrates uploading and downloading a blob using Azure Storage PowerShell.

You'll learn how to:

Create a storage account

If you don't already have one, you need to create a storage account. Otherwise, follow these steps to grant your VM's system-assigned managed identity access to the SAS credential of an existing storage account.

1. Select Storage, then Storage Account.

2. In the Create storage account panel, enter a name for the storage account.

3. Be sure that Deployment model and Account kind are set to Resource Manager and General purpose.

4. Check to ensure that the Subscription and Resource Group match the items you specified when you created your VM in the previous step.

5. Select Create to create your storage account.

   

Create a blob container in the storage account

Later in the tutorial, you'll upload and download a file to the new storage account. Because files require blob storage, you need to create a blob container to store the file in.

1. Navigate to your newly created storage account.

2. Select the Containers link in the left panel, under Blob service.

3. Select + Container at the top of the page, then a New container panel should appear.

4. Give the container a name, determine the access level, then Select OK. The name you specify here is used later in the tutorial.

   

Grant your VM's system-assigned managed identity access to use a storage SAS

Azure Storage doesn't natively support Microsoft Entra authentication. However, you can use a managed identity to retrieve a storage SAS from Resource Manager, then use the SAS to access storage. In this step, you grant your VM's system-assigned managed identity access to your storage account SAS.

1. Navigate back to your newly created storage account.

2. Select Access control (IAM).

3. Select Add > Add role assignment to open the Add role assignment page.

4. Assign the following role. For detailed steps, see Assign Azure roles using the Azure portal.

   Setting	Value
   Role	Storage account contributor
   Assign access to	Managed identity
   System-assigned	Virtual machine
   Select	<your Windows virtual machine>

   

Get an access token using the VM's identity and use it to call Azure Resource Manager 

For the remainder of this tutorial, you work from your VM. You need to use the Azure Resource Manager PowerShell cmdlets in this portion. If you don’t have PowerShell installed, download the latest version before continuing.

1. In the Azure portal, navigate to Virtual Machines, go to your Windows virtual machine, then from the Overview page Select Connect at the top.

2. Enter your Username and Password that you added when you created your Windows VM.

3. Establish a Remote Desktop Connection with the virtual machine.

4. Open PowerShell in the remote session, then use the PowerShell Invoke-WebRequest cmdlet to get an Azure Resource Manager token from the local managed identity for Azure resources endpoint.

      $response = Invoke-WebRequest -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%2F' -Method GET -Headers @{Metadata="true"}
   

   Note

   The value of the resource parameter must be an exact match for what is expected by Microsoft Entra ID. When using the Azure Resource Manager resource ID, you must include the trailing slash on the URI.

   Next, extract the content element, which is stored as a JavaScript Object Notation (JSON) formatted string in the $response object.

   $content = $response.Content | ConvertFrom-Json
   

   Next, extract the access token from the response.

   $ArmToken = $content.access_token
   

Get a SAS credential from Azure Resource Manager to make storage calls

Lastly, use PowerShell to call Resource Manager using the access token that you retrieved in the previous section. You use this token to create a storage SAS credential. Once you have the SAS credential, you can call other storage operations.

For this request, use the following HTTP request parameters to create the SAS credential:

{
    "canonicalizedResource":"/blob/<STORAGE ACCOUNT NAME>/<CONTAINER NAME>",
    "signedResource":"c",              // The kind of resource accessible with the SAS, in this case a container (c).
    "signedPermission":"rcw",          // Permissions for this SAS, in this case (r)ead, (c)reate, and (w)rite. Order is important.
    "signedProtocol":"https",          // Require the SAS be used on https protocol.
    "signedExpiry":"<EXPIRATION TIME>" // UTC expiration time for SAS in ISO 8601 format, for example 2017-09-22T00:06:00Z.
}

The parameters here are included in the POST body of the request for the SAS credential. For more information on parameters for creating a SAS credential, see the List Service SAS REST reference.

1. Convert the parameters to JSON, then call the storage listServiceSas endpoint to create the SAS credential:

   $params = @{canonicalizedResource="/blob/<STORAGE-ACCOUNT-NAME>/<CONTAINER-NAME>";signedResource="c";signedPermission="rcw";signedProtocol="https";signedExpiry="2017-09-23T00:00:00Z"}
   $jsonParams = $params | ConvertTo-Json
   

   $sasResponse = Invoke-WebRequest -Uri https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RESOURCE-GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE-ACCOUNT-NAME>/listServiceSas/?api-version=2017-06-01 -Method POST -Body $jsonParams -Headers @{Authorization="Bearer $ArmToken"}
   

   Note

   The URL is case-sensitive, so ensure that you use the exact same case used when you named the resource group, including the uppercase "G" in resourceGroups.

2. Next, extract the SAS credential from the response:

   $sasContent = $sasResponse.Content | ConvertFrom-Json
   $sasCred = $sasContent.serviceSasToken
   

3. If you inspect the SAS credential, you should see something like this:

   PS C:\> $sasCred
   sv=2015-04-05&sr=c&spr=https&se=2017-09-23T00%3A00%3A00Z&sp=rcw&sig=JVhIWG48nmxqhTIuN0uiFBppdzhwHdehdYan1W%2F4O0E%3D
   

4. Create a file called test.txt. Then use the SAS credential to authenticate with the New-AzStorageContent cmdlet, upload the file to the blob container, then download the file.

   echo "This is a test text file." > test.txt
   

5. Be sure to install the Azure Storage cmdlets first, using Install-Module Azure.Storage. Then upload the blob you just created, using the PowerShell Set-AzStorageBlobContent cmdlet:

   $ctx = New-AzStorageContext -StorageAccountName <STORAGE-ACCOUNT-NAME> -SasToken $sasCred
   Set-AzStorageBlobContent -File test.txt -Container <CONTAINER-NAME> -Blob testblob -Context $ctx
   

   Response:

   ICloudBlob        : Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob
   BlobType          : BlockBlob
   Length            : 56
   ContentType       : application/octet-stream
   LastModified      : 9/21/2017 6:14:25 PM +00:00
   SnapshotTime      :
   ContinuationToken :
   Context           : Microsoft.WindowsAzure.Commands.Storage.AzureStorageContext
   Name              : testblob
   

6. You can also download the blob you uploaded, using the Get-AzStorageBlobContent PowerShell cmdlet:

   Get-AzStorageBlobContent -Blob testblob -Container <CONTAINER-NAME> -Destination test2.txt -Context $ctx
   

   Response:

   ICloudBlob        : Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob
   BlobType          : BlockBlob
   Length            : 56
   ContentType       : application/octet-stream
   LastModified      : 9/21/2017 6:14:25 PM +00:00
   SnapshotTime      :
   ContinuationToken :
   Context           : Microsoft.WindowsAzure.Commands.Storage.AzureStorageContext
   Name              : testblob
   

Use a Windows VM system-assigned managed identity to access Azure SQL Database

This tutorial shows you how to use a system-assigned identity for a Windows virtual machine (VM) to access Azure SQL Database. Managed Service Identities are automatically managed by Azure and enable you to authenticate to services that support Microsoft Entra authentication, without needing to insert credentials into your code.

You'll learn how to:

Enable

Enabling a system-assigned managed identity is a one-click experience. You can either enable it during the creation of a VM or in the properties of an existing VM.

To enable a system-assigned managed identity on a new VM:

1. Sign in to the Azure portal.

2. Create a virtual machine with system-assigned identity enabled.

Grant access

To grant your VM access to a database in Azure SQL Database, use an existing logical SQL server or create a new one. To create a new server and database using the Azure portal, follow the Azure SQL quickstart. There are also quickstarts that use the Azure CLI and Azure PowerShell in the Azure SQL documentation.

Follow these steps to grant your VM access to a database:

1. Enable Microsoft Entra authentication for the server.
2. Create a contained user in the database that represents the VM's system-assigned identity.

Enable Microsoft Entra authentication

To configure Microsoft Entra authentication:

1. In the Azure portal, select SQL server from the left-hand navigation.
2. Select the SQL server you want to enable for Microsoft Entra authentication.
3. In the Settings section of the blade, select Active Directory admin.
4. In the command bar, select Set admin.
5. Select a Microsoft Entra user account to be made an administrator for the server, and select Select.
6. In the command bar, select Save.

Create contained user

This section shows you how to create a contained user in the database that represents the VM's system assigned identity. For this step, you need Microsoft SQL Server Management Studio (SSMS) installed. Before starting, it may be helpful to review the following articles for background on Microsoft Entra integration:

• Universal Authentication with SQL Database and Azure Synapse Analytics (SSMS support for MFA)
• Configure and manage Microsoft Entra authentication with SQL Database or Azure Synapse Analytics

SQL databases require unique Microsoft Entra ID display names. With this, Microsoft Entra accounts, such as users, groups and service principals (applications), and VM names enabled for managed identity must be uniquely defined in Microsoft Entra ID specific to their corresponding display names. SQL checks the Microsoft Entra ID display names during T-SQL creation of such users. If the display names aren't unique, the command fails and prompts you to provide a unique Microsoft Entra ID display name for each given account.

To create a contained user

1. Open SQL Server Management Studio.

2. In the Connect to Server dialog, enter your server name in the Server name field.

3. In the Authentication field, select Active Directory - Universal with MFA support.

4. In the User name field, enter the name of the Microsoft Entra account that you set as the server administrator; for example, cjensen@fabrikam.com.

5. Select Options.

6. In the Connect to database field, enter the name of the non-system database you want to configure.

7. Select Connect, then complete the sign-in process.

8. In the Object Explorer, expand the Databases folder.

9. Right-click on a user database, then select New query.

10. In the query window, enter the following line, and select Execute in the toolbar:

    Note

    VMName in the following command is the name of the VM that you enabled system assigned identity on in the prerequsites section.

    CREATE USER [VMName] FROM EXTERNAL PROVIDER
    

    The command should complete successfully by creating the contained user for the VM's system-assigned identity.

11. Clear the query window, enter the following line, and select Execute in the toolbar:

    Note

    VMName in the following command is the name of the VM that you enabled system assigned identity on in the prerequisites section.

    If you encounter the error "Principal VMName has a duplicate display name", append the CREATE USER statement with WITH OBJECT_ID='xxx'.

    ALTER ROLE db_datareader ADD MEMBER [VMName]
    

    The command should complete successfully by granting the contained user the ability to read the entire database.

Code running in the VM can now get a token using its system-assigned managed identity and use the token to authenticate to the server.

Access data

This section shows you how to get an access token using the VM's system-assigned managed identity and use it to call Azure SQL. Azure SQL natively supports Microsoft Entra authentication, so it can directly accept access tokens obtained using managed identities for Azure resources. This method doesn't require supplying credentials on the connection string.

Here's a .NET code example of opening a connection to SQL using Active Directory Managed Identity authentication. The code must run on the VM to be able to access the VM's system-assigned managed identity's endpoint.

.NET Framework 4.6.2 or higher or .NET Core 3.1 or higher is required to use this method. Replace the values of AZURE-SQL-SERVERNAME and DATABASE accordingly and add a NuGet reference to the Microsoft.Data.SqlClient library.

using Microsoft.Data.SqlClient;

try
{
//
// Open a connection to the server using Active Directory Managed Identity authentication.
//
string connectionString = "Data Source=<AZURE-SQL-SERVERNAME>; Initial Catalog=<DATABASE>; Authentication=Active Directory Managed Identity; Encrypt=True";
SqlConnection conn = new SqlConnection(connectionString);
conn.Open();

Or, use PowerShell to test the end-to-end setup without having to write and deploy an app on the VM.

1. In the portal, navigate to Virtual Machines, go to your Windows VM, then in the Overview, select Connect.

2. Enter your VM admin credential that you added when you created the Windows VM.

3. Now that you have created a Remote Desktop Connection with the VM, open PowerShell in a remote session.

4. Using the PowerShell Invoke-WebRequest cmdlet, make a request to the local managed identity's endpoint to get an access token for Azure SQL.

       $response = Invoke-WebRequest -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fdatabase.chinacloudapi.cn%2F' -Method GET -Headers @{Metadata="true"}
   

   Convert the response from a JSON object to a PowerShell object.

   $content = $response.Content | ConvertFrom-Json
   

   Extract the access token from the response.

   $AccessToken = $content.access_token
   

5. Open a connection to the server. Remember to replace the values for AZURE-SQL-SERVERNAME and DATABASE.

   $SqlConnection = New-Object System.Data.SqlClient.SqlConnection
   $SqlConnection.ConnectionString = "Data Source = <AZURE-SQL-SERVERNAME>; Initial Catalog = <DATABASE>; Encrypt=True;"
   $SqlConnection.AccessToken = $AccessToken
   $SqlConnection.Open()
   

   Next, create and send a query to the server. Remember to replace the value for TABLE.

   $SqlCmd = New-Object System.Data.SqlClient.SqlCommand
   $SqlCmd.CommandText = "SELECT * from <TABLE>;"
   $SqlCmd.Connection = $SqlConnection
   $SqlAdapter = New-Object System.Data.SqlClient.SqlDataAdapter
   $SqlAdapter.SelectCommand = $SqlCmd
   $DataSet = New-Object System.Data.DataSet
   $SqlAdapter.Fill($DataSet)
   

Finally, examine the value of $DataSet.Tables[0] to view the results of the query.

Disable

To disable the system-assigned identity on your VM, set the status of the system-assigned identity to Off.

Use a Windows VM system-assigned managed identity to access Azure Key Vault

This tutorial shows you how a Windows virtual machine (VM) can use a system-assigned managed identity to access Azure Key Vault. Key Vault makes it possible for your client application to use a secret to access resources not secured by Microsoft Entra ID. Managed identities are automatically managed by Azure. They enable you to authenticate to services that support Microsoft Entra authentication, without including authentication information in your code.

You'll learn how to:

Create a Key Vault  

This section shows how to grant your VM access to a secret stored in a Key Vault. When you use managed identities for Azure resources, your code can get access tokens to authenticate to resources that support Microsoft Entra authentication.

However, not all Azure services support Microsoft Entra authentication. To use managed identities for Azure resources with those services, store the service credentials in Azure Key Vault, and use the VM's managed identity to access Key Vault to retrieve the credentials.

First, you need to create a Key Vault and grant your VM’s system-assigned managed identity access to the Key Vault.

1. Sign in to the Azure portal.

2. At the top of the left navigation bar, select Create a resource.

3. In the Search the Marketplace box type in Key Vault and press Enter.

4. Select Key Vault from the results, then select Create.

5. Provide a Name for the new key vault.

   

6. Fill out all required information. Make sure that you choose the subscription and resource group that you're using for this tutorial.

7. Select Review+ create.

8. Select Create.

Create a secret

Next, you need to add a secret to the Key Vault, so you can retrieve it later using code running in your VM. In this section you use PowerShell, but the same concepts apply to any code that you execute in your VM.

1. Navigate to your newly created Key Vault.

2. Select Secrets, then select Add.

3. Select Generate/Import.

4. From the Create a secret screen, in the Upload options leave Manual selected.

5. Enter a name and value for the secret. The value can be anything you want. 

6. Leave the activation date and expiration date clear, and leave Enabled as Yes. 

7. Select Create to create the secret.

   

Grant access

The managed identity used by the VM needs to be granted access to read the secret that the Key Vault stores.

1. Navigate to your newly created Key Vault.

2. Select Access Policy from the menu on the left side.

3. Select Add Access Policy.

   

4. In the Add access policy section, under Configure from template (optional), choose Secret Management from the drop-down menu.

5. Choose Select Principal, then in the search field enter the name of the VM you created earlier. 

6. Select the VM in the result list, then choose Select.

7. Select Add.

8. Select Save.

Access data

This section shows you how to get an access token using the VM identity and use it to retrieve the secret from Key Vault. If you don’t have PowerShell 4.3.1 or greater installed, you'll need to download and install the latest version.

First, use the VM’s system-assigned managed identity to get an access token to authenticate to Key Vault:  

1. In the portal, navigate to Virtual Machines and go to your Windows VM, then in the Overview, select Connect.
2. Enter in your Username and Password that you added when you created the Windows VM.
3. Now that you've created a Remote Desktop Connection with the VM, open PowerShell in a remote session.
4. In PowerShell, invoke the web request on the tenant to get the token for the local host in the specific port for the VM.

Example PowerShell request:

$Response = Invoke-RestMethod -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fvault.azure.cn' -Method GET -Headers @{Metadata="true"} 

For example, vault.usgovcloudapi.net should be used when working with Azure Government Cloud, with this being the end result:

$Response = Invoke-RestMethod -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fvault.usgovcloudapi.net' -Method GET -Headers @{Metadata="true"

To confirm that the suffix matches your environment, review the article Azure Key vault security overview.

The response should look like:

Next, extract the access token from the response.

   $KeyVaultToken = $Response.access_token

Finally, use the PowerShell Invoke-WebRequest cmdlet to retrieve the secret you created earlier in the Key Vault, passing the access token in the Authorization header. You’ll need the URL of your Key Vault, which is in the Essentials section of the Overview page of the Key Vault.

Invoke-RestMethod -Uri https://<your-key-vault-URL>/secrets/<secret-name>?api-version=2016-10-01 -Method GET -Headers @{Authorization="Bearer $KeyVaultToken"}

The response should look like this: 

  value       id                                                                                    attributes
  -----       --                                                                                    ----------
  'My Secret' https://mi-lab-vault.vault.azure.cn/secrets/mi-test/50644e90b13249b584c44b9f712f2e51 @{enabled=True; created=16…

Once you’ve retrieved the secret from the Key Vault, you can use it to authenticate to a service that requires a name and password.

Clean up resources

Finally, when you want to clean up resources, sign in to the Azure portal, select Resource groups, then locate and select the resource group that was created in the process of this tutorial (such as mi-test). Then use the Delete resource group command.

Or, you can also clean up resources using PowerShell or the CLI.

Use a Windows VM system-assigned managed identity to access resource manager

This tutorial explains how to create a system-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'll learn how to:

1. Sign in to the Azure portal with your administrator account.

2. Navigate to the Resource Groups tab.

3. Select the Resource Group that you want to grant the VM's managed identity access.

4. In the left panel, select Access control (IAM).

5. Select Add, then select Add role assignment.

6. In the Role tab, select Reader. This role allows view all resources, but doesn't allow you to make any changes.

7. In the Members tab, for the Assign access to option, select Managed identity, then select + Select members.

8. Ensure the proper subscription is listed in the Subscription dropdown. For Resource Group, select All resource groups.

9. For the Manage identity dropdown, select Virtual Machine.

10. For Select, choose your VM in the dropdown, then select Save.

    

Get an access token

Use the VM's system-assigned managed identity and call the Resource Manager to get an access token.

To complete these steps, you need an SSH client. If you're using Windows, you can use the SSH client in the Windows Subsystem for Linux. If you need assistance configuring your SSH client's keys, see How to Use SSH keys with Windows on Azure, or How to create and use an SSH public and private key pair for Linux VMs in Azure.

1. In the portal, navigate to your Linux VM and in the Overview, select Connect.
2. Connect to the VM with the SSH client of your choice.
3. In the terminal window, using curl, make a request to the local managed identities for Azure resources endpoint to get an access token for Azure Resource Manager.   The curl request for the access token is below.

curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.chinacloudapi.cn/' -H Metadata:true

The response includes the access token you need to access Azure Resource Manager.

Response:

{
  "access_token":"eyJ0eXAiOi...",
  "refresh_token":"",
  "expires_in":"3599",
  "expires_on":"1504130527",
  "not_before":"1504126627",
  "resource":"https://management.chinacloudapi.cn",
  "token_type":"Bearer"
}

Use this access token to access Azure Resource Manager; for example, to read the details of the resource group to which you previously granted this VM access. Replace the values of <SUBSCRIPTION-ID>, <RESOURCE-GROUP>, and <ACCESS-TOKEN> with the ones you created earlier.

curl https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RESOURCE-GROUP>?api-version=2016-09-01 -H "Authorization: Bearer <ACCESS-TOKEN>" 

The response back with the specific resource group information:  

{
"id":"/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/DevTest",
"name":"DevTest",
"location":"chinanorth",
"properties":
{
  "provisioningState":"Succeeded"
  }
} 

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

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'll learn how to:

Configure Azure PowerShell locally

To use Azure PowerShell locally for this article, complete the following steps:

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

2. Sign in to Azure:

   Connect-AzAccount -Environment AzureChinaCloud
   

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 released version of the Az.ManagedServiceIdentity module. You need this to perform the user-assigned managed identity operations in this tutorial:

   Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
   

Enable

For scenarios based on a user-assigned identity, you need to perform the following steps in this section:

1. Create an identity.
2. Assign the newly created identity.

Create identity

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

New-AzUserAssignedIdentity -ResourceGroupName myResourceGroupVM -Name ID1

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

{
Id: /subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ID1
ResourceGroupName : myResourceGroupVM
Name: ID1
Location: chinanorth
TenantId: aaaabbbb-0000-cccc-1111-dddd2222eeee
PrincipalId: aaaaaaaa-bbbb-cccc-1111-222222222222
ClientId: 00001111-aaaa-2222-bbbb-3333cccc4444
ClientSecretUrl: https://control-chinanorth.identity.chinacloudapi.cn/subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM/providers/Microsoft.ManagedIdentity/userAssignedIdentities/ID1/credentials?tid=aaaabbbb-0000-cccc-1111-dddd2222eeee&oid=aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb&aid=00001111-aaaa-2222-bbbb-3333cccc4444
Type: Microsoft.ManagedIdentity/userAssignedIdentities
}

Assign identity

This section shows you 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 you 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, you access the resource group for 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/00000000-0000-0000-0000-000000000000
Scope: /subscriptions/<SUBSCRIPTIONID>/resourcegroups/myResourceGroupVM
DisplayName: ID1
SignInName:
RoleDefinitionName: Reader
RoleDefinitionId: 00000000-0000-0000-0000-000000000000
ObjectId: aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType: ServicePrincipal
CanDelegate: False

Access data

Get an access token

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

1. Sign in to the Azure portal.

2. In the portal, navigate to Virtual Machines and go to the Windows VM. In the Overview, select Connect.

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

4. Now that you have created a Remote Desktop Connection with your VM, open PowerShell in a remote session.

5. Using the PowerShell Invoke-WebRequest cmdlet, 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=00001111-aaaa-2222-bbbb-3333cccc4444&resource=https://management.chinacloudapi.cn/' -Method GET -Headers @{Metadata="true"}
   $content = $response.Content | ConvertFrom-Json
   $ArmToken = $content.access_token
   

Read properties

Finally, use the access token retrieved in the previous step to access Azure Resource Manager, then 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.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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":"ChinaNorth","properties":{"provisioningState":"Succeeded"}}