JSON Web 令牌

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

对于从低信任环境进行的 API 方法调用，车队引擎要求使用由适当服务账号签名的 JSON Web 令牌 (JWT)。低信任环境包括智能手机和浏览器。JWT 源自您的服务器，即完全受信任的环境。JWT 会经过签名和加密，并传递给客户端以供后续与服务器的互动，直到其过期或失效为止。

您的后端应使用标准应用默认凭据机制对 Fleet Engine 进行身份验证和授权。请务必使用由适当服务账号签名的 JWT。如需查看服务账号角色列表，请参阅车队引擎基础知识中的车队引擎服务账号角色。

与之相反，您的后端应使用标准应用默认凭据机制对 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 始终都会使用此声明。车队引擎后端会先确保车辆与所请求的行程相关联，然后再进行修改。
  • JWT 可以涵盖车辆和行程操作（即使不需要），这可能会简化 JWT 签名实现。
• tripid：
  • 消费者 SDK 始终使用此声明。
  • JWT 可以涵盖车辆和行程操作，即使不需要也可以，这可能会简化令牌签名实现。

计划任务

• deliveryvehicleid

  在调用按运输车辆的 API 时使用。

• taskid

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

• taskids

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

• trackingid

  调用 GetTaskTrackingInfoAPI 时使用。声明必须与请求中的跟踪 ID 一致。请勿添加 delivervehicleid、taskid 或 taskids 声明。

后续步骤

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