自律エージェントのトークンを認証して取得する

自律エージェントは、ユーザーの代理人として機能するのではなく、独自の ID を使用して操作を実行します。安全に動作するには、自律エージェントがMicrosoft Entra IDで認証し、アクセストークンを取得し、適切なアクセス許可を付与する必要があります。この記事では、エンドツーエンドのフローについて説明します。

クライアント資格情報を構成します。
エージェント ID ブループリントのトークンを要求します。
エージェント ID トークンを要求します。
アプリケーションのアクセス許可を付与する (管理者の同意)。
(省略可能)ユーザー ID を必要とするリソースに対して、エージェントのユーザーアカウントとして作成および認証します。

注

この記事では、独自の ID で動作する自律エージェントについて説明します。エージェントがサインインしているユーザーの代わりに動作する必要がある場合は、「ユーザーの認証と対話型エージェントのトークンの取得」を参照してください。

前提条件

エージェントトークン認証を実装する前に、次のことを確認してください。

エージェント ID ブループリント。
エージェント ID。エージェントアイデンティティクライアントIDが必要です。
Microsoft Entra エージェント ID における OAuth プロトコルの理解。

管理者の承認には、次のものが必要です。

Microsoft Entra ID テナントにおけるユーザーの管理者権限。
エージェントに必要な特定のアクセス許可を理解する。

エージェントのユーザーアカウント認証には、次のものが必要です。

Microsoft Entra エージェント IDにおけるエージェントのユーザーアカウントに関する理解。

クライアント資格情報を構成する

クライアント資格情報の詳細を取得します。これは、クライアントシークレット、証明書、またはフェデレート ID 資格情報として使用している管理された ID かもしれません。

Warnung

セキュリティリスクのために、エージェント ID ブループリントの運用環境では、クライアントシークレットをクライアント資格情報として使用しないでください。代わりに、マネージド ID またはクライアント証明書を使用するフェデレーション ID 資格情報 (FIC) などのより安全な認証方法を使用してください。これらの方法により、アプリケーション構成内に機密性の高いシークレットを直接格納する必要がなくなり、セキュリティが強化されます。

Microsoft Graph API
Microsoft。Identity.Web

エージェントアイデンティティブループリントで構成したクレデンシャルを集めます。次のいずれかが必要です。

管理 ID (推奨): マネージド ID クライアント ID と、Azure インスタンスメタデータサービス (IMDS) からのトークン。
証明書: 証明書の拇印または PFX ファイル。
クライアントシークレット (開発のみ): シークレット値。

運用環境では、マネージド ID をフェデレーション ID 資格情報として使用します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

ローカル開発とテストの場合のみ、代わりにクライアントシークレットを使用できます。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

エージェント ID ブループリントのトークンを要求する

エージェント ID ブループリントのトークンを要求する場合は、 fmi_path (フェデレーションマネージド ID パス) パラメーターにエージェント ID のクライアント ID を指定します。このパラメーターはMicrosoft Entra IDブループリントがどのエージェント ID に代わって動作するかを示します。

ローカル開発中にクライアントシークレットを使用する場合は、 client_secret パラメーターを指定します。証明書とマネージド ID の場合は、代わりに client_assertion と client_assertion_type を使用します。

Microsoft Graph API
Microsoft。Identity.Web

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Microsoft。Identity.Web、エージェント ID ブループリントのトークンを明示的に要求する必要はありません。 Microsoft。Identity.Web が自動的に実行します。

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

エージェント ID ブループリントトークン (T1) を取得したら、それを使用してエージェント ID トークンを要求します。

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Microsoft。Identity.Web は、アプリケーションの初期化時にサービスコレクションで新しい services.AddAgentIdentities()を使用する場合に、トークン取得プロトコルの詳細を処理します。

アプリケーションを初期化します。

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

アクセストークンを要求するには、 .WithAgentIdentity() パターンを使用します。

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

アプリケーションのアクセス許可を付与する

エージェントは、多くの場合、Microsoft Entra ID アプリケーションのアクセス許可 (アプリロールとして表されます) を必要とするMicrosoft Graphやその他の Web サービスでアクションを実行する必要があります。自律エージェントは、Microsoft Entra ID管理者にこれらのアクセス許可を要求する必要があります。

自律エージェントにアプリケーションのアクセス許可を付与するには、次の 2 つの方法があります。

管理者は、Microsoft Graph API または PowerShell を使用して、appRoleAssignment を作成できます。
エージェントは、管理者の同意 URL を使用して、管理者を同意ページに誘導できます。

API を使用してアプリロールの割り当てを作成する

アプリロールの割り当てを取得するには、次の手順を使用します。

