Last Mile 機群解決方案 (解決方案) 目前僅適用於特定客戶。如需瞭解詳情，請聯絡銷售人員。

本頁面由 Cloud Translation API 翻譯而成。

驗證及授權

本節說明與 Fleet Engine 整合的驗證和授權概念。

您可以透過 Google Cloud 控制台設定 Last Mile Fleet Solution 提供的功能。Fleet Engine SDK 必須使用適當服務帳戶簽署的 JSON Web Token (JWT)。

總覽

進行 Fleet Engine 驗證和授權的客戶後端，應使用標準的應用程式預設憑證機制。

而 Fleet Engine 也會接收來自低信任環境 (例如智慧型手機和瀏覽器) 的呼叫。為了保護服務帳戶密鑰僅適用於受信任的環境，客戶的後端應產生已簽署的 JSON Web Token (JWT)，其中包含 Fleet Engine 專屬的額外憑證附加資訊，接著再核發給不受信任的環境 (如手機)。

驗證設計原則

Fleet Engine 的驗證流程包含下列設計原則。

IAM 角色定義了一組對主體授予資源的權限。舉例來說，「管理員」角色可以使用應用程式預設憑證執行所有操作，「不受信任的驅動程式*」角色只能更新車輛位置，且僅限使用 JWT 進行驗證和授權。
針對不受信任的環境，JWT 憑證附加資訊會進一步限制呼叫端可能在其中執行的實體。可以是特定任務或運輸車輛。
在低信任環境中執行的程式碼必須先在受信任環境中執行的程式碼呼叫，才能發出 JWT。
Fleet Engine 會對資源的 API 呼叫執行下列安全檢查：
1. 呼叫主體具備對資源動作的適當權限 (透過角色指派方式)。
2. 如果是非管理員角色，則要求中傳遞的 JWT 憑證附加資訊會提供資源所需的權限。

驗證流程

以下序列圖表展示這些驗證流程的詳細資料。

機群管理員會建立服務帳戶
機群管理員會為服務帳戶指派特定 IAM 角色。
機群管理員會使用服務帳戶和應用程式預設憑證來設定後端。
用戶端應用程式向客戶後端要求 JWT。要求者可以是驅動程式應用程式、消費者應用程式或監控應用程式。
客戶後端會簽署並發出各服務帳戶的 JWT。用戶端應用程式收到 JWT。
用戶端應用程式會根據在設定階段指派給 Fleet Engine 的 IAM 角色，使用 JWT 連線至 Fleet Engine 讀取或修改資料。

驗證序列圖表

Cloud 專案設定

如要設定雲端專案，請先建立專案，然後建立服務帳戶。

如要建立 Google Cloud 專案，請按照下列步驟操作：

使用 Google Cloud 控制台建立 Google Cloud 專案。
使用 API 和服務資訊主頁，啟用 Local Rides and Deliveries API。

服務帳戶和 IAM 角色

服務帳戶是一種特殊帳戶，由應用程式 (而非使用者) 使用。一般來說，服務帳戶可用來建立 JWT，其會根據角色授予不同的權限組合。為降低濫用的可能性，您可以建立多個服務帳戶，每個帳戶至少要有一組必要的角色 ()。

Last Mile Fleet Solution 使用下列角色：

