颁发 JSON Web 令牌

本文档介绍了在启用 Web 的过程中如何颁发 JSON Web 令牌 和移动应用可访问 Fleet Engine 数据。如果您还没有这样做 请阅读舰队引擎中的安全性下的 JSON Web 令牌 部分。借助 Fleet Engine 服务，您可以使用以下任一种方式颁发 JWT 方式：

• 使用授权库：Google 建议您使用此方法 使用 Java 编写的代码库。此库负责为以下对象签发 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 的授权库，则必须在 构建自己的代码库本部分提供了一些有关如何自行创建 词元。请参阅 Fleet Engine 中的安全性部分下方的 JSON Web 令牌 获取 JWT 字段和声明列表。请参阅服务账号 角色。请参阅 以下部分列出了按需行程或 计划任务。

常规指南

• 使用适当的服务账号和角色。服务账号和 关联的角色可确保请求令牌的用户有权 查看令牌授予他们访问权限的信息。具体而言：
  • 如果要对要传递给移动设备的 JWT 进行签名，请使用该服务 或 Consumer SDK 角色的用户。否则， 设备可以更改和访问其无权访问的数据。
  • 如果要为要用于特权调用的 JWT 签名，请使用此服务 账号拥有正确的 Fleet Engine Admin 角色。 否则，操作将失败。
• 仅共享创建的令牌。切勿向他人透露 创建令牌。
• 对于 gRPC 调用，附加令牌的机制取决于 用于进行调用的语言和框架。用于指定 添加带有不记名的 Authorization 标头 词元，其值是该词元。
• 返回过期时间。您的服务器必须针对 令牌，通常在几秒内完成。
• 如果您需要直接创建 JSON 并作为令牌不记名者对 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 对令牌签名 角色。

  注意 ：使用此角色创建的令牌可向舰队授予一些权限 引擎实体。确保您的后端仅与 经过身份验证的用户。

   {
      "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）执行后端服务器操作， 请参阅安全概览。