Azure VM 上で Azure リソースのマネージド ID を使用してアクセス トークンを取得する方法How to use managed identities for Azure resources on an Azure VM to acquire an access token

Azure リソースのマネージドID は、Azure Active Directory の機能です。Managed identities for Azure resources is a feature of Azure Active Directory. Azure リソースのマネージド ID をサポートする各 Azure サービスは、それぞれ固有のタイムラインの下で提供されます。Each of the Azure services that support managed identities for Azure resources are subject to their own timeline. ご利用のリソースに対するマネージド ID の提供状態と既知の問題をあらかじめ確認しておいてください。Make sure you review the availability status of managed identities for your resource and known issues before you begin.

Azure リソースのマネージド ID は、Azure Active Directory で自動的に管理される ID を Azure サービスに提供します。Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. この ID を使用して、コードに資格情報が含まれていなくても、Azure AD の認証をサポートする任意のサービスに認証することができます。You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code.

この記事では、トークンの取得に使用する各種コードとスクリプトの例を提供するほか、トークンの有効期限や 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.

前提条件Prerequisites

  • Azure リソースのマネージド ID 機能に慣れていない場合は、こちらの概要を参照してください。If you're not familiar with the managed identities for Azure resources feature, see this overview. Azure アカウントをお持ちでない場合は、無料のアカウントにサインアップしてから先に進んでください。If you don't have an Azure account, sign up for a free account before you continue.

この記事の Azure PowerShell の例を使用する場合は、Azure PowerShell の最新バージョンをインストールする必要があります。If you plan to use the Azure PowerShell examples in this article, be sure to install the latest version of Azure PowerShell.

重要

  • この記事のすべてのサンプル コード/スクリプトは、Azure リソースのマネージド ID を使用する仮想マシン上でクライアントが実行されていることを前提としています。All sample code/script in this article assumes the client is running on a virtual machine with managed identities for Azure resources. お使いの VM にリモート接続するには、Azure portal で VM への "接続" 機能を使用します。Use the virtual machine "Connect" feature in the Azure portal, to remotely connect to your VM. VM で Azure リソースのマネージド ID を有効にする方法の詳細については、「Configure managed identities for Azure resources on a VM using the Azure portal」(Azure portal を使用して VM 上で Azure リソースのマネージド ID を構成する)、または関連する記事 (PowerShell、CLI、テンプレート、または 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).

重要

  • Azure リソースのマネージド ID のセキュリティ境界は、使用されているリソースです。The security boundary of managed identities for Azure resources, is the resource it's being used on. 仮想マシン上で実行されるすべてのコード/スクリプトは、そこで使用できる任意のマネージド ID のトークンを要求して取得できます。All code/scripts running on a virtual machine can request and retrieve tokens for any managed identities available on it.

概要Overview

クライアント アプリケーションは、特定のリソースにアクセスするために、Azure リソースのアプリ専用アクセス トークンに対してマネージド ID を要求できます。A client application can request managed identities for Azure resources app-only access token for accessing a given resource. トークンは、Azure リソース サービス プリンシパルのマネージド ID に基づいていますThe token is based on the managed identities for Azure resources service principal. そのため、独自のサービス プリンシパルでアクセス トークンを取得するために、クライアントそのものを登録する必要がありません。As such, there is no need for the client to register itself to obtain an access token under its own service principal. トークンは、クライアント資格情報を必要とするサービス間の呼び出しのベアラー トークンとしての使用に適しています。The token is suitable for use as a bearer token in service-to-service calls requiring client credentials.