角色	說明
Fleet Engine Delivery 受信任驅動程式使用者 `roles/fleetengine.deliveryTrustedDriver`	授予建立及更新運輸車輛和工作的權限，包括更新送貨車位置、工作狀態或結果。具備這個角色的服務帳戶建立的憑證，通常會透過您推送驅動程式的行動裝置或後端伺服器使用。
不受信任的 Fleet Engine Delivery 駕駛員使用者 `roles/fleetengine.deliveryUntrustedDriver`	可授予更新送貨車位置的權限。具備這個角色的服務帳戶建立的權杖通常是從您的配送司機的行動裝置上使用。
Fleet Engine Delivery 一般使用者 `roles/fleetengine.deliveryConsumer`	可使用追蹤 ID 搜尋工作，以及讀取工作資訊但不更新。具備這個角色的服務帳戶建立的權杖通常是透過供應端使用者的網路瀏覽器來使用。
Fleet Engine Delivery 管理員 `roles/fleetengine.deliveryAdmin`	授予交付資源的讀取和寫入權限。具備這個角色的主體不需要使用 JWT，應改用應用程式預設憑證。系統會忽略自訂 JWT 憑證附加資訊。這個角色應限制在受信任的環境 (客戶後端) 範圍內。
~~Fleet Engine Delivery 超級使用者~~ (已淘汰) `roles/fleetengine.deliverySuperUser`	授予所有推送車輛和工作 API 的權限。具備這個角色的服務帳戶建立的權杖，通常會用於後端伺服器。
Fleet Engine Delivery 機群讀取者 `roles/fleetengine.deliveryFleetReader`	可授予讀取運輸車輛和工作的權限，以及使用追蹤 ID 搜尋工作的權限。具備這個角色的服務帳戶建立的權杖通常是透過推送機群業者的網路瀏覽器使用。

如果機構透過企業 IT 管理的裝置來強化推送司機，可以善用 Fleet Engine 受信任驅動程式使用者角色提供的靈活性，並選擇在行動應用程式中整合部分或所有 Fleet Engine 互動。

支援「自攜裝置政策」的機構應選擇以保護 Fleet Engine 未信任驅動程式使用者角色的安全，僅使用行動應用程式將車輛位置更新資訊傳送至 Fleet Engine。所有其他互動應來自客戶的後端伺服器。

驅動程式和消費者 SDK 是根據這些標準角色建構而成。不過，您可以建立自訂角色，允許將任意一組權限組合在一起。缺少必要權限時，驅動程式和消費者 SDK 會顯示錯誤訊息。因此，我們強烈建議使用上述的標準角色組合，而非自訂角色。

建立服務帳戶

您可以使用 Google Cloud 控制台中的「IAM & Admin > Service Accounts」分頁建立服務帳戶。從「Role」(角色) 下拉式清單中選取「Fleet Engine」，然後將其中一個角色指派給服務帳戶。建議您標明與各個角色相關聯的帳戶。例如，為服務帳戶提供有意義的名稱。

為了方便起見，如果您需要為不受信任的用戶端建立 JWT，只要將使用者新增至服務帳戶權杖建立者角色，即可讓他們使用 gcloud 指令列工具建立權杖。

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

其中 my-user@example.com 是用於透過 gcloud 進行驗證的電子郵件 (gcloud auth list --format='value(account)')。

Fleet Engine 驗證程式庫

Fleet Engine 使用 JWT 限制在不受信任的環境中存取 Fleet Engine API 的情形。GitHub 上提供的 Fleet Engine 驗證程式庫可簡化 Fleet Engine JWT 的建構程序，並以安全的方式簽署。

這個程式庫提供以下優點：

簡化建立 Fleet Engine 權杖的程序。
提供使用憑證檔案以外的權杖簽署機制 (例如模擬服務帳戶)。

建立授權的 JSON Web Token (JWT)

不使用 Fleet Engine 驗證程式庫時，您必須直接在程式碼集中建構 JWT。為此，您必須深入瞭解 JWT，以及 JWT 與 Fleet Engine 之間的關係。因此，我們強烈建議採用 Fleet Engine 驗證程式庫。

在 Fleet Engine 中，JWT 可提供短期驗證，並確保裝置只能修改已獲得授權的車輛或工作。JWT 含有標頭和憑證附加資訊區段。標頭區段包含要使用的私密金鑰 (從服務帳戶取得) 和加密演算法等資訊。憑證附加資訊部分包含憑證的建立時間、權杖存留時間、權杖要取得存取權的服務，以及限定存取範圍的其他授權資訊，例如運送車輛 ID。

JWT 標頭區段包含下列欄位：

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

JWT 憑證附加資訊區段包含下列欄位：

