驗證使用者並取得互動代理的代幣

互動代理代表使用者執行行動。為了安全代表使用者行動，代理會驗證使用者、取得所需權限的同意，並取得下游 API 的存取權杖。本文將帶您了解互動代理人的端對端認證與憑證取得流程：

透過可繼承權限或同意授予權限。
驗證使用者並取得存取權杖。
驗證憑證並提取使用者聲明。
利用 On-Behalf-Of（OBO）流程取得下游 API 的憑證。

備註

本文介紹了代表登入 用戶使用 OBO 流程的互動代理程式。如果你的代理需要自己的類使用者身份（數位工作者情境），請參閱代理的使用者帳戶和代理的使用者帳戶 OAuth 流程。

先決條件

在開始之前，請確保您擁有：

一個特工身份藍圖。記錄代理人識別藍圖應用程式 ID（用戶端 ID）。
一個代理人身份。
一個在 Microsoft Entra 註冊的客戶端應用程式，負責使用者驗證。
熟悉 OAuth 2.0 授權碼流程。
如果您打算使用本文中的權杖驗證和 OBO 範例，則需要具備執行 ASP.NET Core Web API 的能力。

管理員授權還需要：

需要管理員存取權來授予同意以獲得應用程式權限。

在代理代表使用者行動之前，使用者或管理員必須同意所需的權限。授權有兩種方式：

可繼承權限：預先授權藍圖權限，讓代理身份自動繼承。
請求同意：註冊一個重定向 URI，並提示使用者或管理員透過 OAuth 請求或使用管理員同意端點授予同意。

使用可繼承權限

在代理身份藍圖上設定可繼承權限，預先授權一組委派範圍與應用程式角色。從藍圖建立的代理身份會自動繼承這些權限，無需互動式同意提示。更多資訊請參閱「設定代理身份藍圖的可繼承權限」。

若要透過 OAuth 流程請求同意，您的代理身份藍圖必須先設定重定向 URI。對於藍圖，重定向 URI 必須是 網頁應用程式 類型。與應用程式註冊時的重定向 URI 不同，藍圖上的重定向 URI 無法用來取得委派的權限令牌。 OAuth2 請求中只支援 ONLY response_type=none ，這表示請求只記錄同意，且不會回傳任何標記。

要更新代理身份藍圖上的重定向 URI，首先需要取得帶有委派權限 AgentIdentityBlueprint.ReadWrite.All的存取權杖。接著向應用程式物件發送 PATCH 請求，以取得代理身份藍圖：

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

使用 Microsoft Graph PowerShell 更新代理程式身分識別藍圖，使其包含重新導向 URI。

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-tenant-id>

$applicationId = "<agent-blueprint-id>"
$web = @{
    redirectUris= @(
        "https://myagentapp.com/authorize"
    )
}

$body = @{
    web   =  $web
}

