發出 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 的建構作業，並安全簽署這些 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 存取權杖，請參閱身分識別開發人員文件中的不使用 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": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "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": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "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": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "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": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

機群操作的 JWT 範例

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

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

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

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

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

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

  {
    "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "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": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }
   

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }
  

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }
  

後續步驟

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