This document covers how to issue JSON Web Tokens as part of enabling your web and mobile-based apps access to Fleet Engine data. If you have not done so already, read JSON Web Tokens under the Security in Fleet Engine section. With the Fleet Engine service, you can issue JWTs in one of the following ways:
- Use the authorization library—Google recommends you use this approach when your codebase is written in Java. This library handles issuing JWTs for all use-case scenarios you might need with the service and greatly simplifies your implementation.
- Create your own JWTs—If you cannot use our JWT library, you will need to build these into your own codebase. This section provides the various examples of JWTs for each scenario.
Use the authorization library for Java
To use the Fleet Engine authorization library for Java, visit the GitHub repository. The library simplifies construction of Fleet Engine JWTs and securely signs them. It provides the following:
- Project dependency declarations
- Full list of all service account roles for either on-demand trips or scheduled tasks
- Token signing mechanisms other than using credential files, such as impersonating a service account
- Attaches signed tokens to outbound requests made from either a gRPC stub or a GAPIC client
- Instructions on integrating the signers with Fleet Engine client libraries
If you issue JWTs from your code
When you cannot use the authorization library for Java, you must implement JWTs in your own codebase. This section provides a few guidelines for creating your own tokens. See JSON Web Tokens under the Security in Fleet Engine section for a list of the service account roles and JWT fields and claims. See the following section for a list of JWT examples for either on-demand trips or scheduled tasks.
General guidelines
- Use appropriate roles. This ensure that the user requesting the token is
authorized to view the information that the token grants them access to.
Specifically:
- When signing the JWT to be passed to a mobile device, use the service account for the Driver or Consumer SDK role. Otherwise, the mobile device will have the ability to alter state it should not have.
- Likewise, when signing the JWT to be used for privileged calls, make sure to use the service account with the correct Fleet Engine Admin role. Otherwise, the operation will fail.
- Only share the created tokens. Never share the credentials used to create the tokens.
- For gRPC calls, the mechanism for attaching the token depends on the
language and framework used to make the call. The mechanism for specifying a
token to an HTTP call is to include an
Authorization
header with a bearer token whose value is the token. - Return an expiry time. Your server must return an expiry time for the token, typically in seconds.
- To create and sign a JSON directly as a token bearer, rather than using OAuth 2.0 access tokens, read the instructions for Service account authorization without OAuth in the Identity Developer documentation.
For on-demand trips
- When creating the JWT payload, add an additional claim in the authorization
section with the key
vehicleid
ortripid
set to the value of the vehicle ID or trip ID for which the call is being made.
For scheduled tasks
- When your server calls other APIs, the tokens must also contain the
appropriate claim. For this, you can do the following:
- Set the value of each key to
*
. - Grant the user access to all
taskids
anddeliveryvehicleids
. To do this, you add an additional claim in the authorization section with the keystaskid
anddeliveryvehicleid
. - When using the asterisk (
*
) in thetaskids
claim, it must be the only element in the array.
- Set the value of each key to
JWT examples for on-demand trips
This section provides JWT examples for common scenarios if you use on-demand trips.
Example token for a backend server operation
{
"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": "*"
}
}
Example token for a driver app operation
{
"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"
}
}
Example token for a consumer app operation
{
"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 examples for scheduled tasks
This section provides JWT example for typical scenarios if you use scheduled tasks.
Example token for a backend server operation
{
"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": "*"
}
}
Example token for a backend server batch create tasks operation
{
"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": ["*"]
}
}
Example token for a backend server per-delivery-vehicle operation
{
"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": "*"
}
}
Example token for a driver app
{
"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"
}
}
Example token for a consumer app
{
"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"
}
}
Example token to track all tasks and vehicles
The following example is a token that tracks all tasks and vehicles in the fleet. See Set up the JavaScript Fleet Tracking Library for the client-side implementation that would use this token:
Sign the token using the
Fleet Engine Delivery Fleet Reader
Cloud IAM role.
{
"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": "*",
}
}
What's next
- Verify your setup so that you can create a trial vehicle and ensure your tokens are working as intended