本文档介绍了如何签发 JSON Web 令牌，以便让基于 Web 和移动设备的应用程序能够访问 Fleet Engine 数据。如果您尚未阅读，请阅读Fleet Engine 中的安全性部分下的 JSON Web 令牌。借助 Fleet Engine 服务，您可以通过以下方式之一签发 JWT：
- 使用授权库 - 如果您的代码库是用 Java 编写的，Google 建议您使用此方法。此库可处理您可能需要的所有服务使用情形的 JWT 发布，并大大简化您的实现。
- 创建您自己的 JWT - 如果您无法使用我们的 JWT 库，则需要将这些功能构建到您自己的代码库中。本部分提供了各种场景下的 JWT 示例。
JWT 的运作方式
对于不受信任的环境（例如手机和 Web 浏览器），后端服务器会签发 JWT，其工作方式如下：
在低信任环境中运行的客户端代码会调用在完全信任环境中运行的服务器代码，以请求要传递给 Fleet Engine 的相应 JWT。
JWT 与服务账号相关联，因此发送到 Fleet Engine 的请求会隐式与签署 JWT 的服务账号相关联。
JWT 声明进一步限制了客户端可以操作的资源，例如特定车辆、行程或任务。
使用 Java 版授权库
如需使用 Java 版 Fleet Engine 授权库，请访问 GitHub 代码库。该库可简化 Fleet Engine JWT 的构建并对其进行安全签名。它提供以下功能：
- 项目依赖项声明
- 适用于按需行程或预定任务的所有服务账号角色的完整列表
- 使用凭据文件以外的令牌签名机制，例如模拟服务账号
- 将签名令牌附加到通过 gRPC stub 或 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 Admin 角色的服务账号。否则，操作将失败。
- 仅分享已创建的令牌。切勿分享用于创建令牌的凭据。
- 对于 gRPC 调用，附加令牌的机制取决于用于进行调用的语言和框架。为 HTTP 调用指定令牌的机制是包含一个
Authorization标头，其中包含一个值为令牌的持有者令牌。 - 返回到期时间。您的服务器必须返回令牌的到期时间，通常以秒为单位。
- 如果您需要直接创建和签署 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": "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 ReaderCloud IAM 角色对令牌进行签名。
{
"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": "*" } }