驗證及授權

本節說明 Fleet Engine 實作的相關驗證和授權概念。其中詳細說明保護 Fleet Engine 函式呼叫所需的程序。

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

總覽

Fleet Engine 是授權機制的一部分，因此可從低信任環境的呼叫提供額外的安全防護。低信任的環境包括智慧型手機和瀏覽器。此外，Fleet Engine 也採用最低權限原則，在這類呼叫中，應只授予完成工作所需的權限。

為保護源自低信任環境的函式呼叫，Google 設計了一項機制，程式碼會在後端伺服器建立權杖，這個機制是完全可靠的環境。每個呼叫均提供完整的安全性說明，然後加密至您隨任何環境呼叫傳遞的 JWT 中。

驗證設計原則

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

  • IAM 角色會定義呼叫端允許的活動範圍。舉例來說，SuperUser 角色可執行所有操作，而「不信任的驅動程式」角色則只能執行最少的位置更新作業。

  • IAM 角色與服務帳戶相關聯。

  • JWT 憑證附加資訊會進一步限制呼叫端可執行的實體。可以是特定工作或運輸車輛。

  • 傳送至 Fleet Engine 的要求一律包含 JWT。

    • 由於 JWT 與服務帳戶相關聯，因此傳送至 Fleet Engine 的要求會直接連結至與 JWT 相關聯的服務帳戶。

  • 為了請求適當的 JWT，您可以將 JWT 傳送至 Fleet Engine，在低信任環境中執行的程式碼必須先呼叫在完全受信任的環境中執行的程式碼。

  • Fleet Engine 會執行下列安全性檢查：

    1. 與服務帳戶關聯的 IAM 角色可為呼叫端提供正確授權，方便發出 API 呼叫。

    2. 要求中傳送的 JWT 憑證附加資訊提供了正確的授權，可讓呼叫端在實體上執行作業。

驗證流程

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

  1. 機群管理員會建立服務帳戶。

  2. 機群管理員會將特定的 IAM 角色指派給服務帳戶。

  3. 機群管理員會使用服務帳戶設定後端。

  4. 用戶端應用程式會從合作夥伴的後端要求 JWT。要求者可以是驅動程式應用程式、消費者應用程式或監控應用程式。

  5. Fleet Engine 會為每個服務帳戶發出 JWT。用戶端應用程式會收到 JWT。

  6. 用戶端應用程式會根據在設定階段獲派的 IAM 角色，使用 JWT 連線至 Fleet Engine 讀取或修改資料。

驗證序列圖表

Cloud 專案設定

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

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

  1. 使用 Google Cloud 控制台建立 Google Cloud 專案。
  2. 使用 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.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 的建構過程，並安全地簽署這些 JWT。

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

  • 簡化建立 Fleet Engine 權杖的程序。
  • 提供非使用憑證檔案 (例如模擬服務帳戶) 的權杖簽署機制。
  • 這個外掛程式能將已簽署的權杖附加至從 gRPC 虛設常式或 GAPIC 用戶端發出的傳出要求。

建立 JSON Web Token (JWT) 做為授權

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

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

JWT 標頭部分包含下列欄位：

欄位說明
alg 要使用的演算法。`RS256`。
typ 權杖類型。「JWT」。
兒童 服務帳戶的私密金鑰 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 (世界標準時間) 起經過的秒數。如果時間戳記在未來超過一小時內，要求就會失敗。
授權 視用途而定，可能會包含「Delivervehicleid」、「trackingid」、「taskid」或「taskids」。

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

JWT 憑證附加資訊

Last Mile Fleet Solution 使用私人聲明。使用私人憑證可確保只有獲授權的用戶端能夠存取自己的資料。舉例來說，當後端為送貨司機的行動裝置發出 JSON Web Token 時，該權杖應包含 deliveryvehicleid 憑證附加資訊，以及該駕駛車輛送貨車 ID 的值。然後，視駕駛人角色而定，權杖只能存取特定車輛 ID，而非任何其他任意車輛 ID。

Last Mile Fleet Solution 使用下列私人版權聲明：

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

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

若要直接建立並簽署 JSON 做為憑證記號 (而不是使用 OAuth 2.0 存取權杖)，請參閱 Identity Developer 說明文件中不含 OAuth 的服務帳戶授權相關說明。

將權杖附加到 gRPC 呼叫的機制，會因用於呼叫的語言和架構而異。為 HTTP 呼叫指定權杖的機制，是加入含有不記名權杖的授權標頭，該標頭的值為權杖，如個別運送追蹤或機群效能用途的授權注意事項中所述。

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

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

簽署要傳遞至行動裝置或使用者的權杖時，請務必使用「交付驅動程式」或「消費者」角色的憑證檔案。否則，行動裝置或使用者將能夠變更或查看他們無權存取的資訊。