README

A PHP library for OpenID Connect (OIDC) integration with AWS Cognito support and Symfony Security component integration.

Features

OIDC Client Credentials Flow: Machine-to-machine authentication with AWS Cognito
PSR-6 Token Caching: Built-in token caching with expiration handling for performance
Symfony Security Integration: User provider for OIDC-based authentication
Type Safety: Full PHP 8.3+ type annotations with Psalm static analysis
Modern PHP: Uses readonly classes, strict types, and latest PHP features

Requirements

PHP 8.3 or higher
Symfony 6.4+ or 7.0+

Installation

composer require gpht/oidc

Usage

1. OIDC Client Token (Machine-to-Machine Authentication)

Use OidcClientToken to obtain access tokens for machine-to-machine communication:

<?php

declare(strict_types=1);

use Gpht\Oidc\Client\OidcClientToken;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\HttpClient\HttpClient;

// Create HTTP client
$httpClient = HttpClient::create();

// Create PSR-6 cache (required for token caching)
$cache = new FilesystemAdapter('oidc_tokens', 3600);

// Initialize OIDC client
$oidcClientToken = new OidcClientToken(
    client: $httpClient,
    cache: $cache,
    tokenEndpoint: 'https://your-cognito-domain.auth.region.amazoncognito.com/oauth2/token',
    cognitoClientId: 'your-client-id',
    cognitoClientSecret: 'your-client-secret'
);

// Get access token with default scopes (m2m/read, m2m/write)
// Token will be cached automatically with expiration handling
$token = $oidcClientToken->clientCredentialToken();

// Get access token with custom scopes
$token = $oidcClientToken->clientCredentialToken(['custom/read', 'custom/write']);

Token Caching Benefits

The library automatically caches tokens with the following features:

Automatic Expiration: Tokens are cached with their expiration time minus a 60-second buffer
Scope-Based Caching: Different token scopes are cached separately using unique cache keys
Performance: Reduces HTTP requests to the token endpoint by reusing valid cached tokens
PSR-6 Compatible: Works with any PSR-6 cache implementation (Redis, Memcached, File system, etc.)

2. Symfony Service Configuration

Register Services

Configure the OIDC services in your Symfony service configuration:

<?php

declare(strict_types=1);

use Gpht\Oidc\Client\OidcClientToken;
use Gpht\Oidc\Symfony\OidcUserProvider;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Contracts\HttpClient\HttpClientInterface;

return static function (ContainerConfigurator $containerConfigurator): void {
    $s = $containerConfigurator->services();
    $s
        ->defaults()
        ->autowire()
        ->autoconfigure();

    // Configure OIDC Client Token service
    $s
        ->set(OidcClientToken::class)
        ->arg('$cache', service('cache.app'))  // Use Symfony's cache service
        ->arg('$tokenEndpoint', '%env(COGNITO_TOKEN_ENDPOINT)%')
        ->arg('$cognitoClientId', '%env(COGNITO_CLIENT_ID)%')
        ->arg('$cognitoClientSecret', '%env(COGNITO_CLIENT_SECRET)%');

    // Configure OIDC User Provider service
    $s
        ->set(OidcUserProvider::class);
};

Environment Variables

Add these environment variables to your .env file:

# AWS Cognito Configuration
COGNITO_TOKEN_ENDPOINT=https://your-cognito-domain.auth.region.amazoncognito.com/oauth2/token
COGNITO_CLIENT_ID=your-client-id
COGNITO_CLIENT_SECRET=your-client-secret
OIDC_BASE_URI=https://your-cognito-domain.auth.region.amazoncognito.com

3. Symfony Security Integration

Configure User Provider

<?php

declare(strict_types=1);

use Gpht\Oidc\Symfony\OidcUserProvider;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Config\SecurityConfig;

return static function (ContainerConfigurator $containerConfigurator, SecurityConfig $securityConfig): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set('env(OIDC_BASE_URI)', 'https://your-cognito-domain.auth.region.amazoncognito.com');

    // Register OIDC user provider
    $securityConfig
        ->provider('oidc')
        ->id(OidcUserProvider::class);

    // Configure OIDC firewall
    $securityConfig
        ->firewall('api')
        ->provider('oidc')
        ->pattern('^/api/')
        ->stateless(true)
        ->accessToken()
            ->tokenHandler()
                ->oidc()
                    ->claim('sub')
                    ->algorithms(['ES256', 'RS256'])
                    ->audience('')
                    ->issuers(['%env(OIDC_BASE_URI)%'])
                    ->discovery()
                        ->baseUri('%env(OIDC_BASE_URI)%')
                        ->cache(['id' => 'cache.app']);
};

Use in Controllers

<?php

declare(strict_types=1);

namespace App\Controller;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
use Symfony\Component\Security\Http\Attribute\IsGranted;

#[Route('/api')]
final readonly class ApiController
{
    public function __construct(
        private TokenStorageInterface $tokenStorage,
    ) {}

    #[Route('/profile', methods: ['GET'])]
    #[IsGranted('IS_AUTHENTICATED_FULLY')]
    public function profile(): JsonResponse
    {
        $token = $this->tokenStorage->getToken();
        $user = $token?->getUser();

        if (null === $user) {
            return new JsonResponse(['error' => 'User not authenticated'], 401);
        }

        return new JsonResponse([
            'user_id' => $user->getUserIdentifier(),
            'roles' => $user->getRoles(),
            'email' => $user->getEmail(),
            'name' => $user->getName(),
        ]);
    }
}

4. Testing with Client Credentials

<?php

declare(strict_types=1);

use Gpht\Oidc\Client\OidcClientToken;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class ApiTest extends WebTestCase
{
    public function testAuthenticatedEndpoint(): void
    {
        $client = static::createClient();
        
        /** @var OidcClientToken $oidcClientToken */
        $oidcClientToken = self::getContainer()->get(OidcClientToken::class);
        $token = $oidcClientToken->clientCredentialToken();

        $client->jsonRequest('GET', '/api/profile', [], [
            'HTTP_AUTHORIZATION' => 'Bearer ' . $token,
        ]);

        $this->assertResponseIsSuccessful();
    }
}

Development

# Install dependencies
composer install

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Check code style
composer cs-check

# Fix code style
composer cs-fix

# Run static analysis
composer psalm

Architecture

Gpht\Oidc\Client\OidcClientToken: Handles OAuth2 client credentials flow for machine-to-machine authentication with PSR-6 token caching
Gpht\Oidc\Symfony\OidcUserProvider: Symfony Security user provider that creates OidcUser objects from OIDC claims

Dependencies

The library uses modern PHP standards and minimal dependencies:

nyholm/psr7: PSR-7 HTTP message implementation for requests
psr/cache: PSR-6 caching interface for token storage
psr/http-client: PSR-18 HTTP client interface
symfony/security-core: Symfony Security component integration

License

MIT License. See LICENSE for details.

gpht / oidc

Maintainers

Details