README

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

• Safely caches all authentication IO to reduce latency across requests when running PHP in a web server context

• All IO is done lazily, avoids accidentally DoSing the metadata server by not performing any IO during initialization

• Supports service account impersonation out of the box

• Clear distinction between fetching OAuth2 access tokens and OIDC identity tokens to make it simple to call Cloud Functions, Cloud Run, and similar products

• Fully typed via Psalm

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

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

// ...

• Installation
• Usage
  • Authenticating with Google Cloud Platform APIs
  • Authenticating with Google Cloud Platform serverless products
  • Impersonating service accounts
  • Determining the project ID

Installation

composer require ericnorris/gcp-auth-contrib

Usage

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 other-account@some-project-id.iam.gserviceaccount.com:

$fetcher = \ericnorris\GCPAuthContrib\OpinionatedDefaults::get()->makeImpersonatedCredentialsFetcher(
    "other-account@some-project-id.iam.gserviceaccount.com",
);

// 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()}";