Como usar identidades gerenciadas para recursos do Azure em uma VM do Azure para adquirir um token de acessoHow to use managed identities for Azure resources on an Azure VM to acquire an access token

Identidades gerenciadas para recursos do Azure é um recurso do Azure Active Directory.Managed identities for Azure resources is a feature of Azure Active Directory. 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.Each of the Azure services that support managed identities for Azure resources are subject to their own timeline. Não deixe de examinar o status de disponibilidade das identidades gerenciadas do seu recurso e os problemas conhecidos antes de começar.Make sure you review the availability status of managed identities for your resource and known issues before you begin.

As identidades gerenciadas dos recursos do Azure fornecem aos serviços do Azure uma identidade gerenciada automaticamente no Azure Active Directory.Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. Você pode usar essa identidade para autenticar em qualquer serviço que dá suporte à autenticação do Azure AD, incluindo o Key Vault, sem ter as credenciais no seu código.You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code.

Este artigo fornece vários exemplos de código e de script para aquisição de token, assim como diretrizes sobre tópicos importantes como a manipulação de expiração de token e erros HTTP.This article provides various code and script examples for token acquisition, as well as guidance on important topics such as handling token expiration and HTTP errors.

Pré-requisitosPrerequisites

  • Se você não estiver familiarizado com as identidades gerenciadas para funcionalidades de recursos do Azure, veja esta visão geral.If you're not familiar with the managed identities for Azure resources feature, see this overview. Caso você ainda não tenha uma conta do Azure, inscreva-se em uma conta gratuita antes de continuar.If you don't have an Azure account, sign up for a free account before you continue.

Se você planeja usar os exemplos do Azure PowerShell neste artigo, instale a versão mais recente do Azure PowerShell.If you plan to use the Azure PowerShell examples in this article, be sure to install the latest version of Azure PowerShell.

Importante

  • Todos os scripts/exemplos de código neste artigo assumem que o cliente está executando em uma máquina virtual com identidades gerenciadas para recursos do Azure.All sample code/script in this article assumes the client is running on a virtual machine with managed identities for Azure resources. Use o recurso "Conectar" da máquina virtual no portal do Azure para conectar remotamente a VM.Use the virtual machine "Connect" feature in the Azure portal, to remotely connect to your VM. Para obter detalhes sobre como habilitar identidades gerenciadas para recursos do Azure em uma VM, consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure ou um dos artigos variantes (usando PowerShell, CLI, um modelo ou um SDK do Azure).For details on enabling managed identities for Azure resources on a VM, see Configure managed identities for Azure resources on a VM using the Azure portal, or one of the variant articles (using PowerShell, CLI, a template, or an Azure SDK).

Importante

  • O limite de segurança de identidades gerenciadas para recursos do Azure é o recurso em que está sendo usado.The security boundary of managed identities for Azure resources, is the resource it's being used on. Todos os códigos/scripts em execução em uma máquina virtual podem solicitar e recuperar tokens para quaisquer identidades gerenciadas disponíveis neles.All code/scripts running on a virtual machine can request and retrieve tokens for any managed identities available on it.

Visão geralOverview

Um aplicativo cliente pode solicitar identidades gerenciadas para o token de acesso somente de aplicativo dos recursos do Azure para acessar um determinado recurso.A client application can request managed identities for Azure resources app-only access token for accessing a given resource. O token é com base nas identidades gerenciadas para a entidade de serviço dos recursos do Azure.The token is based on the managed identities for Azure resources service principal. Sendo assim, o cliente não precisa se registrar para obter um token de acesso em sua própria entidade de serviço.As such, there is no need for the client to register itself to obtain an access token under its own service principal. O token é adequado para uso como um token de portador em chamadas de serviço a serviço que exigem credenciais de cliente.The token is suitable for use as a bearer token in service-to-service calls requiring client credentials.

