Verwenden von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Azure-Computer zum Abrufen eines ZugriffstokensHow to use managed identities for Azure resources on an Azure VM to acquire an access token

Verwaltete Identitäten für Azure-Ressourcen ist eine Funktion von Azure Active Directory.Managed identities for Azure resources is a feature of Azure Active Directory. Für alle Azure-Dienste, die verwaltete Identitäten unterstützen, gilt ein eigener Zeitplan.Each of the Azure services that support managed identities for Azure resources are subject to their own timeline. Sehen Sie sich den Verfügbarkeitsstatus der verwalteten Identitäten für Ihre Ressource und die bekannten Probleme an, bevor Sie beginnen.Make sure you review the availability status of managed identities for your resource and known issues before you begin.

Verwaltete Identitäten für Azure-Ressourcen stellen für Azure-Dienste eine automatisch verwaltete Identität in Azure Active Directory bereit.Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. Sie können diese Identität für die Authentifizierung bei jedem Dienst verwenden, der die Azure AD-Authentifizierung unterstützt. Hierfür müssen keine Anmeldeinformationen im Code enthalten sein.You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code.

Dieser Artikel enthält verschiedene Code- und Skriptbeispiele für den Tokenabruf sowie eine Anleitung zu wichtigen Themen, z.B. zur Behandlung bei Tokenablauf und HTTP-Fehlern.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.

VoraussetzungenPrerequisites

  • Wenn Sie mit der Funktion für verwaltete Identitäten für Azure-Ressourcen nicht vertraut sind, finden Sie hier eine Übersicht.If you're not familiar with the managed identities for Azure resources feature, see this overview. Wenn Sie kein Azure-Konto haben, sollten Sie sich für ein kostenloses Konto registrieren, bevor Sie fortfahren.If you don't have an Azure account, sign up for a free account before you continue.

Wenn Sie die Azure PowerShell-Beispiele in diesem Artikel verwenden möchten, müssen Sie die neueste Version von Azure PowerShell installieren.If you plan to use the Azure PowerShell examples in this article, be sure to install the latest version of Azure PowerShell.

Wichtig

  • Bei allen Beispielcodes/-skripts in diesem Artikel wird vorausgesetzt, dass der Client auf einem virtuellen Computer mit verwalteten Identitäten für Azure-Ressourcen ausgeführt wird.All sample code/script in this article assumes the client is running on a virtual machine with managed identities for Azure resources. Verwenden Sie die Funktion „Verbinden“ für virtuelle Computer im Azure-Portal zum Herstellen einer Remoteverbindung mit Ihrem virtuellen Computer.Use the virtual machine "Connect" feature in the Azure portal, to remotely connect to your VM. Ausführliche Informationen zum Aktivieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Computer finden Sie unter Konfigurieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Computer über das Azure-Portal oder in einem der verwandten Artikel (PowerShell, CLI, Vorlage oder Azure SDK).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).

Wichtig

  • Die Sicherheitsgrenze für verwaltete Identitäten für Azure-Ressourcen wird durch die Ressource vorgegeben, auf der sie verwendet werden.The security boundary of managed identities for Azure resources, is the resource it's being used on. Der gesamte Code und alle Skripts, die auf einem virtuellen Computer ausgeführt werden, können Token für die darin verfügbaren verwalteten Identitäten anfordern und abrufen.All code/scripts running on a virtual machine can request and retrieve tokens for any managed identities available on it.

ÜbersichtOverview

Eine Clientanwendung kann ein App-exklusives Zugriffstoken der verwalteten Identitäten für Azure-Ressourcen für den Zugriff auf eine bestimmte Ressource anfordern.A client application can request managed identities for Azure resources app-only access token for accessing a given resource. Das Token basiert auf dem Dienstprinzipal der verwalteten Identitäten für Azure-Ressourcen.The token is based on the managed identities for Azure resources service principal. Daher muss sich der Client nicht selbst registrieren, um ein Zugriffstoken unter seinem eigenen Dienstprinzipal abzurufen.As such, there is no need for the client to register itself to obtain an access token under its own service principal. Das Token ist geeignet für die Nutzung als Bearertoken in Dienst-zu-Dienst-Aufrufen, für die Clientanmeldeinformationen benötigt werden.The token is suitable for use as a bearer token in service-to-service calls requiring client credentials.

