JSON Web 令牌
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
JSON Web 令牌 (JWT) 是一种开放式 Web 标准,用于对客户端与服务器之间的信息交换进行身份验证和授权。当应用用户首次使用适当的角色凭据登录时,服务器会创建并返回一个经过编码的数字签名 JWT,以供后续请求使用。此流程既可对用户进行身份验证,也可根据用户的账号角色授权其访问路由、服务和资源。
对于来自低信任环境(智能手机和浏览器)的 API 方法调用,Fleet Engine 要求使用 JSON Web 令牌 (JWT)。
JWT 源自您的服务器,经过签名和加密后传递给客户端,以供后续服务器交互使用,直到过期或不再有效为止。
关键细节
与 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
声明。
后续步骤
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-31。
[null,null,["最后更新时间 (UTC):2025-08-31。"],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]