本文件提供 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或AgentUserIdrequireAgentIdentity(使用者代理程式)。 -
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(側車)本身並不設定速率限制。 有效限制來自:
- Microsoft Entra ID 令牌服務限速(SDK 快取令牌時不應該發生)
- 下游 API 限制
- 令牌快取效率(減少獲取量)
最佳做法
- 偏好設定而不是臨機操作覆寫。
- 保持服務名稱靜態且宣告式。
- 實作暫時性失敗的重試原則 (HTTP 500/503)。
- 在呼叫之前驗證客服專員參數。
- 記錄跨服務追蹤的相互關聯識別碼。
- 監控權杖取得延遲和錯誤率。
- 在協調流程平台中使用健康情況探查。