JSON Web Token

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

對於來自低信任環境的 API 方法呼叫，Fleet Engine 要求使用由適當服務帳戶簽署的 JSON Web Token (JWT)。信任度低的環境包括智慧型手機和瀏覽器。JWT 會在伺服器上產生，而伺服器是完全信任的環境。系統會為 JWT 簽署、加密，並將其傳遞給用戶端，以便後續的伺服器互動，直到 JWT 到期或不再有效為止。

後端應使用標準的應用程式預設憑證機制，針對 Fleet Engine 進行驗證和授權。請務必使用經過適當服務帳戶簽署的 JWT。如需服務帳戶角色清單，請參閱「Fleet Engine 基礎知識」中的Fleet Engine 服務帳戶角色。

相反地，後端應使用標準的應用程式預設憑證機制，針對 Fleet Engine 進行驗證及授權。

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

JWT 元素

JWT 包含標頭和憑證附加資訊區段。標頭部分包含從服務帳戶取得的私密金鑰和加密演算法等資訊。權利要求部分包含 JWT 的建立時間、生命週期、JWT 聲明可存取的服務，以及其他授權資訊 (例如運送車輛 ID)。

下表提供一般 JWT 欄位的詳細說明，以及在 Fleet Engine Cloud 專案中尋找這些欄位值的具體資訊。

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 建立時間戳記，以自 00:00:00 UTC, January 1, 1970 起算的秒數為單位。允許 10 分鐘的偏移時間。 如果時間戳記過於久遠或位於未來，伺服器可能會回報錯誤。
exp	JWT 到期時間的時間戳記，以 00:00:00 UTC, January 1, 1970 起算的秒數為單位。如果時間戳記在未來一小時後，要求就會失敗。
授權	視用途而定，可能包含 deliveryvehicleid、trackingid、taskid 或 taskids。 如果指定 taskid，授權範圍必須是下列任一種形式的陣列： "taskids": ["task_id_one","task_id_two"] 或 "taskids": ["*"]

Fleet Engine JWT 憑證附加資訊

Fleet Engine 會使用私人權利要求。使用私人權利要求可確保只有授權的用戶端可以存取自己的資料。

舉例來說，當伺服器為駕駛人的行動裝置發出 JSON Web 權杖時，應包含 vehicleid 權杖或 deliveryvehicleid 權杖，並附上駕駛人的車輛 ID 值。接著，視駕駛員角色而定，JWT 只會啟用特定車輛 ID 的存取權，而不會啟用任何其他任意車輛 ID。

Fleet Engine 會使用下列私人權利要求：

隨選行程

• vehicleid：
  • 無論是針對行程或車輛運作，Driver SDK 一律會使用這項聲明。車隊引擎後端會在修改前，確認車輛與要求的行程相關聯。
  • JWT 可涵蓋車輛和行程作業 (即使不必要)，這可能會簡化 JWT 簽署實作。
• tripid：
  • Consumer SDK 一律會使用這個宣告。
  • JWT 可涵蓋車輛和行程作業，即使不必使用也一樣，這可能會簡化權杖簽署的實作方式。

排定的工作

• deliveryvehicleid

  呼叫每個發布管道 API 時使用。

• taskid

  在呼叫個別工作 API 時使用。

• taskids

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

• trackingid

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

後續步驟

• 請參閱車隊引擎安全設計，瞭解完整的驗證流程。
• 瞭解如何從伺服器發出 JSON Web Token。