HTTP を使用してトークンを取得するGet a token using HTTP Azure リソース トークン エンドポイントのマネージド ID に関するプロトコルの詳細Protocol details for managed identities for Azure resources token endpoint
.NET 用の Microsoft.Azure.Services.AppAuthentication ライブラリを使用してトークンを取得するGet a token using the Microsoft.Azure.Services.AppAuthentication library for .NET .NET クライアントからの Microsoft.Azure.Services.AppAuthentication ライブラリの使用例Example of using the Microsoft.Azure.Services.AppAuthentication library from a .NET client
C# を使用してトークンを取得するGet a token using C# C# クライアントから Azure リソース REST エンドポイントのマネージド ID を使用する例Example of using managed identities for Azure resources REST endpoint from a C# client
Java を使用してトークンを取得するGet a token using Java Java クライアントから Azure リソース REST エンドポイントのマネージド ID を使用する例Example of using managed identities for Azure resources REST endpoint from a Java client
Go を使用してトークンを取得するGet a token using Go Go クライアントから Azure リソース REST エンドポイントのマネージド ID を使用する例Example of using managed identities for Azure resources REST endpoint from a Go client
Azure PowerShell を使用してトークンを取得するGet a token using Azure PowerShell PowerShell クライアントから Azure リソース REST エンドポイントのマネージド ID を使用する例Example of using managed identities for Azure resources REST endpoint from a PowerShell client
CURL を使用してトークンを取得するGet a token using CURL Bash/CURL クライアントから Azure リソース REST エンドポイントのマネージド ID を使用する例Example of using managed identities for Azure resources REST endpoint from a Bash/CURL client
トークンのキャッシュの処理Handling token caching 有効期限が切れたアクセス トークンの処理に関するガイダンスGuidance for handling expired access tokens
エラー処理Error handling Azure リソース トークン エンドポイントのマネージド ID から返される HTTP エラーを処理するためのガイダンスGuidance for handling HTTP errors returned from the managed identities for Azure resources token endpoint
Azure サービスのリソース IDResource IDs for Azure services サポートされている Azure サービスのリソース ID を取得する場所Where to get resource IDs for supported Azure services

HTTP を使用してトークンを取得するGet a token using HTTP

アクセス トークンの取得に使用する基本的なインターフェイスは REST に基づいているため、HTTP REST の呼び出しを行える VM 上で実行されている、すべてのクライアント アプリケーションにアクセスできます。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. これは、クライアントが仮想マシン上のエンドポイントを使用する点以外は、Azure AD のプログラミング モデルと同じです (Azure AD のプログラミング モデルでは、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).