欄位	說明
`iss`	服務帳戶的電子郵件地址。
`sub`	服務帳戶的電子郵件地址。
`aud`	服務帳戶的 SERVICE_NAME，在本範例中為 https://fleetengine.googleapis.com/
`iat`	權杖建立時間的時間戳記，指定自 1970 年 1 月 1 日 00:00:00 (世界標準時間) 以來經過的秒數。請等候 10 分鐘，讓系統進行偏差。如果時間戳記早於過去或未來的時間，伺服器可能會回報錯誤。
`exp`	權杖到期的時間戳記，指定自 1970 年 1 月 1 日 00:00:00 (世界標準時間) 起，以秒為單位。如果時間戳記在未來一小時以上，要求就會失敗。
`authorization`	視用途而定，可能包含「deliveryvehicleid」、「trackingid」、「taskid」或「taskids」。

建立 JWT 權杖就是進行簽署。如需建立和簽署 JWT 的操作說明和程式碼範例，請參閱不使用 OAuth 的服務帳戶授權。接著，您可以將壓縮的權杖附加至 gRPC 呼叫，或用於存取 Fleet Engine 的其他方法。

JWT 憑證附加資訊

Last Mile Fleet Solution 使用私人憑證附加資訊。使用私人憑證，可以確保只有獲得授權的用戶端可以存取自己的資料。舉例來說，當後端核發送貨驅動程式的行動裝置 JSON Web Token 時，該憑證應包含含有該驅動程式交付車輛 ID 值的 deliveryvehicleid 憑證附加資訊。視駕駛人角色而定，權杖只能針對特定運送車輛 ID，無法使用任何其他任意車輛 ID。

Last Mile Fleet Solution 使用下列私人索賠：

deliveryvehicleid - 呼叫每送車 API 時使用。
taskid：呼叫個別工作的 API 時使用。
taskids：呼叫 BatchCreateTasksAPI 時使用。這項憑證附加資訊必須採用陣列格式，且陣列應包含完成要求所需的所有工作 ID。請勿加入 delivervehicleid、trackingid 或 taskid 憑證附加資訊。
trackingid：呼叫 GetTaskTrackingInfoAPI 時使用。著作權聲明必須與要求中的追蹤 ID 相符。請勿加入 delivervehicleid、taskid 或 taskids 聲明。

您從後端伺服器呼叫 API 時，憑證也必須包含適當的憑證附加資訊，但針對 deliveryvehicleid、taskid 和 trackingid 憑證附加資訊，您可以使用星號 (「*」) 的特殊值。星號 (「*」) 也可用於 taskids 聲明中，但必須是陣列中唯一的元素。

如果您要直接建立並簽署 JSON 做為符記不記名，而非使用 OAuth 2.0 存取權杖，請參閱 Identity Developer 說明文件中不使用 OAuth 的服務帳戶授權操作說明。

將權杖附加至 gRPC 呼叫的機制，取決於進行呼叫的語言和架構。將權杖指定到 HTTP 呼叫的機制，是加入包含不記名權杖的 Authorization 標頭，該權杖的值為權杖。如個別運送追蹤或機群效能用途的授權附註所示。

以下範例顯示後端伺服器中每項工作作業的權杖：

    {
      "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": "*"
       }
    }

以下範例顯示使用者客戶的權杖：

    {
      "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"
       }
    }

以下範例顯示驅動程式應用程式的權杖：

    {
      "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"
       }
    }

針對標頭中的 kid 欄位，指定服務帳戶的私密金鑰 ID。您可以在服務帳戶 JSON 檔案的 private_key_id 欄位中找到這個值。
針對 iss 和 sub 欄位，指定服務帳戶的電子郵件地址。您可以在服務帳戶 JSON 檔案的 client_email 欄位中找到這個值。
在 aud 欄位中，指定 https://SERVICE_NAME/。
針對 iat 欄位，指定憑證建立時間的時間戳記，從世界標準時間 1970 年 1 月 1 日 00:00:00 算起 (以秒為單位)。等待 10 分鐘進行偏差。如果時間戳記距離現在太久 (或未來)，伺服器可能會回報錯誤。
針對 exp 欄位，指定符記到期的時間戳記，從世界標準時間 1970 年 1 月 1 日 00:00:00 起開始以秒為單位。建議值為 iat + 3600。

簽署要傳遞至行動裝置或使用者的權杖時，請務必使用「 Delivery Driver」或「Consumer」角色的憑證檔案。否則，行動裝置或使用者能夠修改或查看不應存取的資訊。