JSON Web Tokens

A JSON Web Token (JWT) is an open web standard that's used for authenticating and authorizing information exchanges between a client and a server. When an app user first signs in with the appropriate role credentials, the server creates and returns an encoded, digitally-signed JWT for use with subsequent requests. This process both authenticates the user and authorizes them to access routes, services, and resources based on their account role.

Fleet Engine requires the use of JSON Web Tokens (JWTs) for API method calls from low-trust environments: smartphones and browsers.

A JWT originates on your server, is signed, encrypted, and passed to the client for subsequent server interactions until it expires or is no longer valid.

Key details

• Use Application Default Credentials to authenticate and authorize against Fleet Engine.
• Use an appropriate service account to sign JWTs. See Fleet Engine serviceaccount roles in Fleet Engine Basics.

Unlike API keys, JWTs are short lived and limit operations to only those that the role is authorized to perform. For more information on JWTs, see JSON Web Tokens on Wikipedia. For detail on access roles, see Service account roles in this guide.

JWT elements

JWTs contain a header and a claim section. The header section contains information such as the private key obtained from service accounts, and the encryption algorithm. The claim section contains information such as the JWT's create time, time to live, the services that the JWT claims access to, and other authorization information to scope access; for example, the delivery vehicle ID.

The following table provides descriptive details about JWT fields in general, as well as specific information about where you can find the values for these fields in your Fleet Engine Cloud project.

JWT header fields

Field	Description
alg	The algorithm to use. `RS256`.
typ	The type of token. `JWT`.
kid	Your service account's private key ID. You can find this value in the private_key_id field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions.

JWT claims fields

Field	Description
iss	Your service account's email address, found in the client_email field of your service account JSON file.
sub	Your service account's email address, found in the client_email field of your service account JSON file.
aud	Your service account's SERVICE_NAME, in this case https://fleetengine.googleapis.com/
iat	The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 UTC, January 1, 1970. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error.
exp	The timestamp when the JWT expires, specified in seconds elapsed since 00:00:00 UTC, January 1, 1970. The request fails if the timestamp is more than one hour in the future.
authorization	Depending on the use case, may contain deliveryvehicleid, trackingid, taskid, or taskids. If specifying taskids, the authorization scope must be an array in one of the following forms: "taskids": ["task_id_one","task_id_two"] or "taskids": ["*"]

Fleet Engine JWT claims

Fleet Engine uses private claims. Using private claims ensures that only authorized clients can access their own data.

For example, when your server issues a JSON Web Token for a driver's mobile device, it should contain either the vehicleid claim or the deliveryvehicleid claim with the value of that driver's vehicle ID. Then, depending on the driver role, JWTs enable access only for the specific vehicle ID and not any other arbitrary vehicle ID.

Fleet Engine uses the following private claims:

What's next

• Read about Fleet Engine security design to understand the complete authentication flow.
• Learn how to Issue JSON Web Tokens from your server.