Google Auth Library for PHP: OAuth 2.0 and ADC Setup

What Google Auth Library for PHP Solves

Google Auth Library for PHP addresses the authentication boundary between a PHP application and Google APIs. It provides OAuth 2.0 authorization and authentication support, including Application Default Credentials, service account credentials, user refresh credentials, access-token middleware, and ID token middleware. The intended audience is PHP developers building applications that call Google Cloud or other Google APIs and want the authentication behavior to come from Google's officially supported PHP client rather than custom HTTP signing and token code.

The README recommends Application Default Credentials for calls to Cloud APIs. ADC gives an application a common credential discovery path instead of requiring each call site to know where a key file is stored. The credential source can depend on the execution environment, which matters when the same application runs locally, in a test process, or in production. The library does not remove the need to configure credentials, choose scopes, or enable the target Google API.

There is a security boundary around that convenience. The README explicitly warns that credential configurations accepted from an external source must be validated before being passed to a Google API or library. A credential JSON file, stream, or array can contain security-sensitive fields, so treating arbitrary input as trusted configuration can compromise systems and data. Application Default Credentials should therefore be paired with controlled credential sources and appropriate validation.

How ADC Becomes Google API Authentication

The documented Guzzle flow has four concrete stages. First, the application sets `GOOGLE_APPLICATION_CREDENTIALS` to the path of its JSON credentials file. Second, it declares the OAuth scopes required by the API call. Third, `ApplicationDefaultCredentials::getMiddleware($scopes)` creates authentication middleware. Finally, the middleware is pushed onto a Guzzle `HandlerStack`, and the Guzzle client uses the `google_auth` authentication setting.

The middleware is attached at the HTTP handler layer rather than by manually adding an access token to one request. That arrangement allows the client configuration to authorize requests sent through the stack. The README example targets the Drive API and requests the `https://www.googleapis.com/auth/drive.readonly` scope. It also requires the Drive API to be enabled in the Google Developers Console before the call can succeed.

The library supports more than ADC. The explicit JSON key example uses `ServiceAccountCredentials` for a service account and `UserRefreshCredentials` for an authorized user. An optional `FetchAuthTokenCache` can wrap the credentials with a configured cache and cache implementation. That cache is relevant because token acquisition can otherwise repeat work on each request, although the README excerpt does not define a default cache backend or a complete cache configuration example.

ID token middleware follows a different target. `getIdTokenMiddleware` receives a target audience, which can be an IAP client ID, a Cloud Run URL, or another protected resource URL. The resulting client calls the protected resource rather than the Google API base URI. Cloud Run invocations require the `Cloud Run Invoker` IAM permission, while IAP requires the client ID used for the protected resource as the target audience.

Composer Installation and First Drive Request

The README recommends Composer for installation. Its first command installs Composer itself, and the next command requests the latest stable `google/auth` package. The repository provides PHP source under `src/`, package metadata in `composer.json`, and API documentation through Google Cloud PHP documentation.

Install Composer with the command documented by the project:

curl -sS https://getcomposer.org/installer | php

After Composer is available, install the library:

composer.phar require google/auth

For a first real request, replace the credential path with the path to your own JSON file. The request below follows the README's ADC and Guzzle example. It requests read-only Drive access, creates the middleware and handler stack, and prints the response body.

use Google\Auth\ApplicationDefaultCredentials;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/credentials.json');
$scopes = ['https://www.googleapis.com/auth/drive.readonly'];
$middleware = ApplicationDefaultCredentials::getMiddleware($scopes);
$stack = HandlerStack::create();
$stack->push($middleware);
$client = new Client([
  'handler' => $stack,
  'base_uri' => 'https://www.googleapis.com',
  'auth' => 'google_auth'
]);
$response = $client->get('drive/v2/files');
print_r((string) $response->getBody());

The expected visible result is the API response body, which the example prints for inspection. Before using it, enable the Drive API and ensure the credential file is available at the configured path. The README does not describe a rollback command or a local development credential bootstrap procedure.

Service Accounts, User Credentials, and Caching

ADC is convenient when the runtime environment can supply an appropriate credential configuration. The README also provides a path for applications that already have a specific JSON key and need to select the credential class directly. This is useful when the application does not want to rely on the environment variable for every credential source.

