Endpoints reference: Microsoft Entra ID Auth SDK (sidecar) HTTP API

本文件提供 Microsoft Entra ID Auth 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

使用它來:

  • 產生用戶端程式碼
  • 驗證要求
  • 探索可用的端點

端點概述

端點 製作方法 目標 需要驗證
/Validate GET 驗證入站持有憑證或僅應用 PoP 簽名的 HTTP 請求並回傳聲明 Yes
/AuthorizationHeader/{serviceName} GET 驗證輸入權杖 (如果有的話) 並取得下游 API 的授權標頭 Yes
/AuthorizationHeaderUnauthenticated/{serviceName} GET 取得沒有傳入使用者權杖的授權標頭 (應用程式或代理程式身分) Yes
/DownstreamApi/{serviceName} 獲取、發布、放置、修補、刪除 驗證輸入權杖 (如果有的話) ,並使用自動權杖取得呼叫下游 API Yes
/DownstreamApiUnauthenticated/{serviceName} 獲取、發布、放置、修補、刪除 呼叫下游 API (僅限應用程式或客服專員身分識別) Yes
/healthz GET 健康情況探查 (活躍度/整備狀態) 否
/openapi/v1.json GET OpenAPI 3.0 文件 否 (僅限開發人員)

Authentication

承載者仍是已認證端點的預設認證方案。 端 /Validate 點同時也接受 PoP 僅限應用程式的簽署 HTTP 請求(SHR)憑證方案。 其他已認證端點則需要承載,除非明確標記為未認證:

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-methodoriginal-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 請求中的驗證存取權杖。 回傳的理賠取決於存取權杖版本及租戶設定。

Important

入站 PoP 驗證支援僅應用程式用戶端憑證的存取權杖。 它不支援委派或使用者令牌、OBO 或演員令牌流程、mTLS PoP 或 PFT/CDT over PoP。 AzureAd__Scopes 不會套用在僅應用程式的 PoP 請求上,因為這些標記不包含 scp 申訴。 您的應用程式必須透過回傳的應用程式角色、應用程式權限或其他可信的主張來授權。

錯誤範例

缺少的授權憑證會在端點執行前被拒絕:

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(委派);否則,應用程式內容模式會套用 (如果已啟用)。

路徑參數

  • serviceName — 配置中下游API的名稱

查詢參數

標準覆蓋

參數 類型 Description Example
optionsOverride.Scopes 字串[] 覆寫已設定的範圍 (可重複) ?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read
optionsOverride.RequestAppToken 布爾值 強制僅限應用程式的權杖 (略過 OBO) ?optionsOverride.RequestAppToken=true
optionsOverride.AcquireTokenOptions.Tenant 字串 覆寫租用戶識別碼 ?optionsOverride.AcquireTokenOptions.Tenant=tenant-guid
optionsOverride.AcquireTokenOptions.PopPublicKey 字串 啟用 PoP/SHR(base64 公鑰) ?optionsOverride.AcquireTokenOptions.PopPublicKey=base64key
optionsOverride.AcquireTokenOptions.PopClaims 字串 其他 PoP 宣告 (JSON) ?optionsOverride.AcquireTokenOptions.PopClaims={"nonce":"abc"}

客服專員身分

參數 類型 Description Example
AgentIdentity 字串 客服專員應用程式 (用戶端) ID ?AgentIdentity=11111111-2222-3333-4444-555555555555
AgentUsername 字串 使用者主體名稱 (委派代理程式) ?AgentIdentity=<id>&AgentUsername=user@contoso.com
AgentUserId 字串 使用者物件識別碼 (委派代理程式) ?AgentIdentity=<id>&AgentUserId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

槼:

  • AgentUsername 或 AgentUserId require AgentIdentity (使用者代理程式)。
  • AgentUsername 並且 AgentUserId 是相互排斥的。
  • AgentIdentity 單獨 = 自主代理人。
  • 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} 和參數相同,但沒有傳入使用者權杖。 用於僅限應用程式或自主/代理程式身分識別,而沒有使用者內容。 避免驗證使用者權杖的額外負荷。

請求

GET /AuthorizationHeaderUnauthenticated/Graph HTTP/1.1

回應

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

/DownstreamApi/{serviceName}

取得存取權杖,並向下游 API 執行 HTTP 要求。 從下游回應傳回狀態碼、標頭和本文。 支援使用者 OBO、僅限應用程式或代理程式身分識別模式。

路徑參數

  • serviceName — 已設定下游 API 名稱。

額外的查詢參數(除了 /AuthorizationHeader 參數之外)

參數 類型 Description Example
optionsOverride.HttpMethod 字串 覆寫 HTTP 方法 ?optionsOverride.HttpMethod=POST
optionsOverride.RelativePath 字串 將相對路徑附加至已設定的 BaseUrl ?optionsOverride.RelativePath=me/messages
optionsOverride.CustomHeader.<Name> 字串 新增自訂標頭 ?optionsOverride.CustomHeader.X-Custom=value

請求正文轉發

身體通過不變:

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} ,但不會驗證任何傳入使用者權杖。 用於僅限應用程式或自主代理程式作業。

/健康茲

基本健康情況探查端點。

回應

健康 (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. 記錄跨服務追蹤的相互關聯識別碼。
  6. 監控權杖取得延遲和錯誤率。
  7. 在協調流程平台中使用健康情況探查。