Azure Instance Metadata Service (IMDS) エンドポイントを使用するサンプル要求 (推奨) :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
要素Element 説明Description
GET HTTP 動詞。エンドポイントからデータを取得する必要があることを示します。The HTTP verb, indicating you want to retrieve data from the endpoint. この例では、OAuth アクセス トークンです。In this case, an OAuth access token.
http://169.254.169.254/metadata/identity/oauth2/token Instance Metadata Service 用の Azure リソース エンドポイントのマネージド ID。The managed identities for Azure resources endpoint for the Instance Metadata Service.
api-version クエリ文字列パラメーター。IMDS エンドポイントの API バージョンです。A query string parameter, indicating the API version for the IMDS endpoint. API バージョン 2018-02-01 以上を使用してください。Please use API version 2018-02-01 or greater.
resource クエリ文字列パラメーター。ターゲット リソースのアプリ ID URI です。A query string parameter, indicating the App ID URI of the target resource. 発行されたトークンの aud (audience) 要求にも表示されます。It also appears in the aud (audience) claim of the issued token. この例では、アプリ ID URI が https://management.azure.com/ の Azure Resource Manager にアクセスするためのトークンを要求しています。This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata HTTP 要求ヘッダー フィールド。サーバー側のリクエスト フォージェリ (SSRF) 攻撃に対する軽減策として Azure リソースのマネージド ID に必要です。An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. この値は、"true" に設定し、すべて小文字にする必要があります。This value must be set to "true", in all lower case.
object_id (省略可能) クエリの文字列パラメーター。トークン用の管理対象 ID の object_id を示します。(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. VM に複数のユーザーが割り当てたマネージド ID がある場合は必須です。Required, if your VM has multiple user-assigned managed identities.
client_id (省略可能) クエリの文字列パラメーター。トークン用の管理対象 ID の client_id を示します。(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. VM に複数のユーザーが割り当てたマネージド ID がある場合は必須です。Required, if your VM has multiple user-assigned managed identities.
mi_res_id (省略可能) クエリの文字列パラメーター。トークン用の管理対象 ID の mi_res_id (Azure リソース ID) を示します。(Optional) A query string parameter, indicating the mi_res_id (Azure Resource ID) of the managed identity you would like the token for. VM に複数のユーザーが割り当てたマネージド ID がある場合は必須です。Required, if your VM has multiple user-assigned managed identities.

Azure リソース VM 拡張機能エンドポイントにマネージド ID を使用するサンプル要求 (2019 年 1 月に非推奨となる予定) :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
要素Element 説明Description
GET HTTP 動詞。エンドポイントからデータを取得する必要があることを示します。The HTTP verb, indicating you want to retrieve data from the endpoint. この例では、OAuth アクセス トークンです。In this case, an OAuth access token.
http://localhost:50342/oauth2/token Azure リソース エンドポイントのマネージド ID (50342 は既定のポートであり、構成可能です)。The managed identities for Azure resources endpoint, where 50342 is the default port and is configurable.
resource クエリ文字列パラメーター。ターゲット リソースのアプリ ID URI です。A query string parameter, indicating the App ID URI of the target resource. 発行されたトークンの aud (audience) 要求にも表示されます。It also appears in the aud (audience) claim of the issued token. この例では、アプリ ID URI が https://management.azure.com/ の Azure Resource Manager にアクセスするためのトークンを要求しています。This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/.
Metadata HTTP 要求ヘッダー フィールド。サーバー側のリクエスト フォージェリ (SSRF) 攻撃に対する軽減策として Azure リソースのマネージド ID に必要です。An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. この値は、"true" に設定し、すべて小文字にする必要があります。This value must be set to "true", in all lower case.
object_id (省略可能) クエリの文字列パラメーター。トークン用の管理対象 ID の object_id を示します。(Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. VM に複数のユーザーが割り当てたマネージド ID がある場合は必須です。Required, if your VM has multiple user-assigned managed identities.
client_id (省略可能) クエリの文字列パラメーター。トークン用の管理対象 ID の client_id を示します。(Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. VM に複数のユーザーが割り当てたマネージド ID がある場合は必須です。Required, if your VM has multiple user-assigned managed identities.

応答のサンプル: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"
}
要素Element 説明Description
access_token 要求されたアクセス トークン。The requested access token. セキュリティで保護された REST API を呼び出すとき、トークンは Authorization 要求ヘッダー フィールドに "ベアラー" トークンとして埋め込まれ、API が呼び出し元を認証できるようにします。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 Azure リソースのマネージド ID には使用されません。Not used by managed identities for Azure resources.
expires_in アクセス トークンが発行されてから期限切れになるまでの有効継続時間 (秒単位)。The number of seconds the access token continues to be valid, before expiring, from time of issuance. 発行時刻はトークンの iat 要求で確認できます。Time of issuance can be found in the token's iat claim.
expires_on アクセス トークンが期限切れになるまでの期間。The timespan when the access token expires. 日付は "1970-01-01T0:0:0Z UTC" からの秒数として表されます (トークンの exp 要求に対応)。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 アクセス トークンが有効になり、承認されるまでの期間。The timespan when the access token takes effect, and can be accepted. 日付は "1970-01-01T0:0:0Z UTC" からの秒数として表されます (トークンの nbf 要求に対応)。The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's nbf claim).
resource アクセス トークンの要求対象リソース。要求の resource クエリ文字列パラメーターと一致します。The resource the access token was requested for, which matches the resource query string parameter of the request.
token_type トークンの種類。つまり "ベアラー" アクセス トークン。リソースが、このトークンのベアラーへのアクセスを提供できることを意味します。The type of token, which is a "Bearer" access token, which means the resource can give access to the bearer of this token.

.NET 用の Microsoft.Azure.Services.AppAuthentication ライブラリを使用してトークンを取得するGet a token using the Microsoft.Azure.Services.AppAuthentication library for .NET

.NET アプリケーションと Functions の場合、Azure リソースのマネージド ID を使用する最も簡単な方法は、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. このライブラリを使うと、Visual Studio、Azure CLI、または 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. このライブラリでのローカル開発オプションについて詳しくは、Microsoft.Azure.Services.AppAuthentication のリファレンスに関するページをご覧ください。For more on local development options with this library, see the Microsoft.Azure.Services.AppAuthentication reference. このセクションでは、コードでライブラリを使い始める方法を示します。This section shows you how to get started with the library in your code.

  1. Microsoft.Azure.Services.AppAuthentication および Microsoft.Azure.KeyVault NuGet パッケージに対する参照をアプリケーションに追加します。Add references to the Microsoft.Azure.Services.AppAuthentication and Microsoft.Azure.KeyVault NuGet packages to your application.

  2. 次のコードをアプリケーションに追加します。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));
    

Microsoft.Azure.Services.AppAuthentication およびそれによって公開される操作の詳細については、Microsoft.Azure.Services.AppAuthentication リファレンスAzure リソースのマネージド ID を使用する App Service および KeyVault の .NET サンプルを参照してください。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.

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

Java を使用してトークンを取得するGet a token using Java

Java を使用してトークンを取得するには、この JSON ライブラリを使用します。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;
                }
            }
        }
    }
}

