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

Identidades gerenciadas para recursos do Azure é um recurso do Microsoft Entra ID. Cada um dos serviços do Azure que dão suporte a identidades gerenciadas para recursos do Azure está sujeito à própria linha do tempo. Não deixe de examinar o status de disponibilidade das identidades gerenciadas do seu recurso e os problemas conhecidos antes de começar.

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 serviço de metadados na instância do Azure (IMDS) (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

Exemplo de resposta:

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 userAssignedClientId = "<your managed identity client Id>";
   var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });
   var accessToken = credential.GetToken(new TokenRequestContext(new[] { "https://vault.azure.net" }));
   // To print the token, you can convert it to string 
   String accessTokenString = accessToken.Token.ToString();
   
   //You can use the credential object directly with Key Vault client.     
   var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
   

Obtenha um token usando a biblioteca Microsoft.Azure.Services.AppAuthentication para .NET

Para aplicativos e funções .NET, a maneira mais simples de trabalhar com identidades gerenciadas para recursos do Azure é por meio do pacote Microsoft.Azure.Services.AppAuthentication. Essa biblioteca também permitirá que você teste seu código localmente em seu computador de desenvolvimento. Você pode testar o código usando sua conta de usuário do Visual Studio, a CLI do Azure ou a Autenticação Integrada do Active Directory. Para obter mais informações sobre as opções de desenvolvimento local com essa biblioteca, consulte a Referência Microsoft.Azure.Services.AppAuthentication. Esta seção mostra a você como começar a usar a biblioteca no seu código.

1. Adicione uma referência aos pacotes NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault no aplicativo.

2. Adicione o código a seguir à sua página:

   using Microsoft.Azure.Services.AppAuthentication;
   using Microsoft.Azure.KeyVault;
   // ...
   var azureServiceTokenProvider = new AzureServiceTokenProvider();
   string accessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://management.azure.com/");
   // OR
   var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));
   

Para saber mais sobre o Microsoft.Azure.Services.AppAuthentication e as operações que ele expõe, consulte a Referência do Microsoft.Azure.Services.AppAuthentication e o Serviço de Aplicativo e KeyVault com identidades gerenciadas para exemplo .NET de recursos do Azure .

Obter um token usando C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Web.Script.Serialization; 

// Build request to acquire managed identities for Azure resources token
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/");
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>));
    string accessToken = list["access_token"];
}
catch (Exception e)
{
    string errorText = String.Format("{0} \n\n{1}", e.Message, e.InnerException != null ? e.InnerException.Message : "Acquire token failed");
}

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-WebRequest -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
$response = Invoke-WebRequest -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"}
$content =$response.Content | ConvertFrom-Json
$access_token = $content.access_token
echo "The managed identities for Azure resources access token is $access_token"

# Use the access token to get resource information for the VM
$vmInfoRest = (Invoke-WebRequest -Uri 'https://management.azure.com/subscriptions/<SUBSCRIPTION-ID>/resourceGroups/<RESOURCE-GROUP>/providers/Microsoft.Compute/virtualMachines/<VM-NAME>?api-version=2017-12-01' -Method GET -ContentType "application/json" -Headers @{ Authorization ="Bearer $access_token"}).content
echo "JSON returned from call to get VM info:"
echo $vmInfoRest

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 The managed identities for Azure resources access token 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

É recomendável tentar novamente se você receber o código de erro 404, 429 ou 5xx (confira Tratamento de erros acima). 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.