驗證 | Trend Micro Service Central

驗證

本節說明 Apex Central 如何驗證 API 要求。

Apex Central 採用 Token 型驗證，以確保只有受信任的應用程式可以使用 API。您必須建立正確定義的 JSON Web Token (JWT) 並將其包含在每個 API 要求中，才能存取服務和資源。

JWT 是一種開放的產業標準方法，用於將資訊做為 JSON 物件在各方之間安全地傳輸。傳輸的資訊具有數位簽章，因此可以驗證並加以信任。

如需有關 JWT 的詳細資訊，請移至 https://jwt.io/introduction/。

授權 Token 結構

本主題說明用於驗證 Apex Central API 要求的授權 Token 結構。

JSON Web Token (JWT) 是由以圓點分隔的三個區段組成，例如 xxxxx.yyyyy.zzzzz。

標頭：此區段包含下列採用 Base64URL 編碼的資訊。

表 1. JWT 標頭 — 必要資訊
內容	說明
`alg`	用來計算總和檢查碼的演算法支援的演算法： HS256 (HMAC SHA256) HS384 HS512
`typ`	Token 類型重要: Apex Central 僅接受 JWT。

以下是已解碼的 JWT 標頭範例。

{
"alg": "HS256",
"typ": "JWT"
}

酬載：此區段包含關於第三方應用程式和其他資料的陳述式，採用 Base64URL 編碼。

表 2. JWT 酬載 — 必要資訊
內容	說明
`appid`	第三方應用程式的應用程式 ID 您可以從 Apex Central 主控台的「自動化 API 存取設定」畫面上取得此值。如需詳細資訊，請參閱新增應用程式。
`iat`	"Issued at" Token 產生時間您必須以 Unix 時間戳記格式（自 1970 年 1 月 1 日開始的秒數，採用 UTC 表示）指定此值。
`version`	此 JWT 的版本重要: Apex Central 僅接受 "V1" JWT。
`checksum`	要求的總和檢查碼如需詳細資訊，請參閱總和檢查碼計算。

重要:

除非 JWT 已加密，否則請勿在酬載中包含機密資訊。

以下是已解碼的 JWT 酬載範例。

{
"appid": "2E28ED1BABA2-4D10BB13-F4FA-D5D4-31F3",
"iat": 1495187266.6215432,
"version": "V1",
"checksum": "J+CMrBKctcXXuQ68GrpFyS1+FXA4gCKs8crdOGJZ24Q="
}

簽章：此區段包含下列已簽章的資訊。
- 已編碼的標頭
- 已編碼的酬載
- 金鑰：對於 Apex Central API，「API 金鑰」是用來產生 JWT 簽章的金鑰。
- 標頭中指定的演算法

總和檢查碼計算

本主題說明如何計算用於驗證 Apex Central API 授權 Token 的總和檢查碼。

為了防止第三方重複使用 JWT，請將 checksum 欄位包含在此 Token 中。下列資訊用於計算 checksum。

要求	資訊
`HTTP-Method`	要求的 HTTP 方法（使用大寫字元） `GET` `POST` `PUT` `DELETE`
`Raw-URL`	要求的路徑和查詢字串（使用小寫字元）範例 1： API 的 URL： https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents?HostName=TestAgent 原始 URL： `/webapp/API/agentresource/productagents?hostname=testagent` 範例 2：自動化 API 的 URL： https://<Apex_Central_Server>/WebApp/API/AgentResource/ProductAgents 原始 URL： `/webapp/API/agentresource/productagents` 重要: 如果查詢字串是空的，請勿包含 "?" 字元。
`Canonical-Request-Headers`	以 "API" 開頭的所有要求標頭清單您必須執行下列動作：按英文字母順序列出標頭，並將每個標頭轉換為下列格式。 `LowerCase(Header Name) + ":" + Trim(Header Value)` 使用 "&" 分隔符號聯結標頭。重要: 如果沒有任何標頭以 `API` 為開頭，請將 `Canonical-Request-Headers` 值保留為空字串。
`Request-Body`	採用 UTF-8 編碼的 JSON 字串的要求主體

對於計算 HTTP-Method + "|" + Raw-URL + "|" + Canonical-Request-Headers + "|" + Request-Body 後得出的 SHA-256 總和檢查碼，checksum 欄位採用 base64 字串來表示計算後的 SHA-256 總和檢查碼位元組陣列。

上層主題

Apex Central 自動化 API