Abrufen eines Tokens über HTTPGet a token using HTTP Protokolldetails zum Tokenendpunkt für verwaltete Identitäten für Azure-RessourcenProtocol details for managed identities for Azure resources token endpoint
Abrufen eines Tokens mit der Microsoft.Azure.Services.AppAuthentication-Bibliothek für .NETGet a token using the Microsoft.Azure.Services.AppAuthentication library for .NET Beispiel für die Verwendung der Microsoft.Azure.Services.AppAuthentication-Bibliothek auf einem .NET-ClientExample of using the Microsoft.Azure.Services.AppAuthentication library from a .NET client
Abrufen eines Tokens über C#Get a token using C# Beispiel für die Verwendung des REST-Endpunkts für verwaltete Identitäten für Azure-Ressourcen über einen C#-ClientExample of using managed identities for Azure resources REST endpoint from a C# client
Abrufen eines Tokens mit JavaGet a token using Java Beispiel für die Verwendung von verwalteten Identitäten für den REST-Endpunkt von Azure-Ressourcen über einen Java-ClientExample of using managed identities for Azure resources REST endpoint from a Java client
Abrufen eines Tokens über GoGet a token using Go Beispiel für die Verwendung des REST-Endpunkts für verwaltete Identitäten für Azure-Ressourcen über einen Go-ClientExample of using managed identities for Azure resources REST endpoint from a Go client
Abrufen eines Tokens über Azure PowerShellGet a token using Azure PowerShell Beispiel für die Verwendung des REST-Endpunkts für verwaltete Identitäten für Azure-Ressourcen über einen PowerShell-ClientExample of using managed identities for Azure resources REST endpoint from a PowerShell client
Abrufen eines Tokens über cURLGet a token using CURL Beispiel für die Verwendung des REST-Endpunkts für verwaltete Identitäten für Azure-Ressourcen über einen Bash/cURL-ClientExample of using managed identities for Azure resources REST endpoint from a Bash/CURL client
Behandlung der Token-ZwischenspeicherungHandling token caching Anleitung zur Behandlung abgelaufener ZugriffstokenGuidance for handling expired access tokens
FehlerbehandlungError handling Anleitung zur Behandlung von HTTP-Fehlern, die vom Tokenendpunkt für verwaltete Identitäten für Azure-Ressourcen zurückgegeben werdenGuidance for handling HTTP errors returned from the managed identities for Azure resources token endpoint
Ressourcen-IDs für Azure-DiensteResource IDs for Azure services Abrufen von Ressourcen-IDs für unterstützte Azure-DiensteWhere to get resource IDs for supported Azure services

Abrufen eines Tokens über HTTPGet a token using HTTP

Die grundlegende Schnittstelle zum Abrufen eines Zugriffstokens basiert auf REST, sodass sie für alle auf dem virtuellen Computer ausgeführten Clientanwendungen, die HTTP-REST-Aufrufe ausführen können, zur Verfügung steht.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. Dies ähnelt dem Azure AD-Programmiermodell, aber der Client verwendet einen Endpunkt auf dem virtuellen Computer (und keinen Azure AD-Endpunkt).This is similar to the Azure AD programming model, except the client uses an endpoint on the virtual machine (vs an Azure AD endpoint).

