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.

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 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 driver app operation

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
      "sub": "[e-mail]",
      "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": "[e-mail]",
      "sub": "[e-mail]",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

Note: The trackingid claim is the shipment tracking ID.

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.

  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": "[e-mail]",
      "sub": "[e-mail]",
      "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": "[e-mail]",
    "sub": "[e-mail]",
    "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": "[e-mail]",
      "sub": "[e-mail]",
      "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": "[e-mail]",
      "sub": "[e-mail]",
      "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": "[e-mail]",
      "sub": "[e-mail]",
      "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.