本文档介绍了在启用 Web 的过程中如何颁发 JSON Web 令牌 和移动应用可访问 Fleet Engine 数据。如果您还没有这样做 请阅读舰队引擎中的安全性下的 JSON Web 令牌 部分。借助 Fleet Engine 服务,您可以使用以下任一种方式颁发 JWT 方式:
- 使用授权库:如果您的代码库是用 Java 编写的,Google 建议您使用此方法。此库负责为以下对象签发 JWT 服务的所有用例场景, 可以简化实现流程
- 创建自己的 JWT - 如果您无法使用我们的 JWT 库,则需要 将这些代码构建到您自己的代码库中。本部分介绍了 每种场景的 JWT 示例。
JWT 的工作原理
对于不受信任的环境(例如手机和网络浏览器),您的后端 服务器会颁发如下所示的 JWT:
在低可信环境中运行的客户端代码会调用您的服务器上 在完全受信任的环境中运行的代码,以请求适当的 JWT 传递给 Fleet Engine
由于 JWT 与服务账号关联,因此请求会发送到 Fleet Engine 与签名 JWT 的服务账号隐式关联。
JWT 声明进一步限制客户端可以操作的资源 例如特定车辆、行程或任务。
使用适用于 Java 的授权库
要使用适用于 Java 的 Fleet Engine 授权库,请访问 GitHub 代码库。该库简化了 Fleet Engine 的构建 JWT 并对其进行安全签名。它提供以下功能:
- 项目依赖项声明
- 按需行程或 计划任务
- 令牌签名机制(而非使用凭据文件),例如 模拟服务账号
- 将已签名令牌附加到通过 gRPC 桩或 Google API Codegen (GAPIC) 客户端库发出的出站请求
- 将签名者与 Fleet Engine 客户端库集成的说明
如果您通过代码颁发 JWT
如果您无法使用适用于 Java 的授权库,则必须在 构建自己的代码库本部分提供了一些有关如何自行创建 词元。请参阅 Fleet Engine 中的安全性部分下方的 JSON Web 令牌 获取 JWT 字段和声明列表。请参阅服务账号 角色。请参阅 以下部分列出了按需行程或 计划任务。
常规指南
- 使用适当的服务账号和角色。服务账号和
关联的角色可确保请求令牌的用户有权
查看令牌授予他们访问权限的信息。具体而言:
- 如果要对要传递给移动设备的 JWT 进行签名,请使用该服务 或 Consumer SDK 角色的用户。否则, 设备可以更改和访问其无权访问的数据。
- 如果要为要用于特权调用的 JWT 签名,请使用此服务 账号拥有正确的 Fleet Engine Admin 角色。 否则,操作将失败。
- 仅分享创建的令牌。切勿分享用于创建令牌的凭据。
- 对于 gRPC 调用,附加令牌的机制取决于
用于进行调用的语言和框架。向 HTTP 调用指定令牌的机制是,在
Authorization
标头中添加一个值为令牌的 Bearer 令牌。 - 返回过期时间。您的服务器必须针对 令牌,通常在几秒内完成。
- 如果您需要直接创建 JSON 并作为令牌不记名者对 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 示例。
用于跟踪车队中所有任务和车辆的示例令牌
以下示例是一个令牌,用于跟踪 舰队。所需的权限 都比客户端应用的效率高出一倍请参阅 为客户端设置 JavaScript 舰队跟踪库 会使用此令牌的实现:
使用
Fleet Engine Delivery Fleet Reader
Cloud 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": "*" } }