{"id":28919529,"url":"https://github.com/googlemaps/java-fleetengine-auth","last_synced_at":"2025-10-06T20:42:37.898Z","repository":{"id":38189177,"uuid":"402505082","full_name":"googlemaps/java-fleetengine-auth","owner":"googlemaps","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-27T00:53:06.000Z","size":1209,"stargazers_count":12,"open_issues_count":2,"forks_count":8,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-21T08:14:06.062Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googlemaps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-02T17:21:59.000Z","updated_at":"2025-04-04T04:10:30.000Z","dependencies_parsed_at":"2023-11-06T22:58:36.956Z","dependency_job_id":"b0369847-023e-47e1-8426-959c25374312","html_url":"https://github.com/googlemaps/java-fleetengine-auth","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/googlemaps/java-fleetengine-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps%2Fjava-fleetengine-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps%2Fjava-fleetengine-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps%2Fjava-fleetengine-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps%2Fjava-fleetengine-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googlemaps","download_url":"https://codeload.github.com/googlemaps/java-fleetengine-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlemaps%2Fjava-fleetengine-auth/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261232851,"owners_count":23128169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-22T03:41:49.276Z","updated_at":"2025-10-06T20:42:37.884Z","avatar_url":"https://github.com/googlemaps.png","language":"Java","readme":"# Fleet Engine Auth Library for Java\n\nFleet Engine use JSON Web Tokens (JWTs) to both authenticate and authorize\nincoming requests. This process has several aspects to it and is non-trivial to\nset up. This Fleet Engine Auth Library provides a set of tools to simplify the\nsetup process.\n\nThis library provides the following benefits:\n\n* Simplifies the process of creating Fleet Engine Tokens.\n* Provides token signing mechanisms other than using credential files (such as\n  impersonating a service account.)\n* Attaches signed tokens to outbound requests made from either a GAPIC client or\n  gRPC stub.\n\nSample scripts are provided in the sample directory. To learn more, see:\n[sample/README.md](sample/README.md).\n\n## Installation\n\nYou can add the library to your project via Maven or Gradle.\n\n### Maven\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.google.maps\u003c/groupId\u003e\n  \u003cartifactId\u003efleetengine-auth\u003c/artifactId\u003e\n  \u003cversion\u003e(insert latest version)\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\n### Gradle\n```groovy\ndependencies {\n  implementation 'com.google.maps:fleetengine-auth:(insert latest version here)'\n}\n```\n\n## Concepts\n\n### Fleet Engine Roles\n\nFleet Engine Requests are always made on behalf of a service account defined in\nyour GCP project. Each service account is tied to a pre-defined Fleet Engine\nRole.\n\nThe supported Fleet Engine roles are:\n\nRole                           | Description\n:----------------------------- | :---------:\nFleet Engine Consumer SDK User | Grants permission to search for vehicles and to retrieve information about vehicles and trips. Tokens minted by a service account with this role can be used from your ridesharing consumer app mobile devices.\nFleet Engine Driver SDK User   | Grants permission to update vehicle locations and routes and to retrieve information about vehicles and trips. Tokens minted by a service account with this role can be used from your ridesharing driver app mobile devices.\nFleetEngine Service Super User | Grants permission to all vehicles and trips APIs. Tokens minted by a service account with this role can be used from your backend servers.\nFleet Engine Delivery Consumer SDK User | Grants permission to search for tasks using a tracking ID, and to read but not update task information. Tokens minted by a service account with this role are typically used from a delivery consumer's web browser.\nFleet Engine Delivery Untrusted Driver User | Grants permission to update delivery vehicle location. Tokens minted by a service account with this role are typically used from your delivery driver's mobile devices.\nFleet Engine Delivery Trusted Driver User | Grants permission to create and update delivery vehicles and tasks, including updating the delivery vehicle location and task status or outcome. Tokens minted by a service account with this role are typically used from your delivery driver's mobile devices or from your backend servers.\nFleet Engine Delivery Fleet Reader | Grants permission to read delivery vehicles and tasks and to search for tasks using a tracking ID. Tokens minted by a service account with this role are typically used from a delivery fleet operator's web browser.\nFleet Engine Delivery Super User| Grants permission to all delivery vehicles and tasks APIs. Tokens minted by a service account with this role are typically used from your backend servers.\n\nEach role is tied to a `com.google.fleetengine.auth.token.FleetEngineTokenType`,\nand each type of token can be constrained to a specific resource:\n\nRole                                | Token Type                      | Resource Constraint\n:---------------------------------- | :-----------------------------: | :-----------------:\nFleet Engine Consumer SDK User      | `FleetEngineTokenType#CONSUMER` | trip id\nFleet Engine Driver SDK User        | `FleetEngineTokenType#DRIVER`   | vehicle id\nFleet Engine Service Super SDK User | `FleetEngineTokenType#SERVER`   | (no constraint)\nFleet Engine Delivery Consumer SDK User      | `FleetEngineTokenType#DELIVERY_CONSUMER` | task id OR tracking id\nFleet Engine Delivery Untrusted Driver SDK User        | `FleetEngineTokenType#UNTRUSTED_DELIVERY_DRIVER`   | delivery vehicle id\nFleet Engine Delivery Trusted Driver SDK User | `FleetEngineTokenType#TRUSTED_DELIVERY_DRIVER`   | delivery vehicle id and task id\nFleet Engine Delivery Fleet Reader SDK User | `FleetEngineTokenType#DELIVERY_FLEET_READER`   | (no constraint)\nFleet Engine Delivery Super SDK User | `FleetEngineTokenType#DELIVERY_SERVER`   | (no constraint)\n\n\n### JWT Signers\n\nThe Fleet Engine Auth Library signs JWTs through classes that implement the\n`com.google.fleetengine.auth.token.factory.signer.Signer` interface. The Library\ncomes loaded with three predefined Signers which handle the common use cases\n(the set of pre-defined signers are located below the\n`com.google.fleetengine.auth.token.factory.signer` package):\n\nSigner                        | GCP Required | Description\n:---------------------------: | :----------: | :---------:\n`DefaultServiceAccountSigner` | Yes          | Signs tokens with the service account running the application. This signer is typically used to sign `FleetEngineTokenType#SERVER` tokens. The service account \u003cb\u003eMUST\u003c/b\u003e have the `iam.serviceAccounts.signBlob` permission which is typically acquired through the `Service Account Token Creator` role.\n`ImpersonatedSigner`          | Yes          | Signs tokens by impersonating a different service account. The account hosting the application \u003cb\u003eMUST\u003c/b\u003e have the `iam.serviceAccounts.signBlob` permission which is typically acquired through the `Service Account Token Creator` role.\n`LocalSigner`                 | No           | Signs tokens with a private key file generated by a given service account. **Storing private key files in any form presents a security risk and should be a last resort.**\n\nNote: GCP Required denotes that the Signer works with applications that are\nhosted on GCP or are otherwise authenticated with GCP. To use Signers that\nrequire GCP, the\n\"[IAM Service Account Credentials API](https://console.cloud.google.com/apis/library/iam.googleapis.com)\"\n\u003cb\u003eMUST\u003c/b\u003e be enabled in your GCP project. For more information, see:\nhttps://cloud.google.com/docs/authentication/getting-started.\n\n## Using the library\n\n### Minting Tokens\n\n`com.google.fleetengine.auth.AuthTokenMinter` ties signers with roles to make\nminting tokens straightforward.\n\nTo use, first associate a `Signer` with a service account and a type of token.\n\nFor example, when creating tokens for use with the On Demand Rides and Deliveries APIs:\n\n```java\nAuthTokenMinter minter = AuthTokenMinter.builder()\n  .setServerTokenSigner(DefaultServiceAccountSigner.create())\n  .setDriverSigner(ImpersonatedAccountSignerCredentials.create(\"driver@gcp-project.com\")\n  .setConsumerSigner(ImpersonatedAccountSignerCredentials.create(\"consumer@gcp-project.iam.gserviceaccount.com\")\n  .build();\n```\n\nWhen creating tokens for use with the Last Mile Fleet Services, use:\n\n```java\nAuthTokenMinter minter = AuthTokenMinter.deliveryBuilder()\n  .setDeliveryServerSigner(DefaultServiceAccountSigner.create())\n  .setDeliveryConsumerSigner(ImpersonatedAccountSignerCredentials.create(\"delivery-consumer@gcp-project.com\")\n  .setUntrustedDeliveryDriverSigner(ImpersonatedAccountSignerCredentials.create(\"untrusted-delivery-driver-signer@gcp-project.iam.gserviceaccount.com\")\n  .setTrustedDeliveryDriverSigner(ImpersonatedAccountSignerCredentials.create(\"trusted-delivery-driver-signer@gcp-project.iam.gserviceaccount.com\")\n  .setDeliveryFleetReaderSigner(ImpersonatedAccountSignerCredentials.create(\"delivery-fleet-reader@gcp-project.iam.gserviceaccount.com\")\n  .build();\n```\n\nThe minter provides a getter method for each of the token types. Each getter\nreturns an instance of `com.google.fleetengine.auth.token.FleetEngineToken`:\n\n```java\nFleetEngineToken serverToken = minter.getServerToken();\n\nFleetEngineToken consumerToken = minter.getConsumerToken(TripClaims.create(\"trip-id-123\"));\n\nFleetEngineToken driverToken = minter.getDriverToken(VehicleClaims.create(\"vehicle-id-123\"));\n```\n\nA `FleetEngineToken` has several attributes, but in most cases, only the base64\nencoded JWT is needed `com.google.fleetengine.auth.token.FleetEngineToken#jwt`.\n\n```java\nSystem.out.println(\"Base64 encoded JWT:\");\nSystem.out.println(serverToken.jwt());\n\nSystem.out.println(\"HTTP Header:\");\nSystem.out.println(String.format(\"Authorization: Bearer %s\", token.jwt()));\n```\n\nOutput:\n\n```\nBase64 encoded JWT:\nxxxxx.yyyyy.zzzzz\n\nHTTP Header:\nAuthorization: Bearer xxxxx.yyyyy.zzzzz\n```\n\n## Working with Generated Clients\n\nAlongside token minting functionality, the library also provides a set of\ncomponents that work with Fleet Engine protobuf generated classes. There are two\nsets of generated classes that make requests to the fleet engine server, GAPIC\nclients and gRPC stubs. Using GAPIC clients over gRPC stubs is recommended.\n\nTo learn more about GAPIC clients, see:\nhttps://developers.google.com/maps/documentation/transportation-logistics/on-demand-rides-deliveries-solution/trip-order-progress/fleet-engine/gapic_client\nhttps://developers.google.com/maps/documentation/transportation-logistics/last-mile-fleet-solution/shipment-tracking/fleet-engine/gapic_client\n\nBoth mechanisms require a FleetEngineTokenProvider which is an interface that\nhas just one method:\n\n```java\npackage com.google.fleetengine.auth.client;\n\n/** Provides non-expired, signed JWTs. */\npublic interface FleetEngineTokenProvider {\n  /** Returns a non-expired {@link FleetEngineToken} with a base64 signed JWT. */\n  FleetEngineToken getSignedToken() throws SigningTokenException;\n}\n```\n\nFor convenience, `com.google.fleetengine.auth.AuthTokenMinter` implements\n`FleetEngineTokenProvider` and returns server tokens when called through\n`FleetEngineTokenProvider#getSignedToken`. Any type of token can be returned.\n\n### Sharing Minters\n\nBy default, `AuthTokenMinter` caches signed tokens with a five-minute\nexpiration. In order to take advantage of its internal cache, it must be shared\nacross uses. Having one singleton instance is recommended.\n\n### Integrating with GAPIC Clients\n\nGAPIC clients are configured using `com.google.api.gax.rpc.ClientSettings` which\nare created with a builder. The\n`com.google.fleetengine.auth.client.FleetEngineClientSettingsModifier` updates\n`ClientSettings.Builder`s such that outbound requests made from the\ncorresponding client have valid authorization headers.\n\n```java\nFleetEngineClientSettingsModifier\u003cVehicleServiceSettings, VehicleServiceSettings.Builder\u003e modifier =\n  //In most cases, tokenProvider will be a singleton instance of AuthTokenMinter\n  new FleetEngineClientSettingsModifier\u003c\u003e(tokenProvider); \n\nVehicleServiceSettings.Builder builder = VehicleServiceSettings.newBuilder();\nVehicleServiceSettings settings = modifier.updateBuilder(builder).build();\n\ntry (VehicleServiceClient client = VehicleServiceClient.create(settings)) {\n  // make request\n}\n```\n\nFor more information around the Fleet Engine GAPIC clients, see:\nhttps://developers.google.com/maps/documentation/transportation-logistics/on-demand-rides-deliveries-solution/trip-order-progress/fleet-engine/gapic_client\nhttps://developers.google.com/maps/documentation/transportation-logistics/last-mile-fleet-solution/shipment-tracking/fleet-engine/gapic_client\n### Generated gRPC Stubs\n\ngRPC stubs are initialized from `io.grpc.ManagedChannel`s and allows\nfunctionality to be injected using interceptors.\n\nUsing GAPIC clients in lieu of gRPC stubs is recommended.\n\n```java\n// In most cases, tokenProvider will be a singleton instance of AuthTokenMinter.\nFleetEngineTokenProvider fleetEngineTokenProvider = getTokenProvider();\n\n// Cloud resource prefix allows optimised request handling.\nMetadata headers = new Metadata();\nheaders.put(\n          Metadata.Key.of(\n              \"google-cloud-resource-prefix\", Metadata.ASCII_STRING_MARSHALLER),\n          String.format(\"providers/%s\", PROVIDER_ID));\n\nManagedChannel channel = ManagedChannelBuilder.forTarget(fleetEngineAddress)\n  .intercept(\n      FleetEngineAuthClientInterceptor.create(fleetEngineTokenProvider),\n      MetadataUtils.newAttachHeadersInterceptor(headers))\n  .build();\n\nVehicleServiceBlockingStub stub = VehicleServiceGrpc.newBlockingStub(channel);\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglemaps%2Fjava-fleetengine-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglemaps%2Fjava-fleetengine-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglemaps%2Fjava-fleetengine-auth/lists"}