デーモンアプリケーションを使用して Web API を呼び出すためのトークンを取得する

[アーティクル]
04/09/2024

機密クライアントアプリケーションを構築したら、AcquireTokenForClient を呼び出し、スコープを渡し、必要に応じてトークンを強制的に更新することでアプリのトークンを取得できます。

要求するスコープ

クライアントの資格情報フローのために要求するスコープは、後に /.default が続くリソースの名前です。この表記は、アプリケーションの登録時に静的に宣言された "アプリケーションレベルの権限" を使用するように Microsoft Entra ID に指示します。また、これらの API アクセス許可は、テナント管理者によって付与される必要があります。

appsettings.json ファイルの構成の一部として Web API のスコープを定義する例を次に示します。この例は、GitHub の .NET コンソールデーモンのコードサンプルから引用しています。

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

MSAL Python では、構成ファイルは次のコードスニペットのようになります。

{
    "scope": ["https://graph.microsoft.com/.default"],
}

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};

Azure AD (v1.0) リソース

クライアント資格情報に使用するスコープは、常に、リソース ID の後に /.default が続くものにする必要があります。

重要

MSAL がバージョン 1.0 のアクセストークンを受け入れるリソースのためのアクセストークンを要求すると、Microsoft Entra ID では、最後のスラッシュの前のすべてを取得してそれをリソース ID として使って、要求されたスコープから目的の対象ユーザーの解析が行われます。したがって、Azure SQL Database () のように、 https://database.windows.net リソースは、末尾がスラッシュ (Azure SQL Database の場合) であることを想定している場合は、 https://database.windows.net/ のスコープを要求する必要があり https://database.windows.net//.default ます。 (二重スラッシュに注意してください)。「MSAL.NET issue #747: Resource url's trailing slash is omitted, which caused sql auth failure」も参照してください。

AcquireTokenForClient API

アプリのトークンを取得するには、プラットフォームに応じて AcquireTokenForClient またはそれと同等のものを使用します。

Microsoft.Identity.Web を使用すれば、トークンを取得する必要はありません。デーモンアプリケーションからの Web API の呼び出しに関するページに示されているように、上位の API を使用できます。ただし、トークンを必要とする SDK を使用している場合は、このトークンを取得する方法を次のコードスニペットに示します。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

このコードは、MSAL Java dev サンプルから抽出したものです。

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

次のコードスニペットは、MSAL Node の機密クライアントアプリケーションでトークンを取得する方法を示しています。

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient によるアプリケーショントークンキャッシュの使用

MSAL.NET では、AcquireTokenForClient によってアプリケーショントークンキャッシュが使用されます (他のすべての AcquireTokenXX メソッドでは、ユーザートークンキャッシュが使用されます)。AcquireTokenSilent は "ユーザー" トークンキャッシュを使用するため、AcquireTokenForClient を呼び出す前に AcquireTokenSilent を呼び出さないでください。 AcquireTokenForClient はアプリケーション トークンキャッシュそのものをチェックして、更新します。

Protocol

選択した言語のライブラリがまだない場合は、プロトコルを直接使用することもできます。

最初のケース:共有シークレットを使用してトークン要求にアクセスする

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

2 番目のケース:証明書を使用してトークン要求にアクセスする

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

詳細については、プロトコルのドキュメント:Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フロー。

トラブルシューティング

リソース/.default スコープを使用しましたか?

無効なスコープを使用したことを示すエラーメッセージが表示された場合は、resource/.default スコープを使用しなかった可能性があります。

API を呼び出すときに、この操作を完了するのに十分な特権がありませんというエラーが表示された場合は、テナント管理者がアプリケーションにアクセス許可を付与する必要があります。

アプリケーションに管理者の同意を付与しない場合、次のエラーが発生します。

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

ロールに応じて、次のオプションのいずれかを選択します。

グローバルテナント管理者

グローバルテナント管理者の場合は、Microsoft Entra 管理センターでエンタープライズアプリケーションにアクセスします。アプリの登録を選択し、左ペインの [セキュリティ] セクションで [アクセス許可] を選択します。次に、[{テナント名} に管理者の同意を与えます] というラベルの付いた大きいボタンを選択します ({テナント名} はディレクトリの名前です)。

標準ユーザー

テナントの標準ユーザーの場合は、アプリケーションに管理者の同意を与えるよう全体管理者に依頼してください。これを行うには、次の URL を管理者に知らせます。

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

URL で以下を行ないます。

Enter_the_Tenant_Id_Here をテナント ID またはテナント名 (contoso.microsoft.com など) に置き換えます。
Enter_the_Application_Id_Here は、登録済みアプリケーションのアプリケーション (クライアント) ID です。

上記の URL を使用してアプリに同意を与えると、エラー AADSTS50011: No reply address is registered for the application が表示されることがあります。このエラーが発生するのは、アプリケーションと URL にリダイレクト URI がないためです。このメッセージは無視できます。

独自の API を呼び出している場合

デーモンアプリで独自の Web API を呼び出すとき、デーモンのアプリ登録にアプリのアクセス許可を追加できなかった場合、Web API のアプリ登録にアプリロールを追加する必要があります。

次のステップ

このシナリオの次の記事である Web API の呼び出しに関する記事に進みます。

デーモン アプリケーションを使用して Web API を呼び出すためのトークンを取得する