為自主代理驗證並取得代幣

自主代理以自身身份執行操作，而非作為使用者的代理人。為了安全運作，自主代理必須使用 Microsoft Entra ID 進行認證，取得存取權杖，並獲得適當的權限。本文將帶你了解整個流程：

設定客戶端憑證。
申請代理身份藍圖的令牌。
請求一個代理身份憑證。
授予應用程式權限（管理員同意）。
（可選）建立代理使用者帳號並驗證，以用於需要使用者身份的資源。

備註

本文介紹了以自身身份運作的自主代理人。如果你的代理人需要代表已登入的使用者行動，請參見「認證使用者並取得互動代理人的代幣」。

先決條件

在實施代理令牌認證前，請確保你具備：

一個特工身份藍圖。
一個代理人身份。你需要代理身份和客戶 ID。
理解 Microsoft Entra Agent ID 中的 OAuth 協議。

管理員授權還需要：

您的 Microsoft Entra ID 租戶的管理員權限。
了解你的代理人所需的具體權限。

對於客服人員的使用者帳號驗證，你還需要：

了解 Microsoft Entra Agent ID 中代理的使用者帳號。

設定您的客戶端憑證

取得你的客戶憑證資料。這可能是你的客戶端秘密、憑證，或是你用作聯邦身份憑證的管理身份。

警告

由於安全風險，客戶端秘密不應在生產環境中作為代理身份藍圖的客戶端憑證使用。相反地，應使用更安全的認證方法，例如聯邦身份憑證（FIC）搭配管理身份或用戶端憑證。這些方法透過消除直接在應用程式配置中儲存敏感秘密的需求，提升安全性。

Microsoft 圖形 API
Microsoft。Identity.Web

收集你在代理身份藍圖上設定的憑證。你需要以下其中一項：

管理身份（建議）：管理身份客戶端 ID 及 Azure 實例元資料服務（IMDS）的憑證。
憑證：憑證指紋或 PFX 檔案。
用戶端秘密 （僅限開發）：秘密值。

設定 Microsoft。Identity.Web 用來驗證你的代理身份藍圖，使用聯邦身份憑證。在生產環境中，使用受管理身份作為聯邦身份憑證：

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

僅在本地開發與測試時，你可以使用用戶端密鑰。

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

請求代理身份藍圖的令牌

在請求代理身份藍圖的權杖時，請在 Federated Managed Identity 路徑參數中提供代理身份的用戶端 IDfmi_path。此參數告訴 Microsoft Entra ID 藍圖是以哪個代理身份的名義行事。

在本地開發中使用用戶端秘密時，請提供參數 client_secret 。對於憑證和管理身份，請使用 client_assertion 和 client_assertion_type 代替。

Microsoft 圖形 API
Microsoft。Identity.Web

請使用下列令牌請求來取得代理程式身分藍圖的令牌：

POST https://login.microsoftonline.com/<your-tenant-id>/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，你不需要明確請求應用程式身份藍圖的權杖。 Microsoft。Identity.Web 幫你做到了。

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

一旦你拿到代理身份藍圖標記（T1），就用它來請求代理身份標記。

POST https://login.microsoftonline.com/<your-tenant-id>/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 Graph 及其他網路服務中執行需要 Microsoft Entra ID 應用程式權限（以應用程式角色表示）的操作。自主代理需要向 Microsoft Entra ID 管理員申請這些權限。

授予自主代理應用程式權限有兩種方式：

管理員可以透過使用 Microsoft Graph API 或 PowerShell 建立 appRoleAssignment。
代理程式可以使用管理員同意網址將管理員導向同意頁面。

透過 API 建立應用程式角色指派

請依照以下步驟取得應用程式角色分配。

請求一個包含應用程式權限和Application.Read.All的AppRoleAssignment.ReadWrite.All。
取得你想存取的資源服務主體的物件 ID。例如，要找到 Microsoft Graph 服務主體物件 ID：
1. 前往Microsoft Entra 管理中心。
2. 請前往 Entra ID -->Enterprise Applications
3. 依應用程式類型篩選 == Microsoft 應用程式
4. 搜尋 Microsoft Graph。
從 Microsoft Graph 權限參考中取得你想指派的應用程式角色的唯一 ID。

建立應用程式角色分配：

Microsoft 圖形 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-tenant-id>

# 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

