Come usare le identità gestite per risorse di Azure in una macchina virtuale di Azure per acquisire un token di accesso

Le identità gestite per le risorse di Azure sono una funzionalità di Microsoft Entra ID. Tutti i servizi di Azure che supportano le identità gestite per le risorse di Azure sono soggetti alla sequenza temporale di tali entità. Prima di iniziare, assicurarsi di esaminare lo stato di disponibilità delle identità gestite per la risorsa e i problemi noti.

Le identità gestite per le risorse di Azure offrono servizi di Azure con un'identità gestita automaticamente in Microsoft Entra ID. È possibile usare questa identità per l'autenticazione in qualsiasi servizio che supporta l'autenticazione di Microsoft Entra senza dover immettere le credenziali nel codice.

Questo articolo fornisce vari esempi di codice e script per l'acquisizione di token. Contiene anche indicazioni sulla gestione della scadenza dei token e degli errori HTTP.

Prerequisiti

• Se non si ha familiarità con la funzionalità delle identità gestite per le risorse di Azure, vedere questa panoramica. Se non si ha un account Azure, registrarsi per ottenere un account gratuito prima di continuare.

Se si prevede di usare gli esempi di Azure PowerShell presenti in questo articolo, assicurarsi di installare la versione più recente di Azure PowerShell.

Panoramica

Un'applicazione client può richiedere un token di accesso solo app per l'identità gestita per accedere a una determinata risorsa. Il token è basato sulle identità gestite per l'entità servizio delle risorse di Azure. Di conseguenza, non è necessario che il client ottenga un token di accesso con la propria entità servizio. Il token è adatto per l'uso come token di connessione nelle chiamate da servizio a servizio che richiedono le credenziali client.

Ottenere un token tramite HTTP

L'interfaccia di base per l'acquisizione di un token di accesso si basa su REST. È pertanto accessibile a qualsiasi applicazione client in esecuzione nella macchina virtuale in grado di effettuare chiamate REST HTTP. Questo approccio è simile al modello di programmazione Microsoft Entra, ad eccezione del client che usa un endpoint nella macchina virtuale (rispetto a un endpoint Microsoft Entra).

Richiesta di esempio che usa l'endpoint del servizio metadati dell'istanza (IMDS) (consigliato):

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

Risposta di esempio:

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"
}

Ottenere un token usando la libreria client di identità di Azure

L'uso della libreria client di identità di Azure è il modo consigliato per usare le identità gestite. Tutti gli SDK di Azure sono integrati con la Azure.Identity libreria che fornisce supporto per DefaultAzureCredential. Questa classe semplifica l'uso di identità gestite con Gli SDK di Azure.Ulteriori informazioni

1. Installare il pacchetto Azure.Identity e altri pacchetti di libreria di Azure SDK necessari, ad esempio Azure.Security.KeyVault.Secrets.

2. Usare il codice di esempio seguente. Non è necessario preoccuparsi di ottenere i token. È possibile usare direttamente i client Azure SDK. Il codice è per illustrare come ottenere il token, se necessario.

   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);
   

Ottenere un token usando la libreria Microsoft.Azure.Services.AppAuthentication per .NET

Per le funzioni e le applicazioni .NET, il modo più semplice per usare le identità gestite per risorse di Azure è tramite il pacchetto Microsoft.Azure.Services.AppAuthentication. Questa libreria consentirà anche di testare il codice in locale nel computer di sviluppo. È possibile testare il codice usando l'account utente di Visual Studio, l'interfaccia della riga di comando di Azure o l'autenticazione integrata di Active Directory. Per altre informazioni sulle opzioni di sviluppo locale con questa libreria, vedere la documentazione di riferimento della libreria Microsoft.Azure.Services.AppAuthentication. In questa sezione viene illustrato come muovere i primi passi con la libreria nel codice.

1. Aggiungere un riferimento ai pacchetti NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault all'applicazione.

2. Aggiungere il codice seguente all'applicazione:

   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));
   

Per altre informazioni su Microsoft.Azure.Services.AppAuthentication e sulle relative operazioni esposte, vedere la documentazione di riferimento su Microsoft.Azure.Services.AppAuthentication e l'esempio .NET del Servizio app di Azure e dell'insieme di credenziali delle chiavi con le identità gestite per risorse di Azure.

Ottenere un token tramite 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");
}

Ottenere un token tramite Java

Usare questa libreria JSON per recuperare un token usando 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;
                }
            }
        }
    }
}

Ottenere un token tramite 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)
}

Ottenere un token con PowerShell

L'esempio seguente illustra come usare l'endpoint REST delle identità gestite per risorse di Azure da un client PowerShell per:

1. Acquisire un token di accesso.
2. Usare il token di accesso per chiamare un'API REST di Azure Resource Manager e ottenere informazioni sulla macchina virtuale. Assicurarsi di sostituire l'ID di sottoscrizione, il nome del gruppo di risorse e il nome della macchina virtuale, rispettivamente, per <SUBSCRIPTION-ID>, <RESOURCE-GROUP>, e <VM-NAME>.

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"}

Esempio di come analizzare il token di accesso dalla risposta:

# 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

Ottenere un token tramite 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

Esempio di come analizzare il token di accesso dalla risposta:

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

Memorizzazione del token nella cache

Il sottosistema delle identità gestite memorizza nella cache i token, ma è comunque consigliabile implementare la memorizzazione nella cache dei token nel codice. È necessario prepararsi per gli scenari in cui la risorsa indica che il token è scaduto.

Le chiamate in transito a Microsoft Entra ID vengono restituite solo quando:

• Si verifica il mancato riscontro nella cache a causa dell'assenza di token nella cache del sottosistema delle identità gestite per le risorse di Azure.
• Il token memorizzato nella cache è scaduto.

Gestione degli errori

L'endpoint delle identità gestite segnala errori tramite il campo del codice di stato dell'intestazione del messaggio di risposta HTTP, come errori 4xx o 5xx:

Se si verifica un errore, il corpo della risposta HTTP corrispondente contiene dati JSON con i dettagli dell'errore:

Riferimenti per la risposta HTTP

Questa sezione illustra le possibili risposte di errore. Uno stato di tipo "200 OK" costituisce una risposta con esito positivo e il token di accesso è contenuto nei dati JSON del corpo della risposta, nell'elemento access_token.

Indicazioni per nuovi tentativi

È consigliabile riprovare se si riceve un codice di errore 404, 429 o 5xx (vedere Gestione degli errori precedente). Se viene visualizzato un errore 410, indica che IMDS sta attraversando gli aggiornamenti e sarà disponibile in un massimo di 70 secondi.

I limiti di limitazione si applicano al numero di chiamate effettuate all'endpoint IMDS. Al superamento della soglia di limitazione delle richieste, l'endpoint IMDS limiterà eventuali altre richieste mentre la limitazione è attiva. Durante questo periodo, l'endpoint IMDS restituisce il codice di stato HTTP 429 ("Troppe richieste") e le richieste hanno esito negativo.

Per eseguire nuovi tentativi è consigliabile seguire la strategia seguente:

ID di risorsa per servizi di Azure

Vedere Servizi di Azure con supporto delle identità gestite per un elenco di risorse che supportano le identità gestite per le risorse di Azure.

Passaggi successivi

• Per abilitare le identità gestite per le risorse di Azure in una macchina virtuale di Azure, vedere Configurare le identità gestite per le risorse di Azure in una macchina virtuale tramite il portale di Azure.