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

互動代理代表使用者執行行動。為了安全執行，代理必須驗證使用者身份、取得所需權限的同意，並取得下游 API 的存取權杖。本文將引導你了解如何為你的互動客服人員實施端到端流程：

為您的代理人身份藍圖註冊一個重定向 URI。
設定使用者或管理員授權（同意）。
驗證使用者並取得存取權杖。
驗證憑證並提取使用者聲明。
利用 On-Behalf-Of（OBO）流程取得下游 API 的憑證。

備註

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

先決條件

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

一個特工身份藍圖。記錄代理人識別藍圖應用程式 ID（用戶端 ID）。
一個代理人身份。
一個為你的代理身份設定的代理應用程式。
熟悉 OAuth 2.0 授權碼流程。

管理員授權還需要：

具有委派許可權的Application.ReadWrite.OwnedBy 存取權杖。了解委派權限與應用權限的差異。
需要管理員存取權來授予同意以獲得應用程式權限。

註冊一個重定向 URI

為了支援委派權限，您的代理身份藍圖必須設定有效的重定向 URI。這個 URI 是 Microsoft Entra ID 在用戶對你的代理人授權或拒絕後，將他們轉介給他們的位置。

Microsoft 圖形 API
Microsoft Graph PowerShell

要發送此請求，首先需取得具有委派權限的 AgentIdentityBlueprint.ReadWrite.All 存取權杖。

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

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

$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

當使用者打開此 URL 時，Microsoft Entra ID 會提示他們登入並同意 scope 參數中指定的權限。同意後，使用者會被重新導向到指定的重定向 URI。

同意網址中的關鍵參數包括：

client_id：代理人身份客戶端 ID（非代理人身份藍圖客戶端 ID）。
response_type：設為 none，這是因為此請求僅記錄同意。代幣取得使用 response_type=code 在單獨的請求中進行。
redirect_uri：必須完全符合你在前一步設定的配置。
scope：指定您需要的委派權限（例如， User.Read）。
state：可選參數，用於維持請求與回撥之間的狀態。

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

設定管理員授權

代理也可以向 Microsoft Entra ID 管理員申請授權，該管理員可以為其租戶內的所有使用者授權代理。應用程式權限需要管理員授權，因為個別使用者無法同意。

要授予管理員同意，請建立提示管理員的授權網址。請在以下請求中使用代理身份識別碼。

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

管理員授權後，權限會套用整個租戶，租戶內的使用者不需要個別同意這些權限。

驗證使用者並請求憑證

授權設定完成後，用戶端應用程式（如前端或行動應用程式）會發起 OAuth 2.0 授權碼請求，以取得一個令牌，其中受眾為代理人身份藍圖。在此步驟中，client_id 指的是客戶端應用程式自身註冊的應用程式 ID，而非代理身份或代理身份藍圖 ID。

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

GET https://login.microsoftonline.com/<my-test-tenant>/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/<my-test-tenant>/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。

驗證存取權杖

代理通常透過 Web API 進行對外暴露，並必須驗證存取權杖。執行代幣驗證時，務必使用核准的函式庫。千萬不要自己實作代幣驗證程式碼。

安裝 Microsoft.Identity.Web NuGet 套件：

dotnet add package Microsoft.Identity.Web

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

// Program.cs
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": "<my-test-tenant>",
    "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）流程允許代理人：

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

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。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-09