Beispielanforderung mit dem Azure-IMDS-Endpunkt (Instance Metadata Service) (empfohlen) :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
ElementElement BESCHREIBUNGDescription
GET Das HTTP-Verb, mit dem angegeben wird, dass Sie Daten vom Endpunkt abrufen möchten.The HTTP verb, indicating you want to retrieve data from the endpoint. In diesem Fall ist dies ein OAuth-Zugriffstoken.In this case, an OAuth access token.
http://169.254.169.254/metadata/identity/oauth2/token Der Endpunkt für verwaltete Identitäten für Azure-Ressourcen für den Instanzmetadatendienst.The managed identities for Azure resources endpoint for the Instance Metadata Service.
api-version Ein Abfragezeichenfolgenparameter, mit dem die API-Version für den IMDS-Endpunkt angegeben wird.A query string parameter, indicating the API version for the IMDS endpoint. Verwenden Sie API-Version 2018-02-01 oder höher.Please use API version 2018-02-01 or greater.
resource Ein Abfragezeichenfolgenparameter, der den App-ID-URI der Zielressource angibt.A query string parameter, indicating the App ID URI of the target resource. Er wird auch im Anspruch aud (audience) des ausgestellten Tokens angezeigt.It also appears in the aud (audience) claim of the issued token. In diesem Beispiel wird ein Token für den Zugriff auf Azure Resource Manager angefordert, das über den App-ID-URI https://management.azure.com/ verfügt.This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata Ein HTTP-Anforderungsheader-Feld, das für verwaltete Identitäten für Azure-Ressourcen als Maßnahme gegen SSRF-Angriffe (Server Side Request Forgery) erforderlich ist.An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. Dieser Wert muss auf „true“ (in Kleinbuchstaben) festgelegt werden.This value must be set to "true", in all lower case.
object_id (Optional) Ein Abfragezeichenfolgen-Parameter, der den object_id-Wert der verwalteten Identität angibt, für die das Token gelten soll.(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. Erforderlich, wenn Ihr virtueller Computer über mehrere vom Benutzer zugewiesene verwaltete Identitäten verfügt.Required, if your VM has multiple user-assigned managed identities.
client_id (Optional) Ein Abfragezeichenfolgen-Parameter, der den client_id-Wert der verwalteten Identität angibt, für die das Token gelten soll.(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. Erforderlich, wenn Ihr virtueller Computer über mehrere vom Benutzer zugewiesene verwaltete Identitäten verfügt.Required, if your VM has multiple user-assigned managed identities.
mi_res_id (Optional) Ein Abfragezeichenfolgenparameter, der das Element „mi_res_id“ (Azure-Ressourcen-ID) der verwalteten Identität angibt, für die das Token gelten soll.(Optional) A query string parameter, indicating the mi_res_id (Azure Resource ID) of the managed identity you would like the token for. Erforderlich, wenn Ihr virtueller Computer über mehrere vom Benutzer zugewiesene verwaltete Identitäten verfügt.Required, if your VM has multiple user-assigned managed identities.

Beispielanforderung mit dem VM-Erweiterungsendpunkt für verwaltete Identitäten für Azure-Ressourcen (Veraltung geplant für Januar 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
ElementElement BESCHREIBUNGDescription
GET Das HTTP-Verb, mit dem angegeben wird, dass Sie Daten vom Endpunkt abrufen möchten.The HTTP verb, indicating you want to retrieve data from the endpoint. In diesem Fall ist dies ein OAuth-Zugriffstoken.In this case, an OAuth access token.
http://localhost:50342/oauth2/token Der Endpunkt für verwaltete Identitäten für Azure-Ressourcen, wobei 50342 der Standardport und konfigurierbar ist.The managed identities for Azure resources endpoint, where 50342 is the default port and is configurable.
resource Ein Abfragezeichenfolgenparameter, der den App-ID-URI der Zielressource angibt.A query string parameter, indicating the App ID URI of the target resource. Er wird auch im Anspruch aud (audience) des ausgestellten Tokens angezeigt.It also appears in the aud (audience) claim of the issued token. In diesem Beispiel wird ein Token für den Zugriff auf Azure Resource Manager angefordert, das über den App-ID-URI https://management.azure.com/ verfügt.This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata Ein HTTP-Anforderungsheader-Feld, das für verwaltete Identitäten für Azure-Ressourcen als Maßnahme gegen SSRF-Angriffe (Server Side Request Forgery) erforderlich ist.An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. Dieser Wert muss auf „true“ (in Kleinbuchstaben) festgelegt werden.This value must be set to "true", in all lower case.
object_id (Optional) Ein Abfragezeichenfolgen-Parameter, der den object_id-Wert der verwalteten Identität angibt, für die das Token gelten soll.(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. Erforderlich, wenn Ihr virtueller Computer über mehrere vom Benutzer zugewiesene verwaltete Identitäten verfügt.Required, if your VM has multiple user-assigned managed identities.
client_id (Optional) Ein Abfragezeichenfolgen-Parameter, der den client_id-Wert der verwalteten Identität angibt, für die das Token gelten soll.(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. Erforderlich, wenn Ihr virtueller Computer über mehrere vom Benutzer zugewiesene verwaltete Identitäten verfügt.Required, if your VM has multiple user-assigned managed identities.

Beispiel für eine Antwort: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"
}
ElementElement BESCHREIBUNGDescription
access_token Das angeforderte Zugriffstoken.The requested access token. Beim Aufrufen einer geschützten REST-API wird das Token als „Bearertoken“ in das Authorization-Anforderungsheader-Feld eingebettet, damit der Aufrufer von der API authentifiziert werden kann.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 Wird von verwalteten Identitäten für Azure-Ressourcen nicht verwendet.Not used by managed identities for Azure resources.
expires_in Der Zeitraum in Sekunden, wie lange das Zugriffstoken ab dem Zeitpunkt der Ausstellung gültig ist, bevor es abläuft.The number of seconds the access token continues to be valid, before expiring, from time of issuance. Der Ausstellungszeitpunkt ist im Anspruch iat des Tokens zu finden.Time of issuance can be found in the token's iat claim.
expires_on Der Zeitpunkt, zu dem das Zugriffstoken abläuft.The timespan when the access token expires. Das Datum wird als Anzahl von Sekunden ab „1970-01-01T0:0:0Z UTC“ (entspricht dem Anspruch exp des Tokens) dargestellt.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 Der Zeitpunkt, ab dem das Zugriffstoken wirksam ist und akzeptiert werden kann.The timespan when the access token takes effect, and can be accepted. Das Datum wird als Anzahl von Sekunden ab „1970-01-01T0:0:0Z UTC“ (entspricht dem Anspruch nbf des Tokens) dargestellt.The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's nbf claim).
resource Die Ressource, für die das Zugriffstoken angefordert wurde (Übereinstimmung mit dem Abfragezeichenfolgenparameter resource der Anforderung).The resource the access token was requested for, which matches the resource query string parameter of the request.
token_type Der Typ des Tokens. In diesem Fall ein „Bearerzugriffstoken“, sodass die Ressource Zugriff auf den Bearer dieses Tokens gewähren kann.The type of token, which is a "Bearer" access token, which means the resource can give access to the bearer of this token.

Abrufen eines Tokens mit der Microsoft.Azure.Services.AppAuthentication-Bibliothek für .NETGet a token using the Microsoft.Azure.Services.AppAuthentication library for .NET

Bei .NET-Anwendungen und -Funktionen stellt die einfachste Methode für die Arbeit mit verwalteten Identitäten für Azure-Ressourcen das Microsoft.Azure.Services.AppAuthentication-Paket dar.For .NET applications and functions, the simplest way to work with managed identities for Azure resources is through the Microsoft.Azure.Services.AppAuthentication package. Mithilfe dieser Bibliothek können Sie zudem Ihren Code lokal auf dem Entwicklungscomputer testen. Hierzu verwenden Sie Ihr Benutzerkonto aus Visual Studio, aus der Azure CLI oder der integrierten Active Directory-Authentifizierung.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. Weitere Informationen zu Optionen für die lokale Entwicklung mit dieser Bibliothek finden Sie in der Microsoft.Azure.Services.AppAuthentication-Referenz.For more on local development options with this library, see the Microsoft.Azure.Services.AppAuthentication reference. In diesem Abschnitt werden die ersten Schritte mit der Bibliothek in Ihrem Code erläutert.This section shows you how to get started with the library in your code.

  1. Fügen Sie Ihrer Anwendung einen Verweis auf die NuGet-Pakete Microsoft.Azure.Services.AppAuthentication und Microsoft.Azure.KeyVault hinzu.Add references to the Microsoft.Azure.Services.AppAuthentication and Microsoft.Azure.KeyVault NuGet packages to your application.

  2. Fügen Sie Ihrer Anwendung den folgenden Code hinzu: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));
    

Weitere Informationen zu Microsoft.Azure.Services.AppAuthentication und den zugehörigen Vorgängen finden Sie in der Microsoft.Azure.Services.AppAuthentication-Referenz und im .NET-Beispiel zu App Service und KeyVault mit verwalteten Identitäten für Azure-Ressourcen.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.

Abrufen eines Tokens über 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");
}

Abrufen eines Tokens mit JavaGet a token using Java

Verwenden Sie diese JSON-Bibliothek, um ein Token mithilfe von Java abzurufen.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;
                }
            }
        }
    }
}

