Issue JSON Web Tokens

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 or tripid 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 and deliveryvehicleids. To do this, you add an additional claim in the authorization section with the keys taskid and deliveryvehicleid.
- When using the asterisk (*) in the taskids claim, it must be the only element in the array.

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.

Note: The token created using this role grants some permissions to Fleet Engine entities. Make sure your backend only shares the token with authenticated users.

   {
      "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