Obter um token usando HTTPGet a token using HTTP Detalhes do protocolo para identidades gerenciadas do ponto de extremidade do token de recursos do AzureProtocol details for managed identities for Azure resources token endpoint
Obtenha um token usando a biblioteca Microsoft.Azure.Services.AppAuthentication para .NETGet a token using the Microsoft.Azure.Services.AppAuthentication library for .NET Exemplo de como usar a biblioteca Microsoft.Azure.Services.AppAuthentication de um cliente .NETExample of using the Microsoft.Azure.Services.AppAuthentication library from a .NET client
Obter um token usando C#Get a token using C# Exemplo de uso de identidades gerenciadas para o ponto de extremidade de REST de recursos do Azure de um cliente C#Example of using managed identities for Azure resources REST endpoint from a C# client
Obter um token usando o JavaGet a token using Java Exemplo de uso de identidades gerenciadas para o ponto de extremidade de REST de recursos do Azure de um cliente JavaExample of using managed identities for Azure resources REST endpoint from a Java client
Obter um token usando GoGet a token using Go Exemplo de uso de identidades gerenciadas para o ponto de extremidade de REST de recursos do Azure de um cliente GoExample of using managed identities for Azure resources REST endpoint from a Go client
Obter um token usando o Azure PowerShellGet a token using Azure PowerShell Exemplo de uso de identidades gerenciadas para o ponto de extremidade de REST de recursos do Azure de um cliente PowerShellExample of using managed identities for Azure resources REST endpoint from a PowerShell client
Obter um token usando CURLGet a token using CURL Exemplo de uso de identidades gerenciadas para o ponto de extremidade de REST de recursos do Azure de um cliente Bash/CURLExample of using managed identities for Azure resources REST endpoint from a Bash/CURL client
Tratamento de cache de tokenHandling token caching Diretrizes para manipular tokens de acesso expiradosGuidance for handling expired access tokens
Tratamento de errosError handling Diretrizes para tratar erros HTTP retornados das identidades gerenciadas do ponto de extremidade de token de recursos do AzureGuidance for handling HTTP errors returned from the managed identities for Azure resources token endpoint
IDs de recurso para serviços do AzureResource IDs for Azure services Onde obter IDs de recurso para os serviços do Azure compatíveisWhere to get resource IDs for supported Azure services

Obter um token usando HTTPGet a token using 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.The fundamental interface for acquiring an access token is based on REST, making it accessible to any client application running on the VM that can make HTTP REST calls. Isso é semelhante ao modelo de programação do Azure AD, exceto que o cliente usa um ponto de extremidade na máquina virtual (em vez de um ponto de extremidade do Azure AD).This is similar to the Azure AD programming model, except the client uses an endpoint on the virtual machine (vs an Azure AD endpoint).

