發出 JSON Web Token

本文件將說明如何發出 JSON Web Token，讓網頁和行動應用程式存取 Fleet Engine 資料。如果您尚未完成此步驟，請參閱Fleet Engine 的安全性一節下方的 JSON Web Token。透過 Fleet Engine 服務，您可以使用下列其中一種方式發出 JWT：

• 使用授權程式庫：如果程式碼集是使用 Java 編寫，Google 建議您採用這種方法。這個程式庫會針對您可能需要使用服務的所有用途情境，處理 JWT 核發作業，並大幅簡化實作程序。
• 建立自己的 JWT：如果無法使用我們的 JWT 程式庫，您就必須在程式碼集中建構這些 JWT。本節針對各種情境提供不同的 JWT 範例。

JWT 的運作方式

對於行動電話和網頁瀏覽器等不受信任的環境，後端伺服器會發出 JWT，運作方式如下：

• 在低信任度環境中執行的用戶端程式碼會呼叫在完全信任環境中執行的伺服器程式碼，要求適當的 JWT 以便傳遞至 Fleet Engine。

• JWT 與服務帳戶相關聯，因此傳送至 Fleet Engine 的要求會隱含與簽署 JWT 的服務帳戶相關聯。

• JWT 聲明會進一步限制用戶端可操作的資源，例如特定車輛、行程或工作。

使用 Java 的授權程式庫

如要使用 Java 專用的 Fleet Engine 授權程式庫，請前往 GitHub 存放區。這個程式庫可簡化 Fleet Engine JWT 的建構程序，並以安全的方式簽署 Fleet Engine JWT。提供以下功能：

• 專案依附元件宣告
• 隨選行程或排程任務的所有服務帳戶角色完整清單
• 使用憑證檔案以外的權杖簽署機制，例如模擬服務帳戶
• 將已簽署權杖附加至由 gRPC 虛設常式或 Google API Codegen (GAPIC) 用戶端程式庫發出的傳出要求
• 整合簽署人與 Fleet Engine 用戶端程式庫的操作說明

如果您從程式碼發出 JWT

如果無法使用 Java 的授權程式庫，您必須在自己的程式碼集中實作 JWT。本節提供幾項建立專屬符號的指南。如需 JWT 欄位和宣告清單，請參閱「Fleet Engine 中的安全性」一節中的「JSON Web Token」。如要瞭解 Fleet Engine 使用的服務帳戶角色，請參閱服務帳戶角色。如需即時行程或排程工作任務的 JWT 範例清單，請參閱下節。

一般指南

• 使用適當的服務帳戶和角色。服務帳戶和相關角色可確保要求權杖的使用者有權查看權杖授予存取權的資訊。具體情況如下：
  • 如果要簽署要傳遞至行動裝置的 JWT，請使用 Driver 或 Consumer SDK 角色的服務帳戶。否則，行動裝置可能會修改並存取不應存取的資料。
  • 如果要簽署用於特權呼叫的 JWT，請在使用 ADC 或 JWT 時，使用具有正確 Fleet Engine 管理員角色的服務帳戶。否則作業就會失敗。
• 隻共用已建立的權杖。切勿分享用於建立權杖的憑證，
• 針對 gRPC 呼叫，附加憑證的機制取決於呼叫所用的語言和架構。為 HTTP 呼叫指定符記的機制是加入具有不記名符記的 Authorization 標頭，該符記的值為符記。
• 傳回到期時間。您的伺服器必須傳回權杖的到期時間，通常以秒為單位。
• 如需直接建立並簽署 JSON 做為權杖不記名，而非使用 OAuth 2.0 存取權杖，請參閱 Identity 開發人員說明文件中不使用 OAuth 的服務帳戶授權操作說明。

隨選行程

• 建立 JWT 酬載時，請在授權區段中新增額外的憑證附加資訊，並將鍵 vehicleid 或 tripid 設為發出呼叫的車輛 ID 或行程 ID 值。

適用於已排定的工作

• 伺服器呼叫其他 API 時，權杖也必須包含適當的憑證附加資訊。您可以採取下列做法：
  • 將每個鍵的值設為 *。
  • 將所有 taskids 和 deliveryvehicleids 的存取權授予使用者。如要這麼做，請在授權部分中使用 taskid 和 deliveryvehicleid 鍵新增額外的要求。
  • 在 taskids 要求中使用星號 (*) 時，星號必須是陣列中唯一的元素。

隨選行程的 JWT 範例

本節針對使用預約行程的常見情境，提供 JWT 範例。

驅動程式應用程式作業的權杖範例

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

消費者應用程式作業的憑證範例

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

排程工作 JWT 範例

如果您使用排程工作，本節提供適用於一般情境的 JWT 範例。

驅動程式應用程式的權杖範例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

消費者應用程式的權杖範例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

注意： trackingid 索賠是運送追蹤 ID。

機群作業的 JWT 範例

本節提供車隊作業中常見情境的 JWT 範例。

用於追蹤車隊中所有工作和車輛的範例權杖

以下範例是權杖，可透過業者使用的網頁式應用程式追蹤車隊中的所有工作和車輛。這些作業所需的權限大於用戶端應用程式所需的權限。如要瞭解會使用此符記的用戶端實作方式，請參閱「設定 JavaScript Fleet Tracking Library」：

• 請使用 Fleet Engine Delivery Fleet Reader Cloud IAM 角色簽署權杖。

  注意：使用這個角色建立的權杖會授予 Fleet Engine 實體部分權限。請確保後端只與通過驗證的使用者共用權杖。

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

後端伺服器作業的其他驗證方法

Google 建議您使用 ADC 驗證後端伺服器作業。如果您無法使用 ADC 而需要使用 JWT，請參閱這些範例。

按需後端伺服器作業的範例符記

  {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "private_key_id_of_provider_service_account"
  }

  {
    "iss": "[e-mail]",
    "sub": "[e-mail]",
    "aud": "https://fleetengine.googleapis.com/",
    "iat": 1511900000,
    "exp": 1511903600,
    "authorization": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }
  

排定的後端伺服器作業權杖範例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }
   

排定後端伺服器批次建立工作作業的權杖範例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }
  

已排定的後端伺服器每次交付產品作業的權杖範例

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }
  

後續步驟

• 驗證設定，以便建立試用車輛，並確保權杖正常運作
• 如要瞭解如何使用 ADC 而非 JWT 進行後端伺服器作業，請參閱安全性總覽。