アプリケーションのアクセス許可とApplication.Read.Allを使用してAppRoleAssignment.ReadWrite.Allします。
アクセスしようとしているリソースサービスプリンシパルのオブジェクト ID を取得します。たとえば、Microsoft Graph サービスプリンシパルオブジェクト ID を検索するには、次のようにします。
1. Microsoft Entra 管理センターに移動します。
2. Entra ID -->Enterprise Applications に移動します
3. アプリケーションの種類が Microsoft アプリケーションのときにフィルターをかける
4. Microsoft Graph を検索します。
割り当てるアプリロールの一意の ID を取得します。

アプリロールの割り当てを作成します。

Microsoft Graph API
Microsoft Graph PowerShell

POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Authorization: Bearer <token>
Content-Type: application/json

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<microsoft-graph-sp-object-id>",
  "appRoleId": "<app-role-id>"
}

Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph (well-known app ID)
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get your application's service principal (replace with your app's client ID)
$agentId = "<agent-identity-id>"

# Find the App Role ID for "User.ReadBasic.All"
$userReadBasicRole = $graphSp.AppRoles | Where-Object {
    $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
}

# Assign the app role
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
    -PrincipalId $agentId `
    -ResourceId $graphSp.Id `
    -AppRoleId $userReadBasicRole.Id

テナント管理者に承認を要求する

委任されたアクセス許可を付与するには、管理者に確認を求めるために使用する承認 URL を作成します。ロールパラメーターは、要求されたアプリケーションのアクセス許可を指定するために使用されます。

次の要求では、必ずエージェント ID クライアント ID を使用してください。

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

エージェントの実装では、チャットウィンドウで管理者に送信されたメッセージに含めるなど、さまざまな方法で管理者をこの URL にリダイレクトする場合があります。管理者がこの URL にリダイレクトされると、サインインし、スコープパラメーターで指定されたアクセス許可に同意するように求められます。現時点では、一覧表示されているリダイレクト URI を使用する必要があります。この URI を使用すると、管理者は同意を与えてから空白のページに移動します。

アプリケーションに必要なアクセス許可を付与したら、アクセス許可を有効にするために新しいエージェントアクセストークンを要求します。

エージェントのユーザーアカウントとして認証する

自律エージェントは、アプリ専用トークンを使用して操作するだけでなく、エージェントのユーザーアカウントとして認証できます。エージェントのユーザーアカウントは、エージェントで使用するために専用に構築Microsoft Entra特殊な種類のユーザーアカウントです。最も一般的に使用されるのは、メールボックス、Teams チャネル、その他のユーザー固有のリソースなど、ユーザーアカウントの存在を必要とするシステムにエージェントが接続する必要がある場合です。

各エージェント ID に関連付けられるエージェントのユーザーアカウントは 1 つだけであり、各エージェントのユーザーアカウントは 1 つのエージェント ID にのみ関連付けることができます。

エージェントのユーザーアカウントを作成するための承認を取得する

エージェントのユーザーアカウントを作成するには、エージェント ID ブループリントに、テナント内の AgentIdUser.ReadWrite.IdentityParentedBy アプリケーションのアクセス許可を付与する必要があります。承認は、次の 2 つの方法のいずれかで取得できます。

エージェントの承認を要求します。エージェント ID ではなく、エージェント ID ブループリントをclient_idとして必ず使用してください。
テナントで appRoleAssignment を手動で作成します。エージェント ID ブループリントのサービスプリンシパルオブジェクト ID を、アプリケーション (クライアント) ID ではなく、 principalId 値として使用します。

エージェント ID ブループリントではなく別のクライアントを使用してエージェントのユーザーアカウントを作成する場合、そのクライアントは代わりに委任された AgentIdUser.ReadWrite.All またはアプリケーションのアクセス許可を取得する必要があります。

エージェントのユーザーアカウントを作成する

エージェント ID ブループリントまたはその他の承認済みクライアントを使用して、エージェントのユーザーアカウントを作成します。エージェントのユーザーアカウントを作成する推奨される方法は、エージェント ID ブループリントを使用することです。エージェントのユーザーアカウントを作成するには、アクセストークンが必要です。

レスト
Microsoft。Identity.Web

必要なアクセス許可を持つアクセストークンを取得したら、次の要求を行います。

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "agentuserupn@tenant.onmicrosoft.com",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Microsoft.Identity.Web を使用してエージェントのユーザーアカウントを作成するには、次の手順に従います。

構成ファイルに次のコードを追加します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<my-agent-blueprint-id>",
    "Scopes": "access_agent",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
      }
    ]
  },

  "DownstreamApis": {
    "agent-identity": {
      "BaseUrl": "https://graph.microsoft.com",
      "RelativePath": "/v1.0/users",
      "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
      "RequestAppToken": true
    }
  }
}

