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.
How JWTs work
For untrusted environments, such as mobile phones and web browsers, your backend server issues JWTs that work as follows:
Your client code running in a low-trust environment calls on your server code running in a fully-trusted environment to request the appropriate JWT to pass to Fleet Engine.
JWTs are associated with service accounts, so requests sent to Fleet Engine are implicitly associated with the service account that signed the JWT.
JWT claims further restrict the resources that the client may operate on, such as specific vehicles, trips, or tasks.
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
- A 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 Google API Codegen (GAPIC) client library
- Instructions on integrating the signers with Fleet Engine client libraries
If you issue JWTs from your code
If 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 JWT fields and claims. See Service account roles for the service account roles used by Fleet Engine. See the following section for a list of JWT examples for either on-demand trips or scheduled tasks.
General guidelines
- Use appropriate service accounts and roles. The service account and
associated role ensures that the user requesting the token is authorized to
view the information that the token grants them access to. Specifically:
- If signing a JWT to be passed to a mobile device, use the service account for the Driver or Consumer SDK role. Otherwise, the mobile device can alter and access data it should not have access to.
- If signing the JWT to be used for privileged calls, use the service account with the correct Fleet Engine Admin role when using ADC or JWTs. Otherwise, the operation fails.
- 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.
- If you need 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 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 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"
}
}
JWT examples for fleet operations
This section provides a JWT example for a typical scenario in fleet operations.
Example token to track all tasks and vehicles in a fleet
The following example is a token that tracks all tasks and vehicles in the fleet from a web-based app used by an operator. The permissions required for these operations is greater than for client applications. 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": "*",
}
}
Alternative authentication method for backend server operations
Google recommends you use ADC to authenticate backend server operations. If you cannot use ADC and need to use JWTs, refer to these examples.
Example token for an on-demand 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 scheduled 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 scheduled 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 scheduled 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": "*" } }
What's next
- Verify your setup so that you can create a trial vehicle and ensure your tokens are working as intended
- For information on using ADC instead of JWTs for backend server operations, see the Security overview.