颁发 JSON Web 令牌

本文档介绍了如何在支持 Web 应用和移动应用访问 Fleet Engine 数据的过程中颁发 JSON Web 令牌。如果您尚未阅读，请参阅车队引擎中的安全部分下的 JSON Web 令牌。借助 Fleet Engine 服务，您可以通过以下任一方式颁发 JWT：

• 使用授权库 - 如果您的代码库是使用 Java 编写的，Google 建议您使用此方法。此库可为您处理服务可能需要的所有用例场景处理 JWT 颁发事宜，并大大简化了您的实现。
• 创建您自己的 JWT - 如果您无法使用我们的 JWT 库，则需要将其构建到您自己的代码库中。本部分提供了适用于每种情况的各种 JWT 示例。

JWT 的工作原理

对于不可信环境（例如移动电话和网络浏览器），您的后端服务器会发出 JWT，其运作方式如下：

• 在低信任环境中运行的客户端代码会调用在完全受信任环境中运行的服务器代码，以请求将适当的 JWT 传递给车队引擎。

• JWT 与服务账号相关联，因此发送到车队引擎的请求会隐式与签署 JWT 的服务账号相关联。

• JWT 声明会进一步限制客户端可以操作的资源，例如特定车辆、行程或任务。

使用 Java 版授权库

如需使用 Java 版 Fleet Engine 授权库，请访问 GitHub 代码库。该库简化了 Fleet Engine JWT 的构建并对其进行安全签名。它提供以下功能：

• 项目依赖项声明
• 按需行程或计划任务的所有服务账号角色的完整列表
• 令牌签名机制（使用凭据文件以外的方式），例如模拟服务账号
• 将已签名令牌附加到通过 gRPC 桩或 Google API Codegen (GAPIC) 客户端库发出的出站请求
• 有关将 signer 与 Fleet Engine 客户端库集成的说明

如果您从代码中发出 JWT

如果您无法使用 Java 版授权库，则必须在自己的代码库中实现 JWT。本部分提供了一些有关创建自定义令牌的指南。如需查看 JWT 字段和声明的列表，请参阅车队引擎中的安全部分下的 JSON Web 令牌。如需了解车队引擎使用的服务账号角色，请参阅服务账号角色。如需查看按需行程或计划任务的 JWT 示例列表，请参阅以下部分。

常规指南

• 使用适当的服务账号和角色。服务账号和关联的角色可确保请求令牌的用户有权查看令牌授予其访问权限的信息。具体而言：
  • 如果要为要传递给移动设备的 JWT 签名，请使用适用于 Driver 或 Consumer SDK 角色的服务账号。否则，移动设备可能会更改和访问其无权访问的数据。
  • 如果要为用于特权调用的 JWT 签名，请在使用 ADC 或 JWT 时使用具有正确 Fleet Engine Admin 角色的服务账号。否则，操作将失败。
• 仅分享创建的令牌。切勿分享用于创建令牌的凭据。
• 对于 gRPC 调用，附加令牌的机制取决于用于进行调用的语言和框架。向 HTTP 调用指定令牌的机制是，在 Authorization 标头中添加一个值为令牌的 Bearer 令牌。
• 返回过期时间。您的服务器必须返回令牌的过期时间，通常以秒为单位。
• 如果您需要直接作为令牌持有者创建和签署 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": "[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 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）进行后端服务器操作，请参阅安全概览。