必要なパッケージを追加する

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

サービスを構成します。

using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

エージェントのユーザーアカウント作成エンドポイントを作成します。

app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
{
    try
    {
        // Get the service to call the downstream API (preconfigured in the appsettings.json file)
        IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();

        var requestBody = new AgentIdUser
        {
            displayName = "my-agent-name",
            mailNickname = "my-agent-alias",
            userPrincipalName = "my-agent-email-address",
            accountEnabled = true,
            identityParentId = "<associated-agent-identity-id>"
        };

        // Call the downstream API (Graph) with a POST request to create an agent's user account
        var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
            "agent-identity",
            requestBody
        );

        return Results.Json(jsonResult);
    }
    catch (Exception ex)
    {
        return ex.Message;
    }
})

エージェントのユーザーアカウントを作成したら、他に何も構成する必要はありません。これらのアカウントには資格情報がないため、次のセクションで説明するプロトコルを使用してのみ認証できます。

エージェントのユーザーアカウントは、他のユーザーアカウントと同様に動作します。エージェントのユーザーアカウントを使用してトークンを要求するには、エージェント ID がエージェントの代わりに動作することを承認する必要があります。エージェント ID は、admin authorization を使用して承認するか、Microsoft Graph または Microsoft Graph PowerShell を使用して oAuth2PermissionGrant を手動で作成できます。

Microsoft Graphの場合、要求は次のスニペットに示されています。

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientId": "{agent-identity-id}",
  "consentType": "Principal",
  "principalId": "{agent-id-user-object-id}",
  "resourceId": "{ms-graph-service-principal-object-id}",
  "scope": "Mail.Read"
}

Microsoft Graph PowerShell の場合は、次のスクリプトを使用します。

Connect-MgGraph -Scopes "DelegatedPermissionGrant.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get the service principal for your client app
$clientSp = Get-MgServicePrincipal -Filter "appId eq '{agent-identity-id}'"

# Create the delegated permission grant
New-MgOauth2PermissionGrant -BodyParameter @{
    clientId    = $clientSp.Id
    consentType = "Principal"
    principalId = "{agent-id-user-object-id}"
    resourceId  = $graphSp.Id
    scope       = "Mail.Read"
}

エージェントのユーザーアカウントトークンを要求する

エージェントのユーザーアカウントを認証するには、次の 3 つの手順に従う必要があります。

エージェント ID ブループリントとしてトークンを取得します。
そのトークンを使用して、エージェント ID として別のトークンを取得します。
エージェントのユーザーアカウントとして別のトークンを取得するには、前の両方のトークンを使用します。

レスト
Microsoft。Identity.Web

最初に、「エージェント ID ブループリントのトークンを要求する」の説明に従って、エージェント ID ブループリントとしてトークンを要求します。エージェントアプリトークンを取得したら、それを使用して、エージェント ID のフェデレーション ID 資格情報 (FIC) を要求します。

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

これにより、エージェント ID の交換トークン (T2) が返されます。次の要求でそれを使用して、エージェントのユーザーアカウントの委任されたトークンを取得します。

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

これにより、エージェントのユーザーアカウントとしてMicrosoft Graphを呼び出すために使用できる委任されたアクセストークンが提供されます。ユーザー識別子にuser_id=<user-object-id>する代わりに、username=<UPN>を使用できます。

Microsoft。Identity.Web はトークンの取得を自動的に処理します。アクセストークンを要求するには、 .WithAgentUserIdentity() パターンを使用します。

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

    // Create a ClaimsPrincipal to enable token caching
    ClaimsPrincipal user = new ClaimsPrincipal();

    // Acquire a user token
    string authHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            scopes: ["https://graph.microsoft.com/.default"],
            options: options,
            user: user);

    return Results.Ok(authHeader);
});

オブジェクト ID の代わりに、エージェントのユーザーアカウントプリンシパル名を使用することもできます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-09

自律エージェントのトークンを認証して取得する

前提条件

クライアント資格情報を構成する

エージェント ID ブループリントのトークンを要求する

エージェント ID トークンを要求する

アプリケーションのアクセス許可を付与する

API を使用してアプリ ロールの割り当てを作成する

テナント管理者に承認を要求する

エージェントのユーザー アカウントとして認証する

エージェントのユーザー アカウントを作成するための承認を取得する

エージェントのユーザー アカウントを作成する

エージェント ID に同意を付与する

エージェントのユーザー アカウント トークンを要求する

関連するコンテンツ