Invoke-MgGraphRequest -Method PATCH `
        -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

在代理人代表使用者行動之前，使用者必須同意所需的權限。使用者同意請求不會回傳代幣。相反地，它會記錄使用者已授予代理程式代表其行事的權限。憑證取得是在驗證使用者並請求代幣時進行的。

這很重要

參數中應使用 代理身份 客戶端 ID client_id ，而非代理身份藍圖 ID。

要提示使用者同意，請建構一個授權網址並重新導向該網址。客服人員可以用不同方式呈現這個網址，例如在聊天訊息中作為連結。

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

當使用者打開此網址時，Microsoft Entra ID 會提示他們登入並授權。同意後，使用者會被送回重定向 URI。

使用者同意授權網址中的關鍵參數包括：

client_id：代理人身份客戶端 ID（非代理人身份藍圖客戶端 ID）。
response_type：設為 none，這是因為此請求僅記錄同意。憑證取得的用途 response_type=code 是：認證使用者並請求憑證。
redirect_uri：必須完全符合代理身份藍圖中設定的重定向 URI。
scope：指定您需要的委派權限（例如， User.Read）。
state：可選參數，用於維持請求與回撥之間的狀態。

欲了解更多OAuth授權概念，請參閱Microsoft 身分識別平台中的許可與同意。

代理也可以向 Microsoft Entra ID 系統管理員要求授權，而該管理員可代表其租用戶中的所有使用者，對該代理授與同意。根據租戶中設定的同意設定，可能需要管理員同意。

要授予租戶管理員同意，請引導管理員至以下網址。在參數中使用代理身份 ID client_id 。

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

管理員同意後，權限會適用於整個租戶。使用者不需要再同意。

備註

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

驗證使用者並請求憑證

同意後，客戶端應用程式（如前端或行動應用程式）會發起 OAuth 2.0 授權碼請求，以取得目標受眾為代理人身份藍圖的令牌。在此步驟中，client_id 是指用戶端應用程式本身註冊的應用程式 ID，而不是代理身分或代理身分藍圖。

備註

此要求中的 redirect_uri 屬於用戶端應用程式的註冊設定，而非在先前同意步驟中設定的藍圖重新導向 URI。

利用以下參數將使用者重新導向至 Microsoft Entra ID 授權端點：

GET https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

使用者登入後，你的應用程式會在重定向 URI 收到一個授權碼。將授權碼兌換為存取權杖：

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

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>

只有在使用機密客戶端時才應包含該 client_secret 參數。

JSON 回應包含一個存取權杖，可用來存取代理的 API。

驗證存取權杖

網路 API 必須先驗證進入的存取權杖，代理人才能行動。務必使用核准的函式庫來驗證憑證。不要自行撰寫權杖驗證程式碼。

安裝 Microsoft.Identity.Web NuGet 套件：

dotnet add package Microsoft.Identity.Web

在您的 ASP.NET Core 網頁 API 專案中，實作 Microsoft Entra ID 認證：

// Program.cs
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

在檔案中設定認證憑證 appsettings.json ：

警告

由於安全風險，客戶端秘密不應在生產環境中作為代理身份藍圖的客戶端憑證使用。相反地，應使用更安全的認證方法，例如聯邦身份憑證（FIC）搭配管理身份或用戶端憑證。這些方法透過消除直接在應用程式配置中儲存敏感秘密的需求，提升安全性。
```
"AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-id>",
    "Audience": "<agent-blueprint-id>",
    "ClientCredentials": [
        {
            "SourceType": "ClientSecret",
            "ClientSecret": "your-client-secret"
        }
    ]
}
```

欲了解更多關於 Microsoft 的資訊。Identity.Web，請參見 Microsoft。Identity.Web 文件。

驗證使用者的主張

存取權杖驗證後，代理程式可識別使用者並執行授權檢查。以下範例 API 路由從存取權杖中擷取使用者權利要求，並在 API 回應中回傳：

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

取得下游 API 的憑證

互動代理驗證使用者的憑證後，可以請求存取憑證以代表使用者呼叫下游 API。 On-Behalf-Of（OBO）流程允許代理人：

從客戶端接收存取權杖。
將其兌換成新的存取權杖，用於 Microsoft Graph 等下游 API。
使用這個新憑證代表原始使用者存取受保護的資源。

使用 Microsoft 身份網路
使用 Microsoft Graph SDK

Microsoft.Identity.Web 函式庫透過自動處理令牌交換簡化了 OBO 實作，因此你不必依照協定手動實作流程。

安裝所需的 NuGet 套件：

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

在您的 ASP.NET Core 網頁 API 專案中，更新 Microsoft Entra ID 認證實作：

// 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)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

在代理 API 中，將接收到的使用者存取權杖換成代理身份的新存取權杖。 Microsoft.Identity.Web 驗證進入的存取權杖並處理代表權杖交換：

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

如果你用的是 Microsoft Graph SDK，可以用 GraphServiceClient 來認證給 Microsoft Graph。

安裝所需的 NuGet 套件：

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

在您的 ASP.NET Core 網頁 API 專案中，設定認證並新增對 Microsoft Graph 的支援：

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

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

從服務提供者取得 GraphServiceClient，並用代理身份呼叫Microsoft Graph API：

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";

    GraphServiceClient graphServiceClient = httpContext.RequestServices.GetService<GraphServiceClient>()!;
    var me = await graphServiceClient.Me.GetAsync(r => r.Options.WithAuthenticationOptions(
        o =>
        {
            o.WithAgentIdentity(agentIdentity);
        }));
    return me.UserPrincipalName;
})
.RequireAuthorization();

在底層，OBO 流程包含兩種代幣交換：首先，代理身份藍圖利用其客戶端憑證取得交換令牌，接著代理身份將該令牌與使用者的存取權杖交換為下游 API 令牌。完整協定攻略，包括 HTTP 請求格式與權杖驗證細節，請參閱代理中的 On-behalf-of flow。

了解更多關於代理令牌及相關 API：

意見反應

此頁面對您有幫助嗎？

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

驗證使用者並取得互動代理的代幣

先決條件

許可與同意

使用可繼承權限

請求同意

註冊一個重定向 URI

請求使用者同意

請求所有使用者的管理員同意

驗證使用者並請求憑證

驗證存取權杖

驗證使用者的主張

取得下游 API 的憑證

相關內容

意見反應

其他資源