JSON Web Token

JSON Web Token (JWT) 是一種開放式網路標準，用於驗證及授權用戶端與伺服器之間的資訊交換。當應用程式使用者首次使用適當的角色憑證登入時，伺服器會建立並傳回經過編碼和數位簽署的 JWT，用於後續要求。這項程序會驗證使用者身分，並根據其帳戶角色，授權他們存取路徑、服務和資源。

Fleet Engine 規定，從低信任環境 (智慧型手機和瀏覽器) 呼叫 API 方法時，必須使用 JSON Web Token (JWT)。

JWT 源自伺服器，經過簽署和加密，並傳遞至用戶端，用於後續的伺服器互動，直到過期或失效為止。

重要詳細資料

• 使用應用程式預設憑證，向 Fleet Engine 進行驗證及授權。
• 使用適當的服務帳戶簽署 JWT。請參閱「Fleet Engine 基本概念」中的「Fleet Engine 服務帳戶角色」。

與 API 金鑰不同，JWT 的效期較短，且僅限於角色有權執行的作業。如要進一步瞭解 JWT，請參閱維基百科的 JSON Web Token 頁面。如要進一步瞭解存取角色，請參閱本指南的「服務帳戶角色」一節。

JWT 元素

JWT 包含標頭和權杖附加資訊部分。標頭部分包含從服務帳戶取得的私密金鑰和加密演算法等資訊。宣告部分包含 JWT 的建立時間、存留時間、JWT 宣告存取的服務，以及其他授權資訊，用於限定存取範圍，例如運送車輛 ID。

下表提供一般 JWT 欄位的說明，以及在 Fleet Engine 雲端專案中，何處可找到這些欄位的值。

JWT 標頭欄位

欄位	說明
alg	要使用的演算法。RS256。
typ	權杖類型。`JWT`。
兒童	服務帳戶的私密金鑰 ID。您可以在服務帳戶 JSON 檔案的 private_key_id 欄位中找到這個值。請務必使用具備適當權限層級的服務帳戶金鑰。

JWT 宣告欄位

欄位	說明
iss	服務帳戶的電子郵件地址，位於服務帳戶 JSON 檔案的 client_email 欄位。
替補球員	服務帳戶的電子郵件地址，位於服務帳戶 JSON 檔案的 client_email 欄位。
aud	服務帳戶的 SERVICE_NAME，在本例中為 https://fleetengine.googleapis.com/
iat	JWT 的建立時間戳記，以 UTC, January 1, 1970 00:00:00 起經過的秒數表示。允許 10 分鐘的時間誤差。 如果時間戳記太久遠或在未來，伺服器可能會回報錯誤。
exp	JWT 到期的時間戳記，以自 00:00:00 UTC, January 1, 1970 起經過的秒數指定。如果時間戳記超過一小時，要求就會失敗。
授權	視用途而定，可能包含 deliveryvehicleid、trackingid、taskid 或 taskids。 如果指定 taskids，授權範圍必須是下列其中一種形式的陣列： "taskids": ["task_id_one","task_id_two"] 或 "taskids": ["*"]

Fleet Engine JWT 憑證

Fleet Engine 使用私人聲明。使用私人聲明可確保只有授權用戶端能存取自己的資料。

舉例來說，當伺服器為司機的行動裝置核發 JSON Web Token 時，應包含 vehicleid 宣告或 deliveryvehicleid 宣告，並將值設為該司機的車輛 ID。接著，根據駕駛員角色，JWT 只會啟用特定車輛 ID 的存取權，而非任何其他任意車輛 ID。

Fleet Engine 使用下列私人聲明：

隨選行程

• vehicleid：
  • 無論是行程或車輛，Driver SDK 一律會使用這項聲明。Fleet Engine 後端會先確認車輛與要求的行程相關聯，再進行修改。
  • JWT 可涵蓋車輛和行程作業，即使並非必要，也能簡化 JWT 簽署作業。
• tripid：
  • Consumer SDK 一律會使用這項憑證。
  • JWT 可涵蓋車輛和行程作業，即使不需要也一樣，這可簡化權杖簽署作業。

排定的任務

• deliveryvehicleid

  呼叫每輛運送車輛 API 時使用。

• taskid

  呼叫個別 Tasks API 時使用。

• taskids

  呼叫 BatchCreateTasksAPI 時使用。這項要求必須採用陣列形式，且陣列應包含完成要求所需的所有工作 ID。請勿加入 delivervehicleid、trackingid 或 taskid 聲明。

• trackingid

  呼叫 GetTaskTrackingInfoAPI 時使用。要求必須與要求中的追蹤 ID 相符。請勿加入 delivervehicleid、taskid 或 taskids 聲明。

後續步驟

• 請參閱「Fleet Engine 安全性設計」，瞭解完整的驗證流程。
• 瞭解如何從伺服器核發 JSON Web Token。