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

  • Article

Managed identities for Azure resources is a feature of Microsoft Entra ID. Each of the Azure services that support managed identities for Azure resources are subject to their own timeline. Make sure you review the availability status of managed identities for your resource and known issues before you begin.

Prerequisites

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

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

You'll learn how to:

  • Create a storage account
  • Create a blob container in a storage account
  • Grant the Linux VM's Managed Identity access to an Azure Storage container
  • Get an access token and use it to call Azure Storage

Create a storage account

First, create a storage account.

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

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

  3. Under Name, 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.

    Screenshot showing the new storage account creation screen.

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. Select Blob Service, then Containers.

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

  4. Select New container, then enter a name for the container.

  5. Make sure that Public access level is the default value.

    Screenshot showing the storage container creation screen.

  6. 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!, and then save it.

  7. Select the container name, then Upload. This uploads the file to the newly created container.

  8. 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.

  9. Select the file, then select Upload.

    Screenshot showing the upload text file section.

Grant your VM access to an Azure Storage container

You can use the VM's managed identity to retrieve the data in the Azure storage blob. Managed identities for Azure resources, can be used to authenticate to resources that support Microsoft Entra authentication. Grant access by assigning the storage-blob-data-reader role to the managed-identity at the scope of the resource group that contains your storage account.

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

Note

For more information on the various roles that you can use to grant permissions to storage review Authorize access to blobs and queues using Microsoft Entra ID

Get an access token and use it to call Azure Storage

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

To complete the following steps, you need to work from the VM created earlier and you need an SSH client to connect to it.

If you are 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 Azure portal, navigate to Virtual Machines, go to your Linux virtual machine, then from the Overview page select Connect. Copy the string to connect to your VM.

  2. Connect to the VM with the SSH client of your choice.

  3. In the terminal window, use CURL to make a request to the local Managed Identity endpoint to get an access token for Azure Storage.

    curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fstorage.azure.com%2F' -H Metadata:true

  4. Use the access token to access Azure Storage. For example, to read the contents of the sample file that you previously uploaded to the container, replace the values of <STORAGE ACCOUNT>, <CONTAINER NAME>, and <FILE NAME> with the values you specified earlier, and <ACCESS TOKEN> with the token returned in the previous step.

    curl https://<STORAGE ACCOUNT>.blob.core.chinacloudapi.cn/<CONTAINER NAME>/<FILE NAME> -H "x-ms-version: 2017-11-09" -H "Authorization: Bearer <ACCESS TOKEN>"

    The response contains the contents of the file:

    Hello world! :)

Lastly, you can also store the token in a variable and pass it to the second command as shown:

# Run the first curl command and capture its output in a variable
access_token=$(curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fstorage.azure.com%2F' -H Metadata:true | jq -r '.access_token')

# Run the second curl command with the access token
curl "https://<STORAGE ACCOUNT>.blob.core.chinacloudapi.cn/<CONTAINER NAME>/<FILE NAME>" \
  -H "x-ms-version: 2017-11-09" \
  -H "Authorization: Bearer $access_token"

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

This tutorial shows you how to use a system-assigned managed identity for a Linux virtual machine (VM) to obtain a storage Shared Access Signature (SAS) credential; specifically, a Service SAS credential.

Note

The SAS key generated in this tutorial will not be restricted/bound to the VM.

A Service SAS grants limited access to objects in a storage account without exposing an account access key. Access can be granted for a limited time and a specific service. You can use a SAS credential as usual when doing storage operations; for example, when using the Storage SDK. In this tutorial, you'll upload and download a blob using Azure Storage CLI.

You'll learn how to:

  • Create a storage account
  • Create a blob container in the storage account
  • Grant your VM access to a storage account SAS in Resource Manager
  • Get an access token using your VM's identity, and use it to retrieve the SAS from Resource Manager

Create a storage account

If you don't already have one, you'll need to create a storage account. You can choose to skip this step and grant your VM system-assigned managed identity access to the keys of an existing storage account.

  1. Select the +/Create new service button, located at the upper-left corner of the Azure portal.

  2. Select Storage, then Storage Account, then the Create storage account panel appears.

  3. Enter a Name for the storage account. Remember this name, as you'll need it later.

  4. Make sure that Deployment model is set to Resource Manager, and Account kind is set to General purpose.

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

  6. Select Create to finish creating a storage account.

    Screenshot showing the new storage account creation screen.

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 in which to store the file.

  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 appears.

  4. Give the container a name, select an access level, then select OK. You'll need the name you specified later in the tutorial.

    Screenshot showing storage container creation screen.

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

Azure Storage natively supports Microsoft Entra authentication, so you can use your VM's system-assigned managed identity to retrieve a storage SAS from Resource Manager. Then you can use the SAS to access storage.

In this section, you grant your VM's system-assigned managed identity access to your storage account SAS. Assign the Storage Account Contributor role to the managed-identity at the scope of the resource group that contains your storage account.

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

Note

For more information on the various roles that you can use to grant permissions to storage review Authorize access to blobs and queues using Microsoft Entra ID.

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 the VM that you created earlier.

You need an SSH client to complete these steps. 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:

Once you have your SSH client, follow these steps:

  1. In the Azure portal, navigate to Virtual Machines, then go to your Linux virtual machine.
  2. From the Overview page, select Connect at the top of the screen.
  3. Copy the string to connect to your VM.
  4. Connect to your VM using your SSH client.
  5. Enter your Password that you added when creating the Linux VM. You should then be successfully signed in.
  6. Use CURL to get an access token for Azure Resource Manager.

The CURL request and response for the access token is below:

curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%2F' -H Metadata:true

Note

In the previous request, 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.

In the following response, the access_token element has been shortened for brevity.

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

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

Next, use CURL to call Resource Manager using the access token we retrieved in the previous section. Use this to create a storage SAS credential. Once you have the SAS credential, you can call storage upload/download 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.
}

Include these parameters in the body of the POST request for the SAS credential. For more information on the parameters for creating a SAS credential, see the List Service SAS REST reference.

Use the following CURL request to get the SAS credential. Be sure to replace the <SUBSCRIPTION ID>, <RESOURCE GROUP>, <STORAGE ACCOUNT NAME>, <CONTAINER NAME>, and <EXPIRATION TIME> parameter values with your own values. Replace the <ACCESS TOKEN> value with the access token you retrieved earlier:

curl https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE ACCOUNT NAME>/listServiceSas/?api-version=2017-06-01 -X POST -d "{\"canonicalizedResource\":\"/blob/<STORAGE ACCOUNT NAME>/<CONTAINER NAME>\",\"signedResource\":\"c\",\"signedPermission\":\"rcw\",\"signedProtocol\":\"https\",\"signedExpiry\":\"<EXPIRATION TIME>\"}" -H "Authorization: Bearer <ACCESS TOKEN>"

Note

The text in the prior URL is case sensitive, so ensure if you are using upper-lowercase for your resource groups to reflect it accordingly. Also, it’s important to know this is a POST request, not a GET request.

The CURL response returns the SAS credential:

{"serviceSasToken":"sv=2015-04-05&sr=c&spr=https&st=2017-09-22T00%3A10%3A00Z&se=2017-09-22T02%3A00%3A00Z&sp=rcw&sig=QcVwljccgWcNMbe9roAJbD8J5oEkYoq%2F0cUPlgriBn0%3D"}

On a Linux VM, create a sample blob file to upload to your blob storage container using the following command:

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

Next, authenticate with the CLI az storage command using the SAS credential, and then upload the file to the blob container. For this step, you'll need to install the latest Azure CLI on your VM, if you haven't already.

 az storage blob upload --container-name 
                        --file 
                        --name
                        --account-name 
                        --sas-token

Response:

Finished[#############################################################]  100.0000%
{
  "etag": "\"0x8D4F9929765C139\"",
  "lastModified": "2017-09-21T03:58:56+00:00"
}

You can also download the file using the Azure CLI and authenticating with the SAS credential.

Request:

az storage blob download --container-name
                         --file 
                         --name 
                         --account-name
                         --sas-token

Response:

{
  "content": null,
  "metadata": {},
  "name": "testblob",
  "properties": {
    "appendBlobCommittedBlockCount": null,
    "blobType": "BlockBlob",
    "contentLength": 16,
    "contentRange": "bytes 0-15/16",
    "contentSettings": {
      "cacheControl": null,
      "contentDisposition": null,
      "contentEncoding": null,
      "contentLanguage": null,
      "contentMd5": "Aryr///Rb+D8JQ8IytleDA==",
      "contentType": "text/plain"
    },
    "copy": {
      "completionTime": null,
      "id": null,
      "progress": null,
      "source": null,
      "status": null,
      "statusDescription": null
    },
    "etag": "\"0x8D4F9929765C139\"",
    "lastModified": "2017-09-21T03:58:56+00:00",
    "lease": {
      "duration": null,
      "state": "available",
      "status": "unlocked"
    },
    "pageBlobSequenceNumber": null,
    "serverEncrypted": false
  },
  "snapshot": null
}

Use a Linux VM system-assigned managed identity to access Azure Storage via access key

This tutorial shows you how to use a system-assigned managed identity for a Linux virtual machine (VM) to retrieve storage account access keys. You can use a storage access key as usual when doing storage operations; for example, when using the Storage SDK. For this tutorial, you upload and download blobs using Azure CLI.

You'll learn how to:

  • Grant your VM access to storage account access keys in Resource Manager
  • Get an access token using your VM's identity, and use it to retrieve the storage access keys from Resource Manager

Create a storage account

If you don't have an existing storage account before starting this tutorial, you need to create one. If you do have an existing storage account, follow these steps to grant your VM system-assigned managed identity access to the keys for your existing storage account.

  1. Select the +/Create new service button, located at the upper-left corner of the Azure portal.

  2. Select Storage, then Storage Account, then the Create storage account panel appears.

  3. Enter a Name for the storage account. Remember this name, as you'll need it later.

  4. Make sure that Deployment model is set to Resource Manager, and Account kind is set to General purpose.

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

  6. Select Create to finish creating a storage account.

    Screenshot showing new storage account creation.

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 in which to store the file.

  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 appears.

  4. Give the container a name, select an access level, then select OK. You'll need the name you specified later in the tutorial.

    Screenshot showing the creation of a storage container.

Grant your VM's system-assigned managed identity access to use storage account access keys

Azure Storage doesn't natively support Microsoft Entra authentication. However, you can use your VM's system-assigned 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. Grant access by assigning the Storage Account Contributor role to the managed-identity at the scope of the resource group that contains your storage account.

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

Note

For more information on the various roles that you can use to grant permissions to storage review Authorize access to blobs and queues using Microsoft Entra ID.

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

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

To complete these steps, you need an SSH client. If you are 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 Azure portal, navigate to Virtual Machines, select your Linux virtual machine, then from the Overview page select Connect at the top. Copy the string to connect to your VM.

  2. Connect to your VM using your SSH client.

  3. Next, you need to enter the Password you added when creating the Linux VM.

  4. Use CURL to get an access token for Azure Resource Manager.

    The CURL request and response for the access token is below:

    curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn%2F' -H Metadata:true

    Note

    In the previous request, 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. In the following response, the access_token element as been shortened for brevity.

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

Get storage account access keys from Azure Resource Manager to make storage calls

Now use CURL to call Resource Manager using the access token we retrieved in the previous section, to retrieve the storage access key. Once we have the storage access key, we can call storage upload/download operations. Be sure to replace the <SUBSCRIPTION ID>, <RESOURCE GROUP>, and <STORAGE ACCOUNT NAME> parameter values with your own values. Replace the <ACCESS TOKEN> value with the access token you retrieved earlier:

curl https://management.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE ACCOUNT NAME>/listKeys?api-version=2016-12-01 --request POST -d "" -H "Authorization: Bearer <ACCESS TOKEN>"

Note

The text in the prior URL is case sensitive, so ensure if you are using upper-lowercase for your Resource Groups to reflect it accordingly. Additionally, it’s important to know that this is a POST request not a GET request and ensure you pass a value to capture a length limit with -d that can be NULL.

The CURL response gives you the list of Keys:

{"keys":[{"keyName":"key1","permissions":"Full","value":"iqDPNt..."},{"keyName":"key2","permissions":"Full","value":"U+uI0B..."}]}

Create a sample blob file to upload to your blob storage container. On a Linux VM, you can do this with the following command.

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

Next, authenticate with the CLI az storage command using the storage access key, and upload the file to the blob container. For this step, you need to install the latest Azure CLI on your VM, if you haven't already.

az storage blob upload -c <CONTAINER NAME> -n test.txt -f test.txt --account-name <STORAGE ACCOUNT NAME> --account-key <STORAGE ACCOUNT KEY>

Response:

Finished[#############################################################]  100.0000%
{
  "etag": "\"0x8D4F9929765C139\"",
  "lastModified": "2017-09-12T03:58:56+00:00"
}

Additionally, you can download the file using the Azure CLI and authenticating with the storage access key.

Request:

az storage blob download -c <CONTAINER NAME> -n test.txt -f test-download.txt --account-name <STORAGE ACCOUNT NAME> --account-key <STORAGE ACCOUNT KEY>

Response:

{
  "content": null,
  "metadata": {},
  "name": "test.txt",
  "properties": {
    "appendBlobCommittedBlockCount": null,
    "blobType": "BlockBlob",
    "contentLength": 21,
    "contentRange": "bytes 0-20/21",
    "contentSettings": {
      "cacheControl": null,
      "contentDisposition": null,
      "contentEncoding": null,
      "contentLanguage": null,
      "contentMd5": "LSghAvpnElYyfUdn7CO8aw==",
      "contentType": "text/plain"
    },
    "copy": {
      "completionTime": null,
      "id": null,
      "progress": null,
      "source": null,
      "status": null,
      "statusDescription": null
    },
    "etag": "\"0x8D5067F30D0C283\"",
    "lastModified": "2017-09-28T14:42:49+00:00",
    "lease": {
      "duration": null,
      "state": "available",
      "status": "unlocked"
    },
    "pageBlobSequenceNumber": null,
    "serverEncrypted": false
  },
  "snapshot": null
}

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

This tutorial shows you how a Linux 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 then use a secret to access resources not secured by Microsoft Entra ID. Managed Service Identities are automatically managed by Azure and enable you to authenticate to services that support Microsoft Entra authentication, without including authentication information in your code.

You'll learn how to:

  • Grant your VM access to a secret stored in a Key Vault
  • Get an access token using the VM's identity and use it to retrieve the secret from the Key Vault  

Create a Key Vault  

You also need a Linux Virtual machine that has system assigned managed identities enabled.

Tip

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

This section shows how to grant your VM access to a secret stored in a Key Vault. Using 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 hit Enter.

  4. Select Key Vault from the results.

  5. Select Create.

  6. Provide a Name for the new key vault.

    Screenshot showing the Azure Key vault creation screen.

  7. Fill out all required information making sure that you choose the subscription and resource group where you created the virtual machine that you are using for this tutorial.

  8. Select Review+ create, then 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'll use PowerShell. But the same concepts apply to any code executing in this virtual machine.

  1. Navigate to your newly created Key Vault.

  2. Select Secrets, then select Add.

  3. Select Generate/Import.

  4. In the Create a secret section, go to Upload options and make sure that Manual is 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 make sure that Enabled is set to Yes. 

  7. Select Create to create the secret.

    Screenshot showing secret creation.

Grant access

The managed identity used by the virtual machine needs access to read the secret stored in Key Vault.

  1. Navigate to your newly created Key Vault.

  2. Select Access Policy from the left navigation.

  3. Select Add Access Policy.

    Screenshot of the key vault create access policy screen.

  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.  Select the VM in the result list, then Select.

  6. Select Add.

  7. Select Save.

Access data

To complete these steps, you need an SSH client.  If you are 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.

Important

All Azure SDKs support the Azure.Identity library that makes it easy to acquire Microsoft Entra tokens to access target services. Learn more about Azure SDKs and accessing the Azure.Identity library.

  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, use cURL to make a request to the local managed identities for Azure resources endpoint to get an access token for Azure Key Vault.   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%3A%2F%2Fvault.azure.cn' -H Metadata:true
  ```
The response includes the access token you need to access Resource Manager. 
  
Response:
  
```bash
{"access_token":"eyJ0eXAi...",
"refresh_token":"",
"expires_in":"3599",
"expires_on":"1504130527",
"not_before":"1504126627",
"resource":"https://vault.azure.cn",
"token_type":"Bearer"} 

You can use this access token to authenticate to Azure Key Vault.  The next CURL request shows how to read a secret from Key Vault using CURL and the Key Vault REST API.  You need the URL of your Key Vault, which is in the Essentials section of the Overview page of the Key Vault.  You also need the access token you obtained on the previous call. 

curl 'https://<YOUR-KEY-VAULT-URL>/secrets/<secret-name>?api-version=2016-10-01' -H "Authorization: Bearer <ACCESS TOKEN>" 

The response looks like this: 

{"value":"p@ssw0rd!","id":"https://mytestkeyvault.vault.azure.cn/secrets/MyTestSecret/7c2204c6093c4d859bc5b9eff8f29050","attributes":{"enabled":true,"created":1505088747,"updated":1505088747,"recoveryLevel":"Purgeable"}} 

Once you 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

When you're ready to clean up the 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. You can use the Delete resource group command or via PowerShell or CLI.

Use a Linux VM system-assigned managed identity to access a resource group in resource manager

Tip

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

This tutorial explains how to create a system-assigned identity, assign it to a Linux 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:

  • Grant your VM access to Azure resource manager.
  • Get an access token by using the VM's system-assigned managed identity to access resource manager.

  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, in 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. In the Manage identity dropdown, select Virtual Machine.

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

    Screenshot that shows adding the reader role to the managed identity.

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 Azure portal, navigate to your Linux VM.
  2. In the Overview, select Connect.
  3. Connect to the VM with the SSH client of your choice.
  4. 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

Note

The value of the resource parameter must be an exact match for what is expected by Microsoft Entra ID. In the case of the resource manager resource ID, you must include the trailing slash on the URI.

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.

Note

The URL is case-sensitive, so ensure if you are using the exact case as you used earlier when you named the resource group, and the uppercase “G” in resourceGroup.

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 Linux VM user-assigned managed identity to access a resource group in Resource Manager

Tip

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

This tutorial explains how to create a user-assigned identity, assign it to a Linux 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:

  • Grant your VM access to Azure Resource Manager.
  • Get an access token by using the VM's system-assigned managed identity to access Resource Manager.

Create a user-assigned managed identity using az identity create. The -g parameter specifies the resource group where the user-assigned managed identity is created, and the -n parameter specifies its name. Be sure to replace the <RESOURCE GROUP> and <UAMI NAME> parameter values with your own values:

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. 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.

az identity create -g <RESOURCE GROUP> -n <UAMI NAME>

The response contains details for the user-assigned managed identity created, similar to the following example. Note the id value for your user-assigned managed identity, as it will be used in the next step:

{
"clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"clientSecretUrl": "https://control-chinanorth.identity.chinacloudapi.cn/subscriptions/<SUBSCRIPTON ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<UAMI NAME>/credentials?tid=5678&oid=9012&aid=aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
"id": "/subscriptions/<SUBSCRIPTON ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<UAMI NAME>",
"location": "chinanorth",
"name": "<UAMI NAME>",
"principalId": "9012",
"resourceGroup": "<RESOURCE GROUP>",
"tags": {},
"tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Assign an identity to your Linux VM

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

Assign the user-assigned managed identity to your Linux VM using az vm identity assign. Be sure to replace the <RESOURCE GROUP> and <VM NAME> parameter values with your own values. Use the id property returned in the previous step for the --identities parameter value.

az vm identity assign -g <RESOURCE GROUP> -n <VM NAME> --identities "/subscriptions/<SUBSCRIPTION ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<UAMI NAME>"

Grant access to a resource group in Azure Resource Manager

Managed identities are 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 <SUBSCRIPTION ID> and <RESOURCE GROUP> as appropriate for your environment. Additionally, replace <UAMI PRINCIPALID> with the principalId property returned by the az identity create command in Create a user-assigned managed identity:

az role assignment create --assignee <UAMI PRINCIPALID> --role 'Reader' --scope "/subscriptions/<SUBSCRIPTION ID>/resourcegroups/<RESOURCE GROUP> "

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

{
  "id": "/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "properties": {
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "roleDefinitionId": "/subscriptions/<SUBSCRIPTION ID>/providers/Microsoft.Authorization/roleDefinitions/00000000-0000-0000-0000-000000000000",
    "scope": "/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>"
  },
  "resourceGroup": "<RESOURCE GROUP>",
  "type": "Microsoft.Authorization/roleAssignments"
}

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

Tip

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

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

To complete these steps, you need an SSH client. If you are using Windows, you can use the SSH client in the Windows Subsystem for Linux.

  1. Sign in to the Azure portal.

  2. In the portal, navigate to Virtual Machines and go to the Linux virtual machine and in the Overview, click Connect. Copy the string to connect to your VM.

  3. Connect to the VM with the SSH client of your choice. If you are 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.

  4. In the terminal window, use CURL to make a request to the Azure Instance Metadata Service (IMDS) identity endpoint to get an access token for Azure Resource Manager.

    The CURL request to acquire an access token is shown in the following example. Be sure to replace <CLIENT ID> with the clientId property returned by the az identity create command in Create a user-assigned managed identity:

    curl -H Metadata:true "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.chinacloudapi.cn/&client_id=<UAMI CLIENT ID>"

    Note

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

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

    Response example:

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

  5. Use the access token to access Azure Resource Manager, and read the properties of the resource group to which you previously granted your user-assigned managed identity access. Be sure to replace <SUBSCRIPTION ID>, <RESOURCE GROUP> with the values you specified earlier, and <ACCESS TOKEN> with the token returned in the previous step.

    Note

    The URL is case-sensitive, so be sure to use the exact same case you used earlier when you named the resource group, and the uppercase "G" in resourceGroups.

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

    The response contains the specific resource group information, similar to the following example:

    {
"id":"/subscriptions/<SUBSCRIPTION ID>/resourceGroups/DevTest",
"name":"DevTest",
"location":"chinanorth",
"properties":{"provisioningState":"Succeeded"}
}

Learn more