エンドポイント リファレンス: Microsoft Entra SDK for AgentID HTTP API

このドキュメントでは、Microsoft Entra SDK for AgentID によって公開される HTTP エンドポイントの完全なリファレンスを提供します。

API 仕様

OpenAPI 仕様: /openapi/v1.json (開発環境) およびリポジトリで使用できます。 https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.Sidecar/OpenAPI/Microsoft.Identity.Web.AgentID.json

これは次の目的で使用されます。

• クライアント コードを生成する
• 要求を検証する
• 使用可能なエンドポイントを検出する

エンドポイントの概要

Authentication

明示的に認証されていないとマークされていない限り、すべてのトークン取得および検証エンドポイントでは、 Authorization ヘッダーにベアラー トークンが必要です。

GET /AuthorizationHeader/Graph
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

トークンは、構成された Microsoft Entra ID 設定 (テナント、対象ユーザー、発行者、有効な場合はスコープ) に対して検証されます。

/Validate

受信ベアラー トークンを検証し、その要求を返します。

リクエスト

GET /Validate HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

成功した応答 (200)

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "claims": {
    "aud": "api://your-api-id",
    "iss": "https://sts.windows.net/tenant-id/",
    "iat": 1234567890,
    "nbf": 1234567890,
    "exp": 1234571490,
    "acr": "1",
    "appid": "client-id",
    "appidacr": "1",
    "idp": "https://sts.windows.net/tenant-id/",
    "oid": "user-object-id",
    "tid": "tenant-id",
    "scp": "access_as_user",
    "sub": "subject",
    "ver": "1.0"
  }
}

エラーの例

// 400 Bad Request - No token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "No token found"
}

// 401 Unauthorized - Invalid token
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Unauthorized",
  "status": 401
}

/AuthorizationHeader/{serviceName}

構成されたダウンストリーム API のアクセス トークンを取得し、承認ヘッダー値として返します。 ユーザー ベアラー トークンが受信で提供されている場合は、OBO (委任) が使用されます。それ以外の場合は、アプリ コンテキスト パターンが適用されます (有効な場合)。

Path パラメーター

• serviceName – 構成内のダウンストリーム API の名前

クエリ パラメーター

標準オーバーライド

エージェント ID

準則：

• AgentUsernameまたはAgentUserIdAgentIdentity (ユーザー エージェント) が必要です。
• AgentUsername と AgentUserId は相互に排他的です。
• AgentIdentity alone = 自律エージェント。
• AgentIdentity + ユーザー受信トークン = 委任されたエージェント。

例示

基本的な要求:

GET /AuthorizationHeader/Graph HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

[応答]

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

PoP/SHR 応答:

{
  "authorizationHeader": "PoP eyJ0eXAiOiJhdCtqd3QiLCJhbGc..."
}

/AuthorizationHeaderUnauthenticated/{serviceName}

/AuthorizationHeader/{serviceName}と同じ動作とパラメーターですが、受信ユーザー トークンは必要ありません。 ユーザー コンテキストなしでアプリ専用または自律/エージェント ID を取得するために使用されます。 ユーザー トークンを検証するオーバーヘッドを回避します。

リクエスト

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

[応答]

{
  "authorizationHeader": "Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
}

/DownstreamApi/{serviceName}

アクセス トークンを取得し、ダウンストリーム API への HTTP 要求を実行します。 ダウンストリーム応答から状態コード、ヘッダー、および本文を返します。 ユーザー OBO、アプリ専用、またはエージェント ID パターンをサポートします。

Path パラメーター

• serviceName – ダウンストリーム API 名を構成しました。

追加のクエリ パラメーター ( /AuthorizationHeader パラメーターに加えて)

要求本文の転送

本文は変更されずに渡されます。

POST /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{ 
  "subject": "Hello", 
   "body": { "contentType": "Text", "content": "Hello world" } 
}

[応答]

{
  "statusCode": 200,
  "headers": {
    "content-type": "application/json"
  },
  "content": "{\"@odata.context\":\"...\",\"displayName\":\"...\"}"
}

エラーは、 /AuthorizationHeader とダウンストリーム API エラー状態コードを反映します。

/DownstreamApiUnauthenticated/{serviceName}

/DownstreamApi/{serviceName}と同じですが、受信ユーザー トークンは検証されません。 アプリ専用または自律的なエージェント操作に使用します。

/healthz

基本的な正常性プローブ エンドポイント。

[応答]

正常 (200):

HTTP/1.1 200 OK

異常 (503):

HTTP/1.1 503 Service Unavailable

/openapi/v1.json

OpenAPI 3.0 仕様を返します (開発環境のみ)。 次の用途に使用します。

• クライアント コードを生成する
• 要求を検証する
• エンドポイントの検出

一般的なエラー パターン

無効な要求 (400)

サービス名がありません:

// 400 Bad Request - Missing service name
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "Service name is required" }

// 400 Bad Request - Invalid agent combination
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "AgentUsername and AgentUserId are mutually exclusive" }

// 401 Unauthorized - Invalid token
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Unauthorized", "status": 401 }

// 403 Forbidden - Missing scope
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "Forbidden", "status": 403, "detail": "The scope 'access_as_user' is required" }

// 404 Not Found - Service not configured
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "Downstream API 'UnknownService' not configured" }

// 500 Internal Server Error - Token acquisition failure
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "Failed to acquire token for downstream API" }

MSAL エラーの例

{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "Internal Server Error", "status": 500, "detail": "MSAL.NetCore.invalid_grant: AADSTS50076: Due to a configuration change ...", "extensions": { "errorCode": "invalid_grant", "correlationId": "..." } }

完全なオーバーライド リファレンス

optionsOverride.Scopes=<scope>     # Repeatable
optionsOverride.RequestAppToken=<true|false>
optionsOverride.BaseUrl=<url>
optionsOverride.RelativePath=<path>
optionsOverride.HttpMethod=<method>
optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>
optionsOverride.AcquireTokenOptions.AuthenticationScheme=<scheme>
optionsOverride.AcquireTokenOptions.CorrelationId=<guid>
optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>
optionsOverride.AcquireTokenOptions.PopClaims=<json>
optionsOverride.CustomHeader.<Name>=<value>

AgentIdentity=<agent-client-id>
AgentUsername=<user-upn>            # Requires AgentIdentity
AgentUserId=<user-object-id>        # Requires AgentIdentity

オーバーライドの例

スコープをオーバーライドします。

GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

レート制限

Microsoft Entra SDK for AgentID 自体では、レート制限は課されません。 有効な制限は次のとおりです。

1. Microsoft Entra ID トークン サービスの調整 (SDK がトークンをキャッシュする場合は発生しません)
2. ダウンストリーム API の制限
3. トークン キャッシュの効率 (取得量を削減)

ベスト プラクティス

1. アドホック オーバーライドよりも構成を優先します。
2. サービス名は静的および宣言型のままにします。
3. 一時的な障害 (HTTP 500/503) の再試行ポリシーを実装します。
4. 呼び出す前にエージェント パラメーターを検証します。
5. サービス間でトレースするためのログ関連付け ID。
6. トークン取得の待機時間とエラー率を監視します。
7. オーケストレーション プラットフォームで正常性プローブを使用します。

こちらもご覧ください

• 構成リファレンス
• エージェント ID
• シナリオ: 承認ヘッダーを検証する
• シナリオ: 承認ヘッダーを取得する
• シナリオ: ダウンストリーム API を呼び出す