Unofficial Google Cloud Platform authentication library focusing on speed and correctness.

v1.0.0 2020-09-26 22:38 UTC

This package is auto-updated.

Last update: 2022-07-27 05:08:42 UTC


CI status coverage percentage Psalm type coverage percentage

gcp-auth-contrib is an unofficial PHP library for authenticating with Google Cloud Platform products that focuses on sane defaults, correctness, and speed.

$fetcher = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeCredentialsFetcher();

$storageClient = new \Google\Cloud\Storage\StorageClient([
    "credentialsFetcher" => $fetcher,

// ...


composer require ericnorris/gcp-auth-contrib


The following examples all make use of the OpinionatedDefaults class. The defaults are:

  • Use a plain Guzzle HTTP client. This means exceptions will be thrown for HTTP errors, e.g. for 500s.

  • Use the Application Default Credentials pattern for finding credentials. Note: you DO NOT need to provide a service account key file if you are running your code on a Google Cloud Platform product. Using this library (and the opinionated defaults) will authenticate automatically using the metadata server of the product you are running on.

  • Cache authentication IO using a Symfony in-memory and filesystem cache. Access and identity tokens are cached for as long as they are valid, and other requests are cached permanently when it is safe to do so.

If these defaults do not work for you, the Credentials directory has a flexible set of classes you may use for authentication. It is strongly encouraged that you wrap any such classes with a CachedCredentials instance to avoid unecessary IO.

Authenticating with Google Cloud Platform APIs

The Google Cloud Platform PHP library generally requires a class implementing the FetchAuthTokenInterface interface to be passed in to their client via the credentials or credentialsFetcher option array key. This depends on the particular client, see the docs for your particular client to know which one to use.

You can retrieve a FetchAuthTokenInterface compatible interface by calling makeCredentialsFetcher on the OpinionatedDefaults class.

$fetcher = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeCredentialsFetcher();

// the StorageClient class takes the parameter as a "credentialsFetcher" option
$storageClient = new \Google\Cloud\Storage\StorageClient([
    "credentialsFetcher" => $fetcher,

// the BigtableClient class takes the parameter as a "credentials" option
$bigtableClient = new \Google\Cloud\Bigtable\BigtableClient([
    "credentials" => $fetcher,

// ...

Authenticating with Google Cloud Platform serverless products

Calling authenticated Cloud Run or Cloud Function services requires an OIDC identity token. All instances of Credentials in this library offer a separate fetchIdentityToken(string $audience) method for exactly this purpose.

Note: This includes the AuthorizedUserCredentials! You can use a user’s OAuth credentials (via gcloud auth application-default login or by doing the OAuth2 flow yourself) to call authenticated serverless products.

$credentials = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeCredentials();

$identityTokenResponse = $credentials->fetchIdentityToken("https://your-cloud-function-or-run-url-here");

$headers = [
    "Authorization: Bearer {$identityTokenResponse->getIdentityToken()}",

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, "https://your-cloud-function-or-run-url-here");
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

// ...

Impersonating service accounts

You may impersonate another Google Cloud Platform service account using the service account impersonation flow. Assuming the service account running the below code has the roles/iam.serviceAccountTokenCreator IAM role on an imaginary service account

$fetcher = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeImpersonatedCredentialsFetcher(

// calls will be authenticated using the other account's credentials
$storageClient = new \Google\Cloud\Storage\StorageClient([
    "credentialsFetcher" => $fetcher,

// ...

Determining the project ID

May not be supported by all credential types.

$credentials = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeCredentials();

echo "project ID: {$credentials->fetchProjectID()}";