Abrufen eines Tokens über 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)
}

Abrufen eines Tokens über Azure PowerShellGet a token using Azure PowerShell

Im folgenden Beispiel wird veranschaulicht, wie Sie den REST-Endpunkt für verwaltete Identitäten für Azure-Ressourcen über einen PowerShell-Client für Folgendes verwenden:The following example demonstrates how to use the managed identities for Azure resources REST endpoint from a PowerShell client to:

  1. Abrufen eines ZugriffstokensAcquire an access token.
  2. Verwenden des Zugriffstokens, um eine Azure Resource Manager-REST-API aufzurufen und Informationen zum virtuellen Computer abzurufenUse the access token to call an Azure Resource Manager REST API and get information about the VM. Achten Sie darauf, dass Sie <SUBSCRIPTION-ID>, <RESOURCE-GROUP> und <VM-NAME> jeweils durch Ihre Abonnement-ID, den Namen der Ressourcengruppe und den Namen des virtuellen Computers ersetzen.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"}

Beispiel zum Extrahieren des Zugriffstokens aus der Antwort: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

Abrufen eines Tokens über 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

Beispiel zum Extrahieren des Zugriffstokens aus der Antwort: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

Zwischenspeichern von TokensToken caching

Zwar speichert das verwendete Subsystem für verwaltete Identitäten für Azure-Ressourcen (IMDS/VM-Erweiterung für verwaltete Identitäten für Azure-Ressourcen) Tokens zwischen, es wird jedoch empfohlen, auch die Zwischenspeicherung von Token in Ihrem Code zu implementieren.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. Daher sollten Sie Vorbereitungen für Szenarien treffen, bei denen die Ressource angibt, dass das Token abgelaufen ist.As a result, you should prepare for scenarios where the resource indicates that the token is expired.