Go を使用してトークンを取得するGet 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)
}

Azure PowerShell を使用してトークンを取得するGet a token using Azure PowerShell

次の例では、PowerShell クライアントから Azure リソース REST エンドポイントのマネージド ID を使用して、以下を実行する方法を示します。The following example demonstrates how to use the managed identities for Azure resources REST endpoint from a PowerShell client to:

  1. アクセス トークンを取得します。Acquire an access token.
  2. アクセス トークンを使用して Azure Resource Manager の REST API を呼び出し、VM に関する情報を取得します。Use the access token to call an Azure Resource Manager REST API and get information about the VM. <SUBSCRIPTION-ID><RESOURCE-GROUP>、および <VM-NAME> の代わりに、ご自分のサブスクリプション ID、リソース グループ名、および仮想マシン名をそれぞれ使用する必要があります。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"}

応答からアクセス トークンを解析する方法の例を次に示します。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

CURL を使用してトークンを取得するGet 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

応答からアクセス トークンを解析する方法の例を次に示します。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

トークンのキャッシュToken caching

Azure リソース サブシステムのマネージド ID (Azure リソース VM 拡張機能の IMDS/マネージド ID) はキャッシュ トークンを実行しますが、コードにトークン キャッシングを実装することもお勧めします。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. そのため、リソースがトークンの有効期限切れを示すシナリオに備える必要があります。As a result, you should prepare for scenarios where the resource indicates that the token is expired.

ネットワークを介した Azure AD の呼び出しは、次の場合にのみ行われます。On-the-wire calls to Azure AD result only when:

  • Azure リソース サブシステム キャッシュのマネージド ID にトークンがないためキャッシュ ミスが発生するcache miss occurs due to no token in the managed identities for Azure resources subsystem cache
  • キャッシュのトークンの有効期限が切れているthe cached token is expired

エラー処理Error handling

Azure リソース エンドポイントのマネージド ID は、HTTP 応答メッセージのヘッダーに含まれる状態コード フィールドを通じて、4xx エラーまたは 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:

