颁发 JSON Web 令牌

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

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

JWT 的工作原理

对于不受信任的环境（例如手机和 Web 浏览器），您的后端服务器会发布 JWT，其工作方式如下：

在低信任环境中运行的客户端代码会调用在完全信任环境中运行的服务器代码，以请求要传递给 Fleet Engine 的相应 JWT。
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 或 Consumer SDK 角色的服务账号。否则，移动设备可能会更改和访问它不应访问的数据。
- 如果要对用于特权调用的 JWT 进行签名，请在使用 ADC 或 JWT 时使用具有正确 Fleet Engine 管理员角色的服务账号。否则，操作会失败。
仅共享创建的令牌 。切勿共享用于创建令牌的凭据。
对于 gRPC 调用，附加令牌的机制取决于用于进行调用的语言和框架。为 HTTP 调用指定令牌的机制是包含一个 Authorization 标头，其中包含一个不记名令牌，其值为令牌。
返回过期时间。您的服务器必须返回令牌的过期时间，通常以秒为单位。
如果您需要直接创建 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": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "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": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "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": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "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": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

车队运营的 JWT 示例

本部分提供了一个车队运营典型场景的 JWT 示例。

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

以下示例是一个令牌，用于跟踪运营人员使用的基于 Web 的应用中的车队中的所有任务和车辆。这些操作所需的权限高于客户端应用。如需了解将使用此令牌的客户端实现，请参阅设置 JavaScript Fleet Tracking 库：

使用 Fleet Engine Delivery Fleet Reader Cloud IAM 角色对令牌进行签名。

注意：使用此角色创建的令牌会向 Fleet Engine 实体授予一些权限。请确保您的后端仅与经过身份验证的用户共享令牌。

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "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": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "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": "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": "*"
       }
    }

后续步骤

验证您的设置，以便创建试用车辆并确保令牌按预期工作
如需了解如何使用 ADC 而不是 JWT 进行后端服务器操作，请参阅安全性概览。