private-packagist/oidc-identities

Create OIDC tokens on different platforms

1.0.1 2025-07-31 14:28 UTC

Requires

• php: ^7.2.5 || ^8.0
• php-http/client-common: ^1.9 || ^2.7
• psr/log: ^1.0 || ^2.0 || ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.4
• monolog/monolog: ^2
• nyholm/psr7: ^1.8
• php-http/mock-client: ^1.6
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^1.11.8
• phpstan/phpstan-deprecation-rules: ^1.2.0
• phpstan/phpstan-phpunit: ^1.4.0
• phpstan/phpstan-strict-rules: ^1.6.0
• phpunit/phpunit: ^8.5
• symfony/http-client: ^5.4

MIT

• OpenID Connect
• oidc
• identities

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

Platform	Detected via
GitHub Actions	GITHUB_ACTIONS env var

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.