颁发 JSON Web 令牌

本文档介绍了如何签发 JSON Web 令牌，以便让基于 Web 和移动设备的应用能够访问 Fleet Engine 数据。如果您尚未阅读 Fleet Engine 中的安全性部分下的 JSON Web 令牌，请先阅读。借助 Fleet Engine 服务，您可以通过以下任一方式签发 JWT：

• 使用授权库 - 如果您的代码库是用 Java 编写的，Google 建议您使用此方法。此库会处理您可能需要通过该服务实现的所有应用场景的 JWT 签发，并大大简化您的实现。
• 创建您自己的 JWT - 如果您无法使用我们的 JWT 库，则需要将这些库构建到您自己的代码库中。本部分提供了每种场景的 JWT 的各种示例。

JWT 的工作原理

对于不可信的环境（例如手机和网络浏览器），您的后端服务器会发出 JWT，其工作原理如下：

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

• JWT 与服务账号相关联，因此发送到 Fleet Engine 的请求会隐式与对 JWT 进行签名的服务账号相关联。

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

使用 Java 版授权库

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

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

如果您通过代码签发 JWT

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

一般准则

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

用于跟踪车队中所有任务和车辆的示例令牌

以下示例是一个令牌，用于从操作员使用的基于 Web 的应用中跟踪车队中的所有任务和车辆。这些操作所需的权限高于客户端应用。如需了解使用此令牌的客户端实现，请参阅设置 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）进行后端服务器操作，请参阅安全概览。