The service account path constructs `ServiceAccountCredentials` with scopes and the JSON key array. The authorized user path constructs `UserRefreshCredentials`. The example uses a `match` expression on the JSON key's `type` field and rejects unsupported values with `InvalidArgumentException`. That explicit dispatch is clearer than sending every JSON shape to one credential class, but it also leaves the application responsible for validating the input and limiting accepted credential types.

Token caching is optional in the example. `FetchAuthTokenCache` accepts the credential object, a cache configuration, and a cache implementation. The repository includes tests and package configuration, but the README excerpt does not state which PSR cache implementation to choose, how long tokens remain cached, or what happens when a cache backend is unavailable. Those are deployment decisions that cannot be inferred from the installation example.

This makes the library a useful component rather than a complete credential-management system. It handles credential objects and request authentication, but the surrounding application still controls secret storage, file permissions, cache policy, credential validation, and API permissions.

ID Tokens for Cloud Run and IAP

For applications running behind Cloud Run or Cloud Identity-Aware Proxy, the README documents an ID token flow rather than the standard access token flow. The application provides a target audience to `ApplicationDefaultCredentials::getIdTokenMiddleware`, pushes the returned middleware onto a Guzzle handler stack, and sets the protected resource as `base_uri`.

The audience is not a decorative setting. For IAP, it should be the client ID associated with the IAP application. For Cloud Run, it can be the service URL. The resource URL in the client configuration must correspond to the protected endpoint being called. The README gives these example values:

$targetAudience = 'YOUR_ID_TOKEN_AUDIENCE';
$middleware = ApplicationDefaultCredentials::getIdTokenMiddleware($targetAudience);
$stack = HandlerStack::create();
$stack->push($middleware);
$client = new Client([
  'handler' => $stack,
  'auth' => 'google_auth',
  'base_uri' => 'https://YOUR_PROTECTED_RESOURCE',
]);

The caller still needs authorization in Google Cloud. The README states that a service account invoking Cloud Run services needs the `Cloud Run Invoker` IAM permission. For IAP, the client ID must match the protected resource configuration. Authentication middleware does not create missing IAM grants, and a correctly signed token can still be rejected by a resource whose policy does not allow the caller.

This distinction matters when evaluating the library. It supports two related token purposes, access tokens for Google API calls and ID tokens for protected application audiences. They should not be treated as interchangeable.

Compatibility, Maintenance, and Project Boundaries

The repository includes `composer.json`, `src/`, `tests/`, `phpunit.xml.dist`, `phpstan.neon.dist`, a `CHANGELOG.md`, and a `SECURITY.md` file. It is not archived, and the last push was on 2026-09-28. The recent release list includes `google/auth` versions `v1.55.1` on 2026-09-28, `v1.55.0` on 2026-09-21, and `v1.54.0` on 2026-09-14. That release cadence is evidence of recent project activity, but it does not by itself establish compatibility with every PHP or Guzzle version.

The README includes a dedicated Guzzle 5 compatibility path using `getSubscriber` and `getEmitter()->attach`. The main example uses `HandlerStack` and middleware, which is a different Guzzle integration model. A project must therefore confirm its Guzzle major version before copying the standard example. The README does not provide a full migration procedure between Guzzle versions.

The project is part of Google Cloud PHP. The README directs support requests, bug reports, and development contributions to that broader project, so maintenance responsibilities and issue routing may not be contained entirely within this repository. The package uses the Apache-2.0 license. That is a permissive software license, but the library does not grant access to Google APIs or remove Google Cloud IAM, billing, API enablement, or credential-protection requirements.

The library is also not a general-purpose OAuth provider for arbitrary identity systems. Its documented purpose is Google OAuth 2.0 and Google API authentication. Applications that need a different authorization server should not treat this package as a neutral OAuth framework.

Editorial conclusion

PHP teams already using Composer and Google Cloud APIs should adopt this library when ADC, OAuth scopes, service accounts, or ID tokens fit their request flow. Projects that need non-Google identity providers, or that cannot safely manage credential files and environment configuration, should choose another authentication approach. Verify the credential source, required IAM permission, enabled API, and exact cache configuration before deployment.

Frequently asked questions

Official sources

1. googleapis/google-auth-library-php on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases