Como usar identidades gerenciadas para recursos do Azure em uma VM do Azure para adquirir um token de acesso

As identidades gerenciadas dos recursos do Azure fornecem aos serviços do Azure uma identidade gerenciada automaticamente na ID do Microsoft Entra. Use essa identidade para autenticar qualquer serviço que dê suporte à autenticação do Microsoft Entra, sem a necessidade de ter as credenciais no código.

Este artigo fornece vários exemplos de código e script para aquisição de tokens. Ele também contém diretrizes sobre como lidar com a expiração de tokens e erros HTTP.

Pré-requisitos

• Se você não estiver familiarizado com as identidades gerenciadas para funcionalidades de recursos do Azure, veja esta visão geral. Caso você ainda não tenha uma conta do Azure, inscreva-se em uma conta gratuita antes de continuar.

Se você planeja usar os exemplos do Azure PowerShell neste artigo, instale a versão mais recente do Azure PowerShell.

Visão geral

Um aplicativo cliente pode solicitar um token de acesso somente de aplicativo de identidade gerenciada para acessar um determinado recurso. O token é com base nas identidades gerenciadas para a entidade de serviço dos recursos do Azure. Sendo assim, o cliente não precisa obter um token de acesso em sua própria entidade de serviço. O token é adequado para uso como um token de portador em chamadas de serviço a serviço que exigem credenciais de cliente.

Obter um token usando HTTP

A interface fundamental para adquirir um token de acesso é baseada em REST, tornando-a acessível para qualquer aplicativo cliente em execução na VM que pode fazer chamadas REST HTTP. A abordagem é semelhante ao modelo de programação do Microsoft Entra, exceto que o cliente usa um ponto de extremidade na máquina virtual (em vez de um ponto de extremidade do Microsoft Entra).

Exemplo de solicitação usando o ponto de extremidade do IMDS (Serviço de Metadados de Instância) do Azure (recomendado):

GET 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/' HTTP/1.1 Metadata: true

Resposta de exemplo:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJ0eXAi...",
  "refresh_token": "",
  "expires_in": "3599",
  "expires_on": "1506484173",
  "not_before": "1506480273",
  "resource": "https://management.azure.com/",
  "token_type": "Bearer"
}

Obter um token usando a biblioteca de clientes de identidade do Azure

Usar a biblioteca de clientes de identidade do Azure é a maneira recomendada de usar identidades gerenciadas. Todos os SDKs do Azure são integrados à biblioteca Azure.Identity que fornece suporte para DefaultAzureCredential. Essa classe facilita o uso de Identidades Gerenciadas com SDKs do Azure.Saiba mais

1. Instale o pacote Azure.Identity e outros pacotes necessários da biblioteca do SDK do Azure, como o Azure.Security.KeyVault.Secrets.

2. Use o código de exemplo abaixo. Você não precisa se preocupar em obter os tokens. Você pode usar diretamente os clientes do SDK do Azure. O código serve para demonstrar como obter o token, se necessário.

   using Azure.Core;
   using Azure.Identity;
   
   string managedIdentityClientId = "<your managed identity client Id>";
   var credential = new ManagedIdentityCredential(managedIdentityClientId);
   var accessToken = await credential.GetTokenAsync(new TokenRequestContext(["https://vault.azure.net"]));
   // To print the token, you can convert it to string 
   var accessTokenString = accessToken.Token;
   
   // You can use the credential object directly with Key Vault client.     
   var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
   

Obter um token usando C#

using System;
using System.Net.Http;
using Newtonsoft.Json.Linq;

// Construct HttpClient
var httpClient = new HttpClient
{
    DefaultRequestHeaders =
    {
        { "Metadata", Boolean.TrueString }
    }
};

// Construct URI to call
var resource = "https://management.azure.com/";
var uri = $"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource={resource}";