Aufrufe an Azure AD über das Netzwerk erfolgen nur in folgenden Fällen:On-the-wire calls to Azure AD result only when:

  • Cachefehler aufgrund eines fehlenden Tokens im Cache des Subsystems für verwaltete Identitäten für Azure-Ressourcencache miss occurs due to no token in the managed identities for Azure resources subsystem cache
  • Abgelaufenes zwischengespeichertes Tokenthe cached token is expired

FehlerbehandlungError handling

Der Endpunkt für verwaltete Identitäten für Azure-Ressourcen signalisiert Fehler über das Statuscodefeld des Nachrichtenheaders der HTTP-Antwort als 4xx- oder 5xx-Fehler: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:

StatuscodeStatus Code FehlerursacheError Reason FehlerbehandlungHow To Handle
404 – Nicht gefunden.404 Not found. Der IMDS-Endpunkt wird gerade aktualisiert.IMDS endpoint is updating. Wiederholungsversuch mit exponentiellem Backoff.Retry with Expontential Backoff. Siehe Anleitung unten.See guidance below.
429: Zu viele Anforderungen.429 Too many requests. IMDS-Drosselungsgrenzwert erreicht.IMDS Throttle limit reached. Wiederholungsversuch mit exponentiellem Backoff.Retry with Exponential Backoff. Siehe Anleitung unten.See guidance below.
4xx – Fehler in der Anforderung.4xx Error in request. Mindestens einer der Anforderungsparameter war falsch.One or more of the request parameters was incorrect. Wiederholen Sie den Vorgang nicht.Do not retry. Überprüfen Sie den Fehler, um weitere Informationen zu erhalten.Examine the error details for more information. 4xx-Fehler sind Fehler während der Entwurfszeit.4xx errors are design-time errors.
5xx – Vorübergehender Fehler vom Dienst.5xx Transient error from service. Das Subsystem für verwaltete Identitäten für Azure-Ressourcen oder Azure Active Directory hat einen vorübergehenden Fehler zurückgegeben.The managed identities for Azure resources sub-system or Azure Active Directory returned a transient error. Nach mindestens 1 Sekunde können Sie den Vorgang wiederholen.It is safe to retry after waiting for at least 1 second. Wenn Sie den Vorgang zu schnell oder zu häufig wiederholen, gibt IMDS und/oder Azure AD möglicherweise einen Fehler zum Ratenlimit (429) zurück.If you retry too quickly or too often, IMDS and/or Azure AD may return a rate limit error (429).
timeouttimeout Der IMDS-Endpunkt wird gerade aktualisiert.IMDS endpoint is updating. Wiederholungsversuch mit exponentiellem Backoff.Retry with Expontential Backoff. Siehe Anleitung unten.See guidance below.