状態コードStatus Code エラーの理由Error Reason 処理方法How To Handle
404 見つかりません。404 Not found. IMDS エンドポイントが更新されています。IMDS endpoint is updating. 指数バックオフを使用して再試行してください。Retry with Expontential Backoff. 以下のガイダンスを参照してください。See guidance below.
429 要求が多すぎます。429 Too many requests. IMDS スロットルの上限に達しました。IMDS Throttle limit reached. 指数バックオフを使用して再試行してください。Retry with Exponential Backoff. 以下のガイダンスを参照してください。See guidance below.
要求の 4xx エラーです。4xx Error in request. 1 つ以上の要求パラメーターが正しくありませんでした。One or more of the request parameters was incorrect. 再試行はしないでください。Do not retry. 詳しくは、エラーの詳細を確認します。Examine the error details for more information. 4xx エラーは、デザイン時のエラーです。4xx errors are design-time errors.
サービスからの 5xx の一時的なエラーです。5xx Transient error from service. Azure リソース サブシステムまたは Azure Active Directory のマネージド ID から一時的なエラーが返されました。The managed identities for Azure resources sub-system or Azure Active Directory returned a transient error. 少なくとも 1 秒間待機した後に、安全に再試行できます。It is safe to retry after waiting for at least 1 second. 再試行が早すぎる場合や再試行の回数が多すぎる場合は、IMDS および Azure AD からレート制限エラー (429) が返されることがあります。If you retry too quickly or too often, IMDS and/or Azure AD may return a rate limit error (429).
timeouttimeout IMDS エンドポイントが更新されています。IMDS endpoint is updating. 指数バックオフを使用して再試行してください。Retry with Expontential Backoff. 以下のガイダンスを参照してください。See guidance below.

エラーが発生すると、対応する HTTP 応答本文に、JSON とエラーの詳細が含まれます。If an error occurs, the corresponding HTTP response body contains JSON with the error details:

要素Element 説明Description
errorerror エラー識別子。Error identifier.
error_descriptionerror_description エラーの詳細な説明。Verbose description of error. エラーの説明は、予告なく変更になる場合があります。エラーの説明に含まれる値に基づいて分岐するコードを作成しないでください。Error descriptions can change at any time. Do not write code that branches based on values in the error description.

HTTP 応答リファレンスHTTP response reference

このセクションでは、想定されるエラー応答について説明します。This section documents the possible error responses. "200 OK" の状態は成功応答であり、access_token 要素内の応答本文の JSON にアクセス トークンが含まれています。A "200 OK" status is a successful response, and the access token is contained in the response body JSON, in the access_token element.

状態コードStatus code ErrorError エラーの説明Error Description 解決策Solution
400 Bad Request400 Bad Request invalid_resourceinvalid_resource AADSTS50001: <URI> という名前のアプリケーションが <TENANT-ID> という名前のテナントに見つかりませんでした。AADSTS50001: The application named <URI> was not found in the tenant named <TENANT-ID>. このエラーは、アプリケーションがテナントの管理者によってインストールされていない場合や、アプリケーションがテナント内のいずれのユーザーによっても同意されていない場合に発生することがあります。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. 間違ったテナントに認証要求を送信した可能性があります。You might have sent your authentication request to the wrong tenant.\ (Linux のみ)(Linux only)
400 Bad Request400 Bad Request bad_request_102bad_request_102 必要なメタデータ ヘッダーが指定されていませんRequired metadata header not specified 要求で Metadata 要求ヘッダー フィールドが見つからないか、形式が正しくありません。Either the Metadata request header field is missing from your request, or is formatted incorrectly. 値は true として指定し、すべて小文字にする必要があります。The value must be specified as true, in all lower case. 例については、上記の「REST」セクションの「要求のサンプル」を参照してください。See the "Sample request" in the preceding REST section for an example.
401 権限がありません401 Unauthorized unknown_sourceunknown_source 不明なソース <URI>Unknown Source <URI> HTTP GET 要求の URI の形式が正しいことを確認します。Verify that your HTTP GET request URI is formatted correctly. scheme:host/resource-path 部分は、http://localhost:50342/oauth2/token として指定する必要があります。The scheme:host/resource-path portion must be specified as http://localhost:50342/oauth2/token. 例については、上記の「REST」セクションの「要求のサンプル」を参照してください。See the "Sample request" in the preceding REST section for an example.
invalid_requestinvalid_request 要求に必要なパラメーターが含まれていないか、要求に無効なパラメーター値が含まれているか、要求に複数回パラメーターが含まれているか、要求の形式が正しくないかのいずれかです。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 クライアントには、このメソッドを使用してアクセス トークンを要求する権限がありません。The client is not authorized to request an access token using this method. 拡張機能の呼び出しにローカル ループバックを使用しなかった要求や、Azure リソースのマネージド ID が正しく構成されていない VM が原因です。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. VM の構成についてサポートが必要な場合は、「Azure portal を使用して VM 上に Azure リソースのマネージド ID を構成する」を参照してください。See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.
access_deniedaccess_denied リソース所有者または承認サーバーによって、要求が拒否されました。The resource owner or authorization server denied the request.
unsupported_response_typeunsupported_response_type このメソッドを使用したアクセス トークンの取得は、承認サーバーによってサポートされていません。The authorization server does not support obtaining an access token using this method.
invalid_scopeinvalid_scope 要求されたスコープが無効、不明、または形式が正しくありません。The requested scope is invalid, unknown, or malformed.
500 内部サーバー エラー500 Internal server error unknownunknown Active Directory からのトークンの取得に失敗しました。Failed to retrieve token from the Active directory. 詳細については、 <file path> のログを参照してくださいFor details see logs in <file path> Azure リソースのマネージド ID が VM 上で有効なことを確認します。Verify that managed identities for Azure resources has been enabled on the VM. VM の構成についてサポートが必要な場合は、「Azure portal を使用して VM 上に Azure リソースのマネージド ID を構成する」を参照してください。See Configure managed identities for Azure resources on a VM using the Azure portal if you need assistance with VM configuration.