// Make call
var response = await httpClient.GetAsync(uri);
try
{
    response.EnsureSuccessStatusCode();
}
catch (HttpRequestException)
{
    var error = await response.Content.ReadAsStringAsync();
    Console.WriteLine(error);
    throw;
}

// Parse response using Newtonsoft.Json
var content = await response.Content.ReadAsStringAsync();
var obj = JObject.Parse(content);
var accessToken = obj["access_token"];

Console.WriteLine(accessToken);

Obter um token usando o Java

Use esta biblioteca JSON para recuperar um token usando o Java.

import java.io.*;
import java.net.*;
import com.fasterxml.jackson.core.*;
 
class GetMSIToken {
    public static void main(String[] args) throws Exception {
 
        URL msiEndpoint = new URL("http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/");
        HttpURLConnection con = (HttpURLConnection) msiEndpoint.openConnection();
        con.setRequestMethod("GET");
        con.setRequestProperty("Metadata", "true");
 
        if (con.getResponseCode()!=200) {
            throw new Exception("Error calling managed identity token endpoint.");
        }
 
        InputStream responseStream = con.getInputStream();
 
        JsonFactory factory = new JsonFactory();
        JsonParser parser = factory.createParser(responseStream);
 
        while(!parser.isClosed()){
            JsonToken jsonToken = parser.nextToken();
 
            if(JsonToken.FIELD_NAME.equals(jsonToken)){
                String fieldName = parser.getCurrentName();
                jsonToken = parser.nextToken();
 
                if("access_token".equals(fieldName)){
                    String accesstoken = parser.getValueAsString();
                    System.out.println("Access Token: " + accesstoken.substring(0,5)+ "..." + accesstoken.substring(accesstoken.length()-5));
                    return;
                }
            }
        }
    }
}

Obter um token usando Go

package main

import (
  "fmt"
  "io/ioutil"
  "net/http"
  "net/url"
  "encoding/json"
)

type responseJson struct {
  AccessToken string `json:"access_token"`
  RefreshToken string `json:"refresh_token"`
  ExpiresIn string `json:"expires_in"`
  ExpiresOn string `json:"expires_on"`
  NotBefore string `json:"not_before"`
  Resource string `json:"resource"`
  TokenType string `json:"token_type"`
}

func main() {
    
    // Create HTTP request for a managed services for Azure resources token to access Azure Resource Manager
    var msi_endpoint *url.___URL
    msi_endpoint, err := url.Parse("http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01")
    if err != nil {
      fmt.Println("Error creating URL: ", err)
      return 
    }
    msi_parameters := msi_endpoint.Query()
    msi_parameters.Add("resource", "https://management.azure.com/")
    msi_endpoint.RawQuery = msi_parameters.Encode()
    req, err := http.NewRequest("GET", msi_endpoint.String(), nil)
    if err != nil {
      fmt.Println("Error creating HTTP request: ", err)
      return 
    }
    req.Header.Add("Metadata", "true")

    // Call managed services for Azure resources token endpoint
    client := &http.Client{}
    resp, err := client.Do(req) 
    if err != nil{
      fmt.Println("Error calling token endpoint: ", err)
      return
    }

    // Pull out response body
    responseBytes,err := ioutil.ReadAll(resp.Body)
    defer resp.Body.Close()
    if err != nil {
      fmt.Println("Error reading response body : ", err)
      return
    }

    // Unmarshall response body into struct
    var r responseJson
    err = json.Unmarshal(responseBytes, &r)
    if err != nil {
      fmt.Println("Error unmarshalling the response:", err)
      return
    }

    // Print HTTP response and marshalled response body elements to console
    fmt.Println("Response status:", resp.Status)
    fmt.Println("access_token: ", r.AccessToken)
    fmt.Println("refresh_token: ", r.RefreshToken)
    fmt.Println("expires_in: ", r.ExpiresIn)
    fmt.Println("expires_on: ", r.ExpiresOn)
    fmt.Println("not_before: ", r.NotBefore)
    fmt.Println("resource: ", r.Resource)
    fmt.Println("token_type: ", r.TokenType)
}

