{"id":20532369,"url":"https://github.com/unitvectory-labs/simplegoogleidtoken","last_synced_at":"2026-03-01T00:06:41.711Z","repository":{"id":242356522,"uuid":"809342994","full_name":"UnitVectorY-Labs/simplegoogleidtoken","owner":"UnitVectorY-Labs","description":"simplegoogleidtoken is a lightweight Java library for effortlessly exchanging Google Cloud Service Account credentials for Google ID tokens","archived":false,"fork":false,"pushed_at":"2025-07-05T14:46:42.000Z","size":222,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-05T15:59:35.769Z","etag":null,"topics":["google","java-17","jwt-authentication","mavencentral"],"latest_commit_sha":null,"homepage":"","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/UnitVectorY-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-02T12:29:01.000Z","updated_at":"2025-07-05T14:46:45.000Z","dependencies_parsed_at":"2024-06-02T14:06:47.212Z","dependency_job_id":"4b962b27-42dd-417b-a78b-254317699157","html_url":"https://github.com/UnitVectorY-Labs/simplegoogleidtoken","commit_stats":null,"previous_names":["unitvectory-labs/simplegoogleidtoken"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/UnitVectorY-Labs/simplegoogleidtoken","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fsimplegoogleidtoken","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fsimplegoogleidtoken/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fsimplegoogleidtoken/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fsimplegoogleidtoken/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UnitVectorY-Labs","download_url":"https://codeload.github.com/UnitVectorY-Labs/simplegoogleidtoken/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnitVectorY-Labs%2Fsimplegoogleidtoken/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264916028,"owners_count":23682957,"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":["google","java-17","jwt-authentication","mavencentral"],"created_at":"2024-11-16T00:14:32.833Z","updated_at":"2026-03-01T00:06:41.668Z","avatar_url":"https://github.com/UnitVectorY-Labs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/UnitVectorY-Labs/simplegoogleidtoken.svg)](https://github.com/UnitVectorY-Labs/simplegoogleidtoken/releases/latest) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Active](https://img.shields.io/badge/Status-Active-green)](https://guide.unitvectorylabs.com/bestpractices/status/#active) [![Maven Central](https://img.shields.io/maven-central/v/com.unitvectory/simplegoogleidtoken)](https://central.sonatype.com/artifact/com.unitvectory/simplegoogleidtoken) [![javadoc](https://javadoc.io/badge2/com.unitvectory/simplegoogleidtoken/javadoc.svg)](https://javadoc.io/doc/com.unitvectory/simplegoogleidtoken) [![codecov](https://codecov.io/gh/UnitVectorY-Labs/simplegoogleidtoken/graph/badge.svg?token=V8Uy1YGU2u)](https://codecov.io/gh/UnitVectorY-Labs/simplegoogleidtoken)\n\n# simplegoogleidtoken\n\nsimplegoogleidtoken is a lightweight Java library for effortlessly exchanging Google Cloud Service Account credentials for Google ID tokens\n\n## Purpose\n\nThis library is intended to simplify the process of exchanging Google Cloud Service Account credentials for Google ID tokens. It is configurable so when used in GCP the service account assigned to the infrastructure can be used to generate the Google ID token.  When used in other envirioment the service account credentials JSON file can be provided and used to request the Google ID token.\n\nThe tokens are generated by calling the Google `https://oauth2.googleapis.com/token` endpoint with the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant type specifying a target audience that is included in the ID token.\n\nThe issuer of these tokens will be `https://accounts.google.com` which has a JWKS endpoint available at `https://www.googleapis.com/oauth2/v3/certs`.\n\nThe reasoning behind this library is not for calling Google APIs but for calling other APIs that utilize Google ID tokens for authentication.  By targeting a light weight implementation for use cases outside of GCP the library is able to provide a simple and easy to obtain Google ID tokens.\n\n## Getting Started\n\nThis library requires Java 17 and is available in the Maven Central Repository:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.unitvectory\u003c/groupId\u003e\n    \u003cartifactId\u003esimplegoogleidtoken\u003c/artifactId\u003e\n    \u003cversion\u003e0.0.6\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nWhen utilizing this library and running on GCP the `google-auth-library-oauth2-http` library is required.  This library is available on Maven Central and must be included in addition to `simplegoogleidtoken`. This optional dependency is not needed if the service account credentials JSON file is provided directly.  This is intentional to reduce the number of required dependencies which is limited to only GSON as the mandatory dependency.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.google.auth\u003c/groupId\u003e\n    \u003cartifactId\u003egoogle-auth-library-oauth2-http\u003c/artifactId\u003e\n    \u003cversion\u003e1.27.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\nThis library provides `SimpleGoogleIdToken` which uses `SimpleRequest` to specify the target audience and `SimpleResponse` to return the ID token.  In the case of an error the `SimpleSignException` or SimpleExchangeException` will be throw.\n\nWhen running on GCP this library can utilize the metadata service to obtain the ID tokens without the need to have the service account credentials JSON file.  The default behavior for `SimpleGoogleIdToken` is to use the metadata service to obtain the ID token using the `ServiceAccountDefaultGoogleCredentialsConfig` configuration object which does not need to explicitly be provided.\n\n```java\npackage example;\n\nimport com.unitvectory.simplegoogleidtoken.SimpleGoogleIdToken;\nimport com.unitvectory.simplegoogleidtoken.SimpleRequest;\n\npublic class GCPExample {\n\n    public String getIdToken() {\n\n        String audience = \"https://example.com\";\n\n        SimpleGoogleIdToken simpleGoogleIdToken = SimpleGoogleIdToken.builder().build();\n\n        String idToken = simpleGoogleIdToken\n                .getIdToken(SimpleRequest.builder().withTargetAudience(audience).build()).getIdToken();\n\n        return idToken;\n    }\n}\n```\n\nWhen running outside of GCP the service account credentials JSON file can be provided to the library.  The `ServiceAccountFileConfig` configuration object can be used to provide the path to the service account credentials JSON file. Alternatively `ServiceAccountJsonConfig` can be used to provide the service account credentials JSON as a string directly.\n\n```java\npackage example;\n\nimport com.unitvectory.simplegoogleidtoken.ServiceAccountFileConfig;\nimport com.unitvectory.simplegoogleidtoken.SimpleGoogleIdToken;\nimport com.unitvectory.simplegoogleidtoken.SimpleRequest;\n\npublic class LocalExample {\n\n    public String getIdToken(String serviceAccountKeyFilePath) {\n\n        String audience = \"https://example.com\";\n\n        SimpleGoogleIdToken simpleGoogleIdToken = SimpleGoogleIdToken.builder().withServiceAccountConfig(\n                ServiceAccountFileConfig.builder().withFilePath(serviceAccountKeyFilePath).build()).build();\n\n        String idToken = simpleGoogleIdToken\n                .getIdToken(SimpleRequest.builder().withTargetAudience(audience).build()).getIdToken();\n\n        return idToken;\n    }\n}\n```\n\n## Under the Covers\n\nHow does GCP's API work for Identity tokens?  This is accomplished through Google's OAuth endpoint.  The following is a brief overview of how this token exchange occurs which is also a description of what this library implements, this isn't particurally complicated.\n\nThe POST payload here is a `application/x-www-form-urlencoded` payload with a grant type of `urn:ietf:params:oauth:grant-type:jwt-bearer` with the `assertion` parameter including the JWT from the service account.\n\n```\nPOST https://oauth2.googleapis.com/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer\u0026assertion=TOKENHERE\n```\n\nThe assertion is a JWT with the following format...\n\nThe header Google expects for this are:\n\n```json\n{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\"\n}\n```\n\nThe payload is as follows with the key input being `target_audience` as this will be the audience of the generated token.\n\n```json\n{\n    \"iss\": \"example-service-account@example.iam.gserviceaccount.com\",\n    \"sub\": \"example-service-account@example.iam.gserviceaccount.com\",\n    \"aud\": \"https://oauth2.googleapis.com/token\",\n    \"iat\": 1723155553,\n    \"exp\": 1723159153,\n    \"target_audience\": \"https://targetaudience.example.com\"\n}\n```\n\nIn the case that a JSON file from a GCP service account is being used, that JSON file looks like the following.  The two key attributes here are `client_email` which is used in bothe the `iss` and `sub` of the JWT that is being sigened and the `private_key` that is being used for the signing.\n\n```json\n{\n  \"type\": \"service_account\",\n  \"project_id\": \"example\",\n  \"private_key_id\": \"00000000000000000000000000000000000000000\",\n  \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nPRIVATEKEYGOESHERE\\n-----END PRIVATE KEY-----\\n\",\n  \"client_email\": \"example-service-account@example.iam.gserviceaccount.com\",\n  \"client_id\": \"0000000000000000000000\",\n  \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n  \"token_uri\": \"https://oauth2.googleapis.com/token\",\n  \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n  \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/example-service-account%40example.iam.gserviceaccount.com\",\n  \"universe_domain\": \"googleapis.com\"\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funitvectory-labs%2Fsimplegoogleidtoken","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funitvectory-labs%2Fsimplegoogleidtoken","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funitvectory-labs%2Fsimplegoogleidtoken/lists"}