發出 JSON Web Token

本文說明如何發行 JSON Web Token，讓網路和行動應用程式存取 Fleet Engine 資料。如尚未閱讀，請先參閱「Fleet Engine 安全性」一節中的「JSON Web Tokens」。您可以使用下列其中一種方式，透過 Fleet Engine 服務發出 JWT：

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

JWT 的運作方式

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

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

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

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

使用 Java 授權程式庫

如要使用 Java 適用的 Fleet Engine 授權程式庫，請前往 GitHub 存放區。這個程式庫可簡化 Fleet Engine JWT 的建構作業，並安全地簽署這些 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 程式庫」：

• 使用 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) 執行後端伺服器作業，請參閱安全性總覽。