Obter um token usando PowerShell

O exemplo a seguir demonstra como usar as identidades gerenciadas do ponto de extremidade de REST de recursos do Azure de um cliente do PowerShell para:

1. Adquirir um token de acesso.
2. Use o token de acesso para chamar uma API REST do Azure Resource Manager e obter informações sobre a VM. Substitua sua ID de assinatura, o nome do grupo de recursos e o nome da máquina virtual para <SUBSCRIPTION-ID>, <RESOURCE-GROUP> e <VM-NAME>, respectivamente.

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

Exemplo sobre como analisar o token de acesso da resposta:

# Get an access token for managed identities for Azure resources
$resource = 'https://management.azure.com'
$response = Invoke-RestMeth -Method GET `
                            -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource' `
                            -Headers @{ Metadata="true" }
$content = $response.Content | ConvertFrom-Json
$accessToken = $content.access_token
Write-Host "Access token using a User-Assigned Managed Identity is $accessToken"

# Use the access token to get resource information for the VM
$secureToken = $accessToken | ConvertTo-SecureString -AsPlainText
$vmInfoRest = Invoke-RestMeth -Method GET `
                              -Uri 'https://management.azure.com/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RESOURCE-GROUP>/providers/Microsoft.Compute/virtualMachines/<VM-NAME>?api-version=2017-12-01' `
                              -ContentType 'application/json' `
                              -Authentication Bearer `
                              -Token $secureToken
Write-Host "JSON returned from call to get VM info: $($vmInfoRest.content)"

Obter um token usando CURL

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

Exemplo sobre como analisar o token de acesso da resposta:

response=$(curl 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.azure.com%2F' -H Metadata:true -s)
access_token=$(echo $response | python -c 'import sys, json; print (json.load(sys.stdin)["access_token"])')
echo Access token using a User-Assigned Managed Identity is $access_token

Armazenamento de token em cache

O subsistema de identidades gerenciadas armazena em cache tokens, mas ainda recomendamos que você implemente o cache de token em seu código. Você deve se preparar para cenários em que o recurso indica que o token expirou.

As chamadas on-the-wire para o Microsoft Entra ID resultam somente quando:

• A perda no cache ocorre porque não há tokens nas identidades gerenciadas do cache do subsistema de recursos do Azure.
• O token está expirado.

Tratamento de erros

O ponto de extremidade de identidades gerenciadas sinaliza os erros por meio do campo de código de status do cabeçalho da mensagem de resposta HTTP, como erros 4xx ou 5xx:

Se ocorrer um erro, o corpo da resposta HTTP correspondente conterá o JSON com os detalhes do erro:

Referência de resposta HTTP

Esta seção documenta as possíveis respostas de erro. Um status "200 OK" é uma resposta bem-sucedida, e o token de acesso está contido no JSON do corpo de resposta, no elemento access_token.

Repita a orientação

Tente novamente se receber um código de erro 404, 429 ou 5xx (consulte Tratamento de erro). Se você receber um erro 410, ele indicará que o IMDS está passando por atualizações e estará disponível em no máximo 70 segundos.

Limitação limites se aplicam ao número de chamadas feitas para o ponto de extremidade IMDS. Quando o limite de limitação é excedido, o ponto de extremidade IMDS limita qualquer solicitação adicional enquanto a limitação está em vigor. Durante esse período, o ponto de extremidade de IMDS da MSI retornará o código de status HTTP 429 ("Muitas solicitações") e as solicitações falharão.

Para tentar novamente, é recomendável a estratégia a seguir:

IDs de recurso para serviços do Azure

Para obter uma lista de serviços do Azure que dão suporte a identidades gerenciadas, veja Serviços do Azure com suporte a identidades gerenciadas.

Próximas etapas

• Para habilitar identidades gerenciadas para recursos do Azure em uma VM do Azure, consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure l.