エンドポイント リファレンス: Microsoft Entra ID Auth SDK (サイドカー) HTTP API

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

API 仕様

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

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

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

エンドポイントの概要

Authentication

ベアラーは、認証されたエンドポイントの既定の認証スキームのままです。 /Validate エンドポイントは、アプリ専用の署名付き HTTP 要求 (SHR) 資格情報のPoPスキームも受け入れます。 認証されていないと明示的にマークされている場合を除き、他の認証済みエンドポイントには Bearer が必要です。

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

トークンは、テナント、対象ユーザー、発行者、スコープを含む、構成されたMicrosoft Entra ID設定に対して検証されます (有効になっている場合)。 PoP 要求の場合、サイドカーは、同じテナント、対象ユーザー、発行者、署名キーの構成に対して SHR 署名とその埋め込みアクセス トークンを検証します。

/Validate

受信ベアラー トークンまたはアプリ専用の SHR PoP 資格情報を検証し、検証済みのトークンとその要求を返します。

リクエスト

ベアラー要求:

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

PoP 要求:

GET /Validate HTTP/1.1
Authorization: PoP <signed-http-request>
original-method: GET
original-uri: https://api.contoso.com/data

PoP の場合は、 original-method と original-uri が必要です。 SHR 資格情報がサインオンされた元の要求のメソッドと絶対 URI を含める必要があります。 サイドカーはこれらの値を使用して要求バインディングを検証します。 /Validate 要求自体が署名されたリソース要求ではありません。

成功した応答 (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"
  }
}

protocol値はベアラー要求に対してBearerされ、PoP 要求のPoPされます。 PoP の場合、 token には、署名された HTTP 要求に埋め込まれた検証済みアクセス トークンが含まれます。 返される要求は、アクセス トークンのバージョンとテナントの構成によって異なります。

エラーの例

不足している承認資格情報は、エンドポイントを実行する前に拒否されます。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

無効なベアラー トークンは、ベアラー チャレンジを返します。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

失敗した PoP 要求には、次のチャレンジが含まれます。 /Validateは両方の認証スキームを受け入れるため、応答にはベアラー チャレンジを含めることもできます。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: PoP error="invalid_token"

/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 ID認証 SDK (サイドカー) 自体では、レート制限は課されません。 有効な制限は次のとおりです。

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

ベスト プラクティス

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

関連するコンテンツ

• 構成リファレンス
• エージェント ID
• 承認ヘッダーの検証
• ダウンストリーム API を呼び出す