JSON Web 令牌

JSON Web 令牌 (JWT) 是一种开放式 Web 标准，用于对客户端和服务器之间的信息交换进行身份验证和授权。当应用用户首次使用适当的角色凭据登录时，服务器会创建并返回一个经过编码的数字签名 JWT，以供后续请求使用。此过程既可对用户进行身份验证，也可根据用户的账号角色授权其访问路由、服务和资源。

对于来自低信任环境（智能手机和浏览器）的 API 方法调用，Fleet Engine 要求使用 JSON Web 令牌 (JWT)。

JWT 源自您的服务器，经过签名、加密并传递给客户端，以供后续服务器交互使用，直到过期或不再有效。

关键细节

• 使用应用默认凭据针对 Fleet Engine 进行身份验证和授权。
• 使用适当的服务账号对 JWT 进行签名。请参阅 Fleet Engine 基础知识中的 Fleet Engine 服务账号角色。

与 API 密钥不同，JWT 的有效期较短，并且仅允许角色有权执行的操作。如需详细了解 JWT，请参阅 Wikipedia 上的 JSON Web 令牌。如需详细了解访问权限角色，请参阅本指南中的服务账号角色。

JWT 元素

JWT 包含标头和声明部分。标头部分包含从服务账号获取的私钥和加密算法等信息。声明部分包含 JWT 的创建时间、存留时间、JWT 声称有权访问的服务以及其他用于限定访问范围的授权信息（例如配送车辆 ID）等信息。

下表提供了有关 JWT 字段的一般说明性详细信息，以及有关如何在 Fleet Engine Cloud 项目中查找这些字段的值的具体信息。

JWT 标头字段

字段	说明
alg	要使用的算法。`RS256`。
typ	令牌的类型。`JWT`。
儿童	服务账号的私钥 ID。您可以在服务账号 JSON 文件的 private_key_id 字段中找到此值。请务必使用具有正确权限级别的服务账号的密钥。

JWT 声明字段

字段	说明
iss	服务账号的电子邮件地址，可在服务账号 JSON 文件的 client_email 字段中找到。
sub	服务账号的电子邮件地址，可在服务账号 JSON 文件的 client_email 字段中找到。
aud	您的服务账号的 SERVICE_NAME，在本例中为 https://fleetengine.googleapis.com/
iat	JWT 的创建时间戳，以自 00:00:00 UTC, January 1, 1970 以来经过的秒数指定。允许 10 分钟偏差。 如果时间戳距现在过于久远（遥远的过去或未来），服务器可能会报告错误。
exp	JWT 过期时的时间戳，以自 00:00:00 UTC, January 1, 1970 以来经过的秒数指定。如果时间戳比当前时间晚一个小时以上，则请求会失败。
授权	根据使用情形，可能包含 deliveryvehicleid、trackingid、taskid 或 taskids。 如果指定了 taskid，则授权范围必须是采用以下形式之一的数组： "taskids": ["task_id_one","task_id_two"] 或 "taskids": ["*"]

Fleet Engine JWT 声明

Fleet Engine 使用私有声明。使用私有声明可确保只有获授权的客户端才能访问自己的数据。

例如，当您的服务器为司机的移动设备签发 JSON Web 令牌时，该令牌应包含 vehicleid 声明或 deliveryvehicleid 声明，且后者的值为相应司机的车辆 ID。然后，根据驾驶员角色，JWT 仅允许访问特定车辆 ID，而不允许访问任何其他任意车辆 ID。

Fleet Engine 使用以下私有声明：

按需行程

• vehicleid：
  • 无论是在行程中还是在车辆中操作，Driver SDK 始终使用此声明。Fleet Engine 后端会确保车辆与所请求的行程相关联，然后再进行修改。
  • JWT 可以涵盖车辆和行程操作，即使不是必需的，这也可以简化 JWT 签名实现。
• tripid：
  • Consumer SDK 始终使用此声明。
  • JWT 可以涵盖车辆和行程操作，即使不是必需的也是如此，这可能会简化令牌签名实现。

计划任务

• deliveryvehicleid

  在调用按配送车辆 API 时使用。

• taskid

  在调用每个任务的 API 时使用。

• taskids

  在调用 BatchCreateTasksAPI 时使用。此声明必须采用数组形式，并且该数组应包含完成请求所需的所有任务 ID。请勿包含 delivervehicleid、trackingid 或 taskid 声明。

• trackingid

  在调用 GetTaskTrackingInfoAPI 时使用。相应声明必须与请求中的跟踪 ID 一致。请勿包含 delivervehicleid、taskid 或 taskids 声明。

后续步骤

• 请参阅 Fleet Engine 安全设计，了解完整的身份验证流程。
• 了解如何从服务器签发 JSON Web 令牌。