向租戶管理員申請授權

要授予應用程式權限，請建構用於提示管理員的授權網址。角色參數用於指定所請求的應用程式權限。

請務必在以下請求中使用代理人身份客戶 ID。

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

代理程式的實作可能會以各種方式將管理員重新導向到這個網址，例如在聊天視窗中發送給管理員的訊息中包含它。當管理員被重新導向到這個 URL，他們會被要求登入並同意範圍參數中指定的權限。目前你必須使用列出的重定向 URI，該 URI 在授權後會引導管理員到空白頁面。

備註

在你的藍圖上設定一個重定向 URI，並在同意請求中加入 state 參數。當同意獲得後，使用者會被導向重定向 URI，您可以在那裡顯示確認。你的端點可以用這個 state 參數來追蹤權限是否被授予。對於單一租戶代理，你可以選擇重試令牌請求，直到同意，因為租戶 ID 已經被確認。

在為您的代理程式身分藍圖授與所需權限後，請求新的代理程式存取權杖，讓這些權限生效。

透過代理人使用者帳號進行驗證

除了只使用應用程式代幣外，自主代理還可以用代理的使用者帳號進行驗證。代理的使用者帳號是 Microsoft Entra 中專為代理設計的特殊使用者帳號類型。當客服人員需要連接到需要使用者帳號存在的系統時，例如信箱、Teams 頻道或其他使用者專屬資源，這些工具最常被使用。

每個代理身份只能擁有一個關聯的代理的使用者帳號，且每個代理的使用者帳號只能與單一代理身份綁定。

取得建立客服使用者帳號的授權

要建立代理的使用者帳號，你的代理身份藍圖必須在租戶中獲得應用程式權限 AgentIdUser.ReadWrite.IdentityParentedBy 。您可以透過以下兩種方式之一取得授權：

請向租戶管理員申請授權。務必使用你的代理人身份藍圖作為 client_id，而非代理人身份。
透過租戶中的 API 建立應用程式角色指派。使用代理身份藍圖的服務主體物件 ID 作為 principalId 的值，而非其應用程式（用戶端）ID。

如果你想使用與代理身份藍圖不同的其他客戶端來建立代理的使用者帳號，那麼該客戶端必須取得 AgentIdUser.ReadWrite.All 的委派權限或應用程式權限。

建立客服人員的使用者帳號

使用你的代理人身份藍圖或其他核准客戶建立代理人的用戶帳號。建立客服人員使用者帳號的建議方法是使用您的客服身份藍圖。你需要用代理身份藍圖取得存取權杖來建立代理的使用者帳號。

休息
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": "<your-tenant-id>",
    "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;
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;
    }
})

一旦你建立了代理的使用者帳號，就不需要再設定其他東西。這些帳號沒有任何憑證，只能使用以下章節所述的協議進行驗證。

客服人員的使用者帳號行為和其他使用者帳號一樣。在你能用代理人的使用者帳號請求代幣之前，你需要授權代理人身份代表它行事。你可以向租戶管理員申請授權來授權代理身份，或手動使用 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-tenant-id>

# 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"
}

取得代理的使用者帳戶令牌

要驗證客服人員的使用者帳號，您需要遵循三個步驟：

取得一個令牌作為代理身份藍圖。
使用該代幣取得另一個代幣作為代理身份認證。
用之前兩個代幣來取得另一個代幣作為代理人的用戶帳號。

休息
Microsoft。Identity.Web

首先，請以代理人身份藍圖請求一個令牌，詳見「請求代理人身份藍圖的令牌」一文。一旦你擁有代理身份藍圖令牌，使用該代理身份藍圖令牌申請你的代理身份的聯邦身份憑證（FIC）：

POST https://login.microsoftonline.com/<your-tenant-id>/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>

此時會回傳一個代理身份的交換標記（T2）。在下一個請求中使用它來取得代理人使用者帳號的委派令牌：

POST https://login.microsoftonline.com/<your-tenant-id>/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。

代理身份存取權杖的主張
請致電Microsoft 圖形 API
呼叫自訂 API
請致電Azure服務
使用 Microsoft Entra ID Auth SDK (Sidecar) 取得權杖
Microsoft Graph 權限參考資料
Microsoft 身分識別平台中的許可權和同意
代理的使用者帳號流程
代理人的使用者帳號

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-06-16