Exemplo de solicitação usando o ponto de extremidade do serviço de metadados na instância do Azure (IMDS) (recomendado) :Sample request using the Azure Instance Metadata Service (IMDS) endpoint (recommended):

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
ElementoElement DESCRIÇÃODescription
GET O verbo HTTP, indicando que você deseja recuperar os dados do ponto de extremidade.The HTTP verb, indicating you want to retrieve data from the endpoint. Neste caso, um token de acesso OAuth.In this case, an OAuth access token.
http://169.254.169.254/metadata/identity/oauth2/token As identidades gerenciadas do ponto de extremidade de recursos do Azure para o Serviço de Metadados de Instância.The managed identities for Azure resources endpoint for the Instance Metadata Service.
api-version Um parâmetro de cadeia de caracteres, que indica a versão de API para o ponto de extremidade IMDS.A query string parameter, indicating the API version for the IMDS endpoint. Use a versão de API 2018-02-01 ou superior.Please use API version 2018-02-01 or greater.
resource Um parâmetro de cadeia de caracteres de consulta que indica o URI da ID do aplicativo do recurso de destino.A query string parameter, indicating the App ID URI of the target resource. Ele também aparece na declaração aud (público) do token emitido.It also appears in the aud (audience) claim of the issued token. Este exemplo solicita um token para acessar o Azure Resource Manager, que tem um URI de ID do aplicativo de https://management.azure.com/.This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata Um campo de cabeçalho de solicitação HTTP, exigido por identidades gerenciadas para recursos do Azure como uma atenuação contra ataque SSRF (Server Side Request Forgery).An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. Esse valor deve ser definido como "true", com todas as letras minúsculas.This value must be set to "true", in all lower case.
object_id (Opcional) Um parâmetro de string de consulta, indicando o object_id da identidade gerenciada para a qual você deseja o token.(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. Obrigatório, se a VM tiver várias identidades gerenciadas atribuídas ao usuário.Required, if your VM has multiple user-assigned managed identities.
client_id (Opcional) Um parâmetro de cadeia de consulta, indicando o client_id da identidade gerenciada para a qual você deseja o token.(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. Obrigatório, se a VM tiver várias identidades gerenciadas atribuídas ao usuário.Required, if your VM has multiple user-assigned managed identities.
mi_res_id (Opcional) Um cadeia de caracteres parâmetro de consulta, que indica o mi_res_id (ID do recurso do Azure) de identidade gerenciada que você gostaria que o token para.(Optional) A query string parameter, indicating the mi_res_id (Azure Resource ID) of the managed identity you would like the token for. Obrigatório, se a VM tiver várias identidades gerenciadas atribuídas ao usuário.Required, if your VM has multiple user-assigned managed identities.

Solicitação de exemplo usando as identidades gerenciadas do Ponto de Extremidade de Extensão de VM dos recursos do Azure (previsão de reprovação em janeiro de 2019) :Sample request using the managed identities for Azure resources VM Extension Endpoint (planned for deprecation in January 2019):

GET http://localhost:50342/oauth2/token?resource=https%3A%2F%2Fmanagement.azure.com%2F HTTP/1.1
Metadata: true
ElementoElement DESCRIÇÃODescription
GET O verbo HTTP, indicando que você deseja recuperar os dados do ponto de extremidade.The HTTP verb, indicating you want to retrieve data from the endpoint. Neste caso, um token de acesso OAuth.In this case, an OAuth access token.
http://localhost:50342/oauth2/token As identidades gerenciadas do ponto de extremidade de recursos do Azure, em que 50342 é a porta padrão e é configurável.The managed identities for Azure resources endpoint, where 50342 is the default port and is configurable.
resource Um parâmetro de cadeia de caracteres de consulta que indica o URI da ID do aplicativo do recurso de destino.A query string parameter, indicating the App ID URI of the target resource. Ele também aparece na declaração aud (público) do token emitido.It also appears in the aud (audience) claim of the issued token. Este exemplo solicita um token para acessar o Azure Resource Manager, que tem um URI de ID do aplicativo de https://management.azure.com/.This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata Um campo de cabeçalho de solicitação HTTP, exigido por identidades gerenciadas para recursos do Azure como uma atenuação contra ataque SSRF (Server Side Request Forgery).An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. Esse valor deve ser definido como "true", com todas as letras minúsculas.This value must be set to "true", in all lower case.
object_id (Opcional) Um parâmetro de string de consulta, indicando o object_id da identidade gerenciada para a qual você deseja o token.(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. Obrigatório, se a VM tiver várias identidades gerenciadas atribuídas ao usuário.Required, if your VM has multiple user-assigned managed identities.
client_id (Opcional) Um parâmetro de cadeia de consulta, indicando o client_id da identidade gerenciada para a qual você deseja o token.(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. Obrigatório, se a VM tiver várias identidades gerenciadas atribuídas ao usuário.Required, if your VM has multiple user-assigned managed identities.

Exemplo de resposta:Sample response:

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"
}
ElementoElement DESCRIÇÃODescription
access_token O token de acesso solicitado.The requested access token. Ao chamar uma API REST protegida, o token é inserido no campo de cabeçalho de solicitação Authorization como um token "portador", permitindo que a API autentique o chamador.When calling a secured REST API, the token is embedded in the Authorization request header field as a "bearer" token, allowing the API to authenticate the caller.
refresh_token Não usado por identidades gerenciadas para recursos do Azure.Not used by managed identities for Azure resources.
expires_in O número de segundos que o token de acesso continua sendo válido antes da expiração desde o momento da emissão.The number of seconds the access token continues to be valid, before expiring, from time of issuance. A hora da emissão pode ser encontrada na declaração iat do token.Time of issuance can be found in the token's iat claim.
expires_on O período de expiração do token de acesso.The timespan when the access token expires. A data é representada como o número de segundos de “1970-01-01T0:0:0Z UTC” (corresponde à declaração exp do token).The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's exp claim).
not_before O período para o token de acesso entrar em vigor e poder ser aceito.The timespan when the access token takes effect, and can be accepted. A data é representada como o número de segundos de “1970-01-01T0:0:0Z UTC” (corresponde à declaração nbf do token).The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's nbf claim).
resource O recurso para o qual o token de acesso foi solicitado, que corresponde ao parâmetro de cadeia de consulta resource da solicitação.The resource the access token was requested for, which matches the resource query string parameter of the request.
token_type O tipo de token, que é um token de acesso "Portador", o que significa que o recurso pode conceder acesso ao portador desse token.The type of token, which is a "Bearer" access token, which means the resource can give access to the bearer of this token.

Obtenha um token usando a biblioteca Microsoft.Azure.Services.AppAuthentication para .NETGet a token using the Microsoft.Azure.Services.AppAuthentication library for .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.For .NET applications and functions, the simplest way to work with managed identities for Azure resources is through the Microsoft.Azure.Services.AppAuthentication package. Essa biblioteca também permitirá que você teste seu código localmente em sua máquina de desenvolvimento, usando sua conta de usuário do Visual Studio, a Azure CLI ou a Autenticação Integrada do Active Directory.This library will also allow you to test your code locally on your development machine, using your user account from Visual Studio, the Azure CLI, or Active Directory Integrated Authentication. Para obter mais informações sobre as opções de desenvolvimento local com essa biblioteca, consulte a Referência Microsoft.Azure.Services.AppAuthentication.For more on local development options with this library, see the Microsoft.Azure.Services.AppAuthentication reference. Esta seção mostra a você como começar a usar a biblioteca no seu código.This section shows you how to get started with the library in your code.

  1. Adicione uma referência aos pacotes NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault no aplicativo.Add references to the Microsoft.Azure.Services.AppAuthentication and Microsoft.Azure.KeyVault NuGet packages to your application.

  2. Adicione o código a seguir à sua página:Add the following code to your application:

    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 .To learn more about Microsoft.Azure.Services.AppAuthentication and the operations it exposes, see the Microsoft.Azure.Services.AppAuthentication reference and the App Service and KeyVault with managed identities for Azure resources .NET sample.

Obter um token usando C#Get a token using 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 JavaGet a token using Java

Use esta biblioteca JSON para recuperar um token usando o Java.Use this JSON library to retrieve a token using 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 GoGet a token using 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 := url.Values{}
    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 o Azure PowerShellGet a token using Azure 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:The following example demonstrates how to use the managed identities for Azure resources REST endpoint from a PowerShell client to:

  1. Adquirir um token de acesso.Acquire an access token.
  2. Use o token de acesso para chamar uma API REST do Azure Resource Manager e obter informações sobre a VM.Use the access token to call an Azure Resource Manager REST API and get information about the 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.Be sure to substitute your subscription ID, resource group name, and virtual machine name for <SUBSCRIPTION-ID>, <RESOURCE-GROUP>, and <VM-NAME>, respectively.
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:Example on how to parse the access token from the response:

# 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 CURLGet a token using 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:Example on how to parse the access token from the response:

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 cacheToken caching

Embora as identidades gerenciadas do subsistema de recursos do Azure que está sendo usado (IMDS/identidades gerenciadas para Extensão de VM dos recursos do Azure) tenham tokens de cache, também é recomendável implementar o cache de token no código.While the managed identities for Azure resources subsystem being used (IMDS/managed identities for Azure resources VM Extension) does cache tokens, we also recommend to implement token caching in your code. Como resultado, você deve se preparar para cenários em que o recurso indica que o token expirou.As a result, you should prepare for scenarios where the resource indicates that the token is expired.

Chamadas durante a transmissão para o Azure AD resultam apenas quando:On-the-wire calls to Azure AD result only when:

  • a perda no cache ocorre porque não há tokens nas identidades gerenciadas do cache do subsistema de recursos do Azurecache miss occurs due to no token in the managed identities for Azure resources subsystem cache
  • o token está expiradothe cached token is expired

Tratamento de errosError handling

As identidades gerenciadas do ponto de extremidade de recursos do Azure sinalizam erros por meio do campo de código de status do cabeçalho da mensagem de resposta HTTP, como erros 4xx ou 5xx:The managed identities for Azure resources endpoint signals errors via the status code field of the HTTP response message header, as either 4xx or 5xx errors:

Código de statusStatus Code Motivo do erroError Reason Como tratarHow To Handle
404 Não Encontrado:404 Not found. Ponto de extremidade IMDS está atualizando.IMDS endpoint is updating. Tente novamente com Expontential retirada.Retry with Expontential Backoff. Consulte as diretrizes abaixo.See guidance below.
429 Número excessivo de solicitações.429 Too many requests. Atingido o limite de restrição IMDS.IMDS Throttle limit reached. Tentar novamente com Retirada Exponencial.Retry with Exponential Backoff. Consulte as diretrizes abaixo.See guidance below.
o erro 4xx na solicitação.4xx Error in request. Um ou mais parâmetros de solicitação estava incorreto.One or more of the request parameters was incorrect. Não tente novamente.Do not retry. Examine os detalhes do erro para obter mais informações.Examine the error details for more information. Os erros 4xx são erros de tempo de design.4xx errors are design-time errors.
Erro 5xx transitório do serviço.5xx Transient error from service. As identidades gerenciadas do subsistema de recursos do Azure ou do Azure Active Directory retornaram um erro transitório.The managed identities for Azure resources sub-system or Azure Active Directory returned a transient error. É seguro tentar novamente após aguardar pelo menos 1 segundo.It is safe to retry after waiting for at least 1 second. Se tentar novamente muito rápido ou com muita frequência, o IMDS e/ou o Microsoft Azure Active Directory poderá retornar um erro de limite de taxa (429).If you retry too quickly or too often, IMDS and/or Azure AD may return a rate limit error (429).
timeouttimeout Ponto de extremidade IMDS está atualizando.IMDS endpoint is updating. Tente novamente com Expontential retirada.Retry with Expontential Backoff. Consulte as diretrizes abaixo.See guidance below.

Se ocorrer um erro, o corpo da resposta HTTP correspondente conterá o JSON com os detalhes do erro:If an error occurs, the corresponding HTTP response body contains JSON with the error details:

ElementoElement DESCRIÇÃODescription
errorerror Identificador do erro.Error identifier.
error_descriptionerror_description Descrição detalhada do erro.Verbose description of error. Descrições de erro podem ser alteradas a qualquer momento. Não escreva código que se ramifique com base nos valores na descrição do erro.Error descriptions can change at any time. Do not write code that branches based on values in the error description.

Referência de resposta HTTPHTTP response reference

Esta seção documenta as possíveis respostas de erro.This section documents the possible error responses. 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.A "200 OK" status is a successful response, and the access token is contained in the response body JSON, in the access_token element.

Código de statusStatus code ErroError Descrição do erroError Description SoluçãoSolution
400 Solicitação Inválida400 Bad Request invalid_resourceinvalid_resource AADSTS50001: O aplicativo chamado <URI> não foi encontrado no locatário chamado <TENANT-ID> .AADSTS50001: The application named <URI> was not found in the tenant named <TENANT-ID>. Isso poderá acontecer se o aplicativo não tiver sido instalado pelo administrador do locatário ou aceito por qualquer usuário no locatário.This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. Talvez você tenha enviado a solicitação de autenticação ao locatário errado.You might have sent your authentication request to the wrong tenant.\ (Apenas Linux)(Linux only)
400 Solicitação Inválida400 Bad Request bad_request_102bad_request_102 Cabeçalho de metadados necessário não especificadoRequired metadata header not specified O campo de cabeçalho de solicitação Metadata está ausente da solicitação ou está formatado incorretamente.Either the Metadata request header field is missing from your request, or is formatted incorrectly. O valor deve ser especificado como true, com todas as letras minúsculas.The value must be specified as true, in all lower case. Consulte a "Solicitação de exemplo" na seção REST anterior para obter um exemplo.See the "Sample request" in the preceding REST section for an example.
401 Não Autorizado401 Unauthorized unknown_sourceunknown_source <URI> de origem desconhecidaUnknown Source <URI> Verifique se o URI da solicitação HTTP GET está formatado corretamente.Verify that your HTTP GET request URI is formatted correctly. A parte scheme:host/resource-path deve ser especificada como http://localhost:50342/oauth2/token.The scheme:host/resource-path portion must be specified as http://localhost:50342/oauth2/token. Consulte a "Solicitação de exemplo" na seção REST anterior para obter um exemplo.See the "Sample request" in the preceding REST section for an example.
invalid_requestinvalid_request A solicitação não tem um parâmetro obrigatório, inclui um valor de parâmetro inválido, inclui um parâmetro mais de uma vez ou está malformada.The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unauthorized_clientunauthorized_client O cliente não está autorizado a solicitar um token de acesso usando este método.The client is not authorized to request an access token using this method. Causado por uma solicitação que não usou loopback local para chamar a extensão ou em uma VM que não tenha identidades gerenciadas para recursos do Azure configuradas corretamente.Caused by a request that didn’t use local loopback to call the extension, or on a VM that doesn’t have managed identities for Azure resources configured correctly. Consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure, se precisar de ajuda com a configuração da VM.See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.
access_deniedaccess_denied O proprietário do recurso ou o servidor de autorização negou a solicitação.The resource owner or authorization server denied the request.
unsupported_response_typeunsupported_response_type O servidor de autorização não dá suporte à obtenção de um token de acesso usando este método.The authorization server does not support obtaining an access token using this method.
invalid_scopeinvalid_scope O escopo solicitado é inválido, desconhecido ou malformado.The requested scope is invalid, unknown, or malformed.
Erro interno do servidor 500500 Internal server error unknownunknown Falha ao recuperar o token do Active Directory.Failed to retrieve token from the Active directory. Para obter detalhes, consulte os logs no <caminho do arquivo>For details see logs in <file path> Verifique se as identidades gerenciadas dos recursos do Azure foram habilitadas na VM.Verify that managed identities for Azure resources has been enabled on the VM. Consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure, se precisar de ajuda com a configuração da VM.See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.

Verifique também se seu URI de solicitação GET HTTP foi formatado corretamente, principalmente o URI do recurso especificado na cadeia de caracteres de consulta.Also verify that your HTTP GET request URI is formatted correctly, particularly the resource URI specified in the query string. Consulte a "Solicitação de exemplo" na seção REST anterior para obter um exemplo ou Serviços do Azure que dão suporte para autenticação do Azure AD para obter uma lista de serviços e seus respectivos IDs de recurso.See the "Sample request" in the preceding REST section for an example, or Azure services that support Azure AD authentication for a list of services and their respective resource IDs.

Repita a orientaçãoRetry guidance

É recomendado tentar novamente se você receber o código de erro 404, 429 ou 5xx (confira Tratamento de erro acima).It is recommended to retry if you receive a 404, 429, or 5xx error code (see Error handling above).

Limitação limites se aplicam ao número de chamadas feitas para o ponto de extremidade IMDS.Throttling limits apply to the number of calls made to the IMDS endpoint. Quando o limite de limitação é excedido, o ponto de extremidade IMDS limita qualquer solicitação adicional enquanto a limitação está em vigor.When the throttling threshold is exceeded, IMDS endpoint limits any further requests while the throttle is in effect. 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.During this period, the IMDS endpoint will return the HTTP status code 429 ("Too many requests"), and the requests fail.

Para tentar novamente, é recomendável a estratégia a seguir:For retry, we recommend the following strategy:

Estratégia de repetiçãoRetry strategy ConfiguraçõesSettings ValoresValues Como funcionaHow it works
ExponentialBackoffExponentialBackoff Contagem de repetiçãoRetry count
Retirada mín.Min back-off
Retirada máx.Max back-off
Retirada deltaDelta back-off
Primeira repetição rápidaFirst fast retry
55
0 s0 sec
60 s60 sec
2 s2 sec
falsofalse
1ª tentativa — intervalo de 0 sAttempt 1 - delay 0 sec
2ª tentativa — intervalo de ~2 sAttempt 2 - delay ~2 sec
3ª tentativa — intervalo de ~6 sAttempt 3 - delay ~6 sec
4ª tentativa — intervalo de ~14 sAttempt 4 - delay ~14 sec
5ª tentativa — intervalo de ~30 sAttempt 5 - delay ~30 sec

IDs de recurso para serviços do AzureResource IDs for Azure services

Consulte Serviços do Azure que dão suporte à autenticação do Azure AD para obter uma lista de recursos que dão suporte ao Azure AS e foram testados com identidades gerenciadas para recursos do Azure e as respectivas IDs do recurso.See Azure services that support Azure AD authentication for a list of resources that support Azure AD and have been tested with managed identities for Azure resources, and their respective resource IDs.

Próximas etapasNext steps