README

A PHP library that obtains OpenID Connect (OIDC) ID tokens from the CI/CD platform it is running on.

Modern CI/CD platforms can issue short-lived, signed OIDC tokens that prove the identity of the running workflow (which repository, which workflow, which branch, etc.). These tokens can be exchanged for credentials with a service that trusts the platform's OIDC provider — removing the need to store long-lived secrets in your CI configuration. This library handles the platform-specific work of detecting the environment and requesting such a token, then hands you back the parsed result.

Requirements

PHP >= 7.2.5

The library relies on HTTPlug / PSR-18 discovery, so you also need a PSR-18 HTTP client and PSR-17 factories available in your project (for example symfony/http-client and nyholm/psr7).

Install

Via Composer:

$ composer require private-packagist/oidc-identities

Supported platforms

The TokenGenerator tries each supported platform in turn and uses the first one that reports it is the current environment. When none of them match — for example when running locally — generate() returns null.

What is the TokenGenerator?

TokenGenerator is the main entry point of the library. You give it an $audience (the identifier of the service that will consume the token, e.g. Private Packagist), and it:

1. Detects which supported platform the code is currently running on.
2. Performs the platform-specific request to mint an OIDC ID token for that audience.
3. Returns a Token value object containing the raw JWT together with its decoded header, payload and signature parts.

You would use it whenever your code runs inside a CI/CD pipeline and needs to prove its identity to an external service via OIDC, instead of relying on a stored secret. Because it abstracts away the per-platform details, the same call works on any supported platform without branching in your own code.

Usage

Initiate a TokenGenerator instance and call the generate method with $audience. The TokenGenerator will automatically try all supported platforms and return a Token for the first matching one, or null if the current environment is not supported.

use Http\Client\Common\HttpMethodsClient;
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;
use PrivatePackagist\OIDC\Identities\TokenGenerator;
use Psr\Log\NullLogger;

// Configure a HttpMethodsClient instance
$oidcHttpClient = new HttpMethodsClient(
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findStreamFactory(),
);

$tokenGenerator = new TokenGenerator(new NullLogger(), $oidcHttpClient);
$token = $tokenGenerator->generate($audience);

if ($token === null) {
    // Not running on a supported platform, or no OIDC token available.
    return;
}

// $token->token     — the raw JWT string
// $token->header    — decoded header
// $token->payload   — decoded payload
// $token->signature — the signature part

The constructor also accepts any PSR-3 LoggerInterface; pass a real logger instead of NullLogger to get debug output about platform detection and the token request.

Copyright and License

The library is licensed under the MIT License.