Wenn ein Fehler auftritt, enthält der entsprechende HTTP-Antworttext JSON-Code mit den Fehlerdetails:If an error occurs, the corresponding HTTP response body contains JSON with the error details:

ElementElement BESCHREIBUNGDescription
errorerror Fehler-IDError identifier.
error_descriptionerror_description Ausführliche Beschreibung des Fehlers.Verbose description of error. Fehlerbeschreibungen können sich jederzeit ändern. Schreiben Sie keinen Code, der sich basierend auf Werten in der Fehlerbeschreibung brancht.Error descriptions can change at any time. Do not write code that branches based on values in the error description.

Referenz für HTTP-AntwortenHTTP response reference

In diesem Abschnitt sind die möglichen Fehlerantworten aufgeführt.This section documents the possible error responses. Der Status „200 OK“ ist eine erfolgreiche Antwort, und das Zugriffstoken ist im JSON-Antworttext im Element „access_token“ enthalten.A "200 OK" status is a successful response, and the access token is contained in the response body JSON, in the access_token element.

StatuscodeStatus code ErrorError FehlerbeschreibungError Description LösungSolution
400 – Ungültige Anforderung400 Bad Request invalid_resourceinvalid_resource AADSTS50001: Die Anwendung namens <URI> wurde im Mandanten <TENANT-ID> nicht gefunden.AADSTS50001: The application named <URI> was not found in the tenant named <TENANT-ID>. Dies kann auftreten, wenn die Anwendung nicht vom Administrator des Mandanten installiert wurde oder wenn sie von den Benutzern des Mandanten keine Zustimmung erhalten hat.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. Unter Umständen haben Sie Ihre Authentifizierung an den falschen Mandanten gesendet.You might have sent your authentication request to the wrong tenant.</span> (Nur Linux)(Linux only)
400 – Ungültige Anforderung400 Bad Request bad_request_102bad_request_102 Erforderlicher Metadatenheader nicht angegebenRequired metadata header not specified Entweder fehlt der Metadata-Anforderungsheader in Ihrer Anforderung, oder er ist falsch formatiert.Either the Metadata request header field is missing from your request, or is formatted incorrectly. Der Wert muss als true (in Kleinbuchstaben) angegeben werden.The value must be specified as true, in all lower case. Ein Beispiel finden Sie im vorherigen REST-Abschnitt unter „Beispiel für eine Anforderung“.See the "Sample request" in the preceding REST section for an example.
401 – Nicht autorisiert401 Unauthorized unknown_sourceunknown_source Unbekannte Quelle <URI>Unknown Source <URI> Stellen Sie sicher, dass Ihr HTTP GET-Anforderungs-URI richtig formatiert ist.Verify that your HTTP GET request URI is formatted correctly. Der Teil scheme:host/resource-path muss als http://localhost:50342/oauth2/token angegeben werden.The scheme:host/resource-path portion must be specified as http://localhost:50342/oauth2/token. Ein Beispiel finden Sie im vorherigen REST-Abschnitt unter „Beispiel für eine Anforderung“.See the "Sample request" in the preceding REST section for an example.
invalid_requestinvalid_request In der Anforderung fehlt ein erforderlicher Parameter, ist ein ungültiger Parameter enthalten oder ist ein Parameter mehrfach vorhanden, oder die Anforderung ist auf andere Weise fehlerhaft.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 Der Client ist zum Anfordern eines Zugriffstokens mit dieser Methode nicht autorisiert.The client is not authorized to request an access token using this method. Ursache ist eine Anforderung, die keinen lokalen Loopback zum Aufrufen der Erweiterung verwendet hat, oder ein virtueller Computer, auf dem keine verwalteten Identitäten für Azure-Ressourcen ordnungsgemäß konfiguriert sind.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. Hilfe zur Konfiguration des virtuellen Computers finden Sie unter Konfigurieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Computer über das Azure-Portal.See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.
access_deniedaccess_denied Der Ressourcenbesitzer oder Autorisierungsserver hat die Anforderung verweigert.The resource owner or authorization server denied the request.
unsupported_response_typeunsupported_response_type Der Autorisierungsserver unterstützt das Abrufen eines Zugriffstokens mit dieser Methode nicht.The authorization server does not support obtaining an access token using this method.
invalid_scopeinvalid_scope Der angeforderte Bereich ist ungültig, unbekannt oder falsch formatiert.The requested scope is invalid, unknown, or malformed.
500 Interner Serverfehler500 Internal server error unknownunknown Beim Abrufen des Tokens aus Active Directory ist ein Fehler aufgetreten.Failed to retrieve token from the Active directory. Details finden Sie in den Protokollen unter <Dateipfad> .For details see logs in <file path> Stellen Sie sicher, dass verwaltete Identitäten für Azure-Ressourcen auf dem virtuellen Computer aktiviert wurden.Verify that managed identities for Azure resources has been enabled on the VM. Hilfe zur Konfiguration des virtuellen Computers finden Sie unter Konfigurieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Computer über das Azure-Portal.See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.

Überprüfen Sie zudem, ob Ihr HTTP GET-Anforderungs-URI richtig formatiert ist. Dies gilt vor allem für den Ressourcen-URI, der in der Abfragezeichenfolge angegeben ist.Also verify that your HTTP GET request URI is formatted correctly, particularly the resource URI specified in the query string. Unter „Beispiel für eine Anforderung“ im vorherigen REST-Abschnitt finden Sie ein Beispiel, und unter Azure-Dienste, die die Azure AD-Authentifizierung unterstützen finden Sie eine Liste mit Diensten und den dazugehörigen Ressourcen-IDs.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.

Informationen zur WiederholungRetry guidance

Wenn Sie einen Fehlercode vom Typ 404, 429 oder 5xx erhalten, sollten Sie den Vorgang wiederholen. (Weitere Informationen finden Sie weiter oben unter Fehlerbehandlung.)It is recommended to retry if you receive a 404, 429, or 5xx error code (see Error handling above).

Drosselungsgrenzwerte gelten für die Anzahl von Aufrufen, die an den IMDS-Endpunkt gerichtet werden.Throttling limits apply to the number of calls made to the IMDS endpoint. Wird der Drosselungsschwellenwert überschritten, schränkt der IMDS-Endpunkt alle weiteren Anforderungen ein, während die Drosselung aktiv ist.When the throttling threshold is exceeded, IMDS endpoint limits any further requests while the throttle is in effect. Während dieser Zeit gibt der IMDS-Endpunkt den HTTP-Statuscode 429 (zu viele Anforderungen) zurück, und die Anforderungen sind nicht erfolgreich.During this period, the IMDS endpoint will return the HTTP status code 429 ("Too many requests"), and the requests fail.

Empfohlene Wiederholungsstrategie:For retry, we recommend the following strategy:

WiederholungsstrategieRetry strategy EinstellungenSettings WerteValues So funktioniert'sHow it works
ExponentialBackoffExponentialBackoff Anzahl der WiederholungenRetry count
Min. BackoffMin back-off
Max. BackoffMax back-off
Delta-BackoffDelta back-off
Erster schneller WiederholungsversuchFirst fast retry
55
0 Sek.0 sec
60 Sekunden60 sec
2 Sek2 sec
falsefalse
Versuch 1 – Verzögerung 0 Sek.Attempt 1 - delay 0 sec
Versuch 2 – Verzögerung ca. 2 Sek.Attempt 2 - delay ~2 sec
Versuch 3 – Verzögerung ca. 6 Sek.Attempt 3 - delay ~6 sec
Versuch 4 – Verzögerung ca. 14 Sek.Attempt 4 - delay ~14 sec
Versuch 5 – Verzögerung ca. 30 Sek.Attempt 5 - delay ~30 sec

Ressourcen-IDs für Azure-DiensteResource IDs for Azure services

Eine Liste mit Ressourcen, die Azure AD unterstützen und mit verwalteten Identitäten für Azure-Ressourcen getestet wurden, und die jeweiligen zugehörigen Ressourcen-IDs finden Sie unter Azure-Dienste, die die Azure AD-Authentifizierung unterstützen.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.

Nächste SchritteNext steps