また、HTTP GET 要求の URI、特にクエリ文字列で指定されたリソース URI の形式が正しいかどうかを確認します。Also verify that your HTTP GET request URI is formatted correctly, particularly the resource URI specified in the query string. 例については、上記の「REST」セクションの「要求のサンプル」を参照してください。または、「Azure AD 認証をサポートしている Azure サービス」で、サービスの一覧と、そのリソース ID を参照してください。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.

再試行のガイダンスRetry guidance

404、429、または 5xx のエラー コードが表示される場合、再試行することをお勧めします (前の 「エラー処理」を参照)。It is recommended to retry if you receive a 404, 429, or 5xx error code (see Error handling above).

スロットル制限は、IMDS エンドポイントに対して行われる呼び出し回数に適用されます。Throttling limits apply to the number of calls made to the IMDS endpoint. スロットルのしきい値を超えた場合、IMDS エンドポイントは、スロットルが有効な状態にあっても、それ以降の要求を制限します。When the throttling threshold is exceeded, IMDS endpoint limits any further requests while the throttle is in effect. この期間中、IMDS エンドポイントは HTTP 状態コード 429 ("要求が多すぎます") を返し、要求は失敗します。During this period, the IMDS endpoint will return the HTTP status code 429 ("Too many requests"), and the requests fail.

再試行については、次の方法をお勧めします。For retry, we recommend the following strategy:

再試行戦略Retry strategy 設定Settings Values 動作のしくみHow it works
ExponentialBackoffExponentialBackoff 再試行回数Retry count
最小バックオフMin back-off
最大バックオフMax back-off
差分バックオフDelta back-off
最初の高速再試行First fast retry
55
0 秒0 sec
60 秒60 sec
2 秒2 sec
falsefalse
試行 1 - 0 秒の遅延Attempt 1 - delay 0 sec
試行 2 - 最大 2 秒の遅延Attempt 2 - delay ~2 sec
試行 3 - 最大 6 秒の遅延Attempt 3 - delay ~6 sec
試行 4 - 最大 14 秒の遅延Attempt 4 - delay ~14 sec
試行 5 - 最大 30 秒の遅延Attempt 5 - delay ~30 sec

Azure サービスのリソース IDResource IDs for Azure services

Azure AD をサポートするリソースで、Azure リソースのマネージド ID をテスト済みのリソースとそれぞれのリソース ID の一覧については、「Azure AD 認証をサポートしている Azure サービス」を参照してください。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.

次の手順Next steps