Fleet Engine Auth Library for Java

Fleet Engine use JSON Web Tokens (JWTs) to both authenticate and authorize incoming requests. This process has several aspects to it and is non-trivial to set up.

The Fleet Engine Auth Library provides a set of tools to simplify the setup process. The functionality is best thought of in two buckets, Fleet Engine Roles and JWT Signers.

Sample scripts are provided in the sample directory. To learn more, see: sample/README.md.

You can add the library to your project via Maven or Gradle.

<dependency>
  <groupId>com.google.maps</groupId>
  <artifactId>fleetengine-auth</artifactId>
  <version>(insert latest version)</version>
</dependency>
<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>java-jwt</artifactId>
  <version>3.10.2</version>
</dependency>
<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <version>1.55.0</version>
</dependency>
<dependency>
  <groupId>com.google.auth</groupId>
  <artifactId>google-auth-library-oauth2-http</artifactId>
  <version>0.26.0</version>
</dependency>

dependencies {
  implementation 'com.google.maps:fleetengine-auth:(insert latest version here)'
  implementation 'com.auth0:java-jwt:3.10.2'
  implementation 'com.google.guava:guava:1.55.0'
  implementation 'com.google.auth:google-auth-library-oauth2-http:0.26.0'
}

Fleet Engine Requests are always made on behalf of a service account defined in your GCP project. Each service account is tied a pre-defined Fleet Engine Role.

The supported Fleet Engine roles are:

Each role is tied to a com.google.fleetengine.auth.token.FleetEngineTokenType, and each type of token can be constrained to a specific resource:

The Fleet Engine Auth Library signs JWTs through classes that implement the com.google.fleetengine.auth.token.factory.signer.Signer interface. The Library comes loaded with three predefined Signers which handle the common use cases (the set of pre-defined signers are located below the com.google.fleetengine.auth.token.factory.signer package):

Note: GCP Required denotes that the Signer works with applications that are hosted on GCP or are otherwise authenticated with GCP. For more information, see: https://cloud.google.com/docs/authentication/getting-started.

com.google.fleetengine.auth.AuthTokenMinter ties signers with roles to make minting tokens straightforward.

To use, first associate a Signer with a service account and a type of token.

For example:

AuthTokenMinter minter = AuthTokenMinter.builder()
  .setServerTokenSigner(DefaultServiceAccountSigner.create())
  .setDriverSigner(ImpersonatedAccountSignerCredentials.create("[email protected]")
  .setConsumerSigner(ImpersonatedAccountSignerCredentials.create("[email protected]")
  .build();

The minter provides a getter method for each of the token types. Each getter returns an instance of com.google.fleetengine.auth.token.FleetEngineToken:

FleetEngineToken serverToken = minter.getServerToken();

FleetEngineToken consumerToken = minter.getConsumerToken(TripClaims.create("trip-id-123"));

FleetEngineToken driverToken = minter.getDriverToken(VehicleClaims.create("vehicle-id-123"));

A FleetEngineToken has several attributes, but in most cases, only the base64 encoded JWT is needed com.google.fleetengine.auth.token.FleetEngineToken#jwt.

System.out.println("Base64 encoded JWT:");
System.out.println(serverToken.jwt());

System.out.println("HTTP Header:");
System.out.println(String.format("Authorization: Bearer %s", token.jwt()));

Output:

Base64 encoded JWT:
xxxxx.yyyyy.zzzzz

HTTP Header:
Authorization: Bearer xxxxx.yyyyy.zzzzz

Alongside token minting functionality, the library also provides a set of components that work with Fleet Engine protobuf generated classes. There are two sets of generated classes that make requests to the fleet engine server, gRPC stubs and GAPIC clients.

Both mechanisms require a FleetEngineTokenProvider which is an interface that has just one method:

package com.google.fleetengine.auth.client;

/** Provides non-expired, signed JWTs. */
public interface FleetEngineTokenProvider {
  /** Returns a non-expired {@link FleetEngineToken} with a base64 signed JWT. */
  FleetEngineToken getSignedToken() throws SigningTokenException;
}

For convenience, com.google.fleetengine.auth.AuthTokenMinter implements FleetEngineTokenProvider and returns server tokens when called through FleetEngineTokenProvider#getSignedToken. Any type of token can be returned.

gRPC stubs are initialized from io.grpc.ManagedChannels and allows functionality to be injected using interceptors:

FleetEngineTokenProvider fleetEngineTokenProvider = getTokenProvider();

ManagedChannel channel = ManagedChannelBuilder.forTarget(fleetEngineAddress)
  .intercept(FleetEngineAuthClientInterceptor.create(fleetEngineTokenProvider))
  .build();

VehicleServiceBlockingStub stub = VehicleServiceGrpc.newBlockingStub(channel);

GAPIC clients are configured using com.google.api.gax.rpc.ClientSettings which are built with using a builder. The com.google.fleetengine.auth.client.FleetEngineClientSettingsModifier updates ClientSettings.Builders such that outbound requests made from the corresponding client have valid authorization headers.

FleetEngineClientSettingsModifier<VehicleServiceSettings, VehicleServiceSettings.Builder> modifier =
  new FleetEngineClientSettingsModifier<>(tokenProvider);

VehicleServiceSettings.Builder builder = VehicleServiceSettings.newBuilder();
VehicleServiceSettings settings = modifier.updateBuilder(builder).build();

VehicleServiceClient client = VehicleServiceClient.create(settings);