OpenID (OIDC) Client

0.2.4 2022-04-21 11:49 UTC

This package is auto-updated.

Last update: 2022-05-21 12:02:31 UTC


Full OpenID client implementation.

Latest Stable Version Total Downloads License codecov Build Status

Most of the library code is based on the awesome node-openid-client.

The PHP extension gmp could be required.

Implemented specs and features

Supports of the following draft specifications



  • psr/http-client-implementation implementation
  • psr/http-factory-implementation implementation
  • psr/http-message-implementation implementation
composer require facile-it/php-openid-client

RSA signing algorithms are already included from the JWT Framework package`. If you need other algorithms you should install it manually.

Basic Usage

For a basic usage you shouldn't require any other dependency package.

Every builder have methods to customize instances with other dependencies.

use Facile\OpenIDClient\Client\ClientBuilder;
use Facile\OpenIDClient\Issuer\IssuerBuilder;
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Service\Builder\AuthorizationServiceBuilder;
use Facile\OpenIDClient\Service\Builder\UserInfoServiceBuilder;
use Psr\Http\Message\ServerRequestInterface;

$issuer = (new IssuerBuilder())
$clientMetadata = ClientMetadata::fromArray([
    'client_id' => 'client-id',
    'client_secret' => 'my-client-secret',
    'token_endpoint_auth_method' => 'client_secret_basic', // the auth method tor the token endpoint
    'redirect_uris' => [
$client = (new ClientBuilder())

// Authorization

$authorizationService = (new AuthorizationServiceBuilder())->build();
$redirectAuthorizationUri = $authorizationService->getAuthorizationUri(
    ['login_hint' => 'user_username'] // custom params
// you can use this uri to redirect the user

// Get access token

/** @var ServerRequestInterface::class $serverRequest */
$serverRequest = null; // get your server request
$callbackParams = $authorizationService->getCallbackParams($serverRequest, $client);
$tokenSet = $authorizationService->callback($client, $callbackParams);

$idToken = $tokenSet->getIdToken(); // Unencrypted id_token
$accessToken = $tokenSet->getAccessToken(); // Access token
$refreshToken = $tokenSet->getRefreshToken(); // Refresh token

$claims = $tokenSet->claims(); // IdToken claims (if id_token is available)

// Refresh token
$tokenSet = $authorizationService->refresh($client, $tokenSet->getRefreshToken());

// Get user info
$userInfoService = (new UserInfoServiceBuilder())->build();
$userInfo = $userInfoService->getUserInfo($client, $tokenSet);

Client registration

See OpenID Connect Dynamic Client Registration 1.0 and RFC7591 OAuth 2.0 Dynamic Client Registration Protocol.

use Facile\OpenIDClient\Service\Builder\RegistrationServiceBuilder;

$registration = (new RegistrationServiceBuilder())->build();

// registration
$metadata = $registration->register(
        'client_name' => 'My client name',
        'redirect_uris' => [''],

// read
$metadata = $registration->read($metadata['registration_client_uri'], $metadata['registration_access_token']);

// update
$metadata = $registration->update(
    array_merge($metadata, [
        // new metadata

// delete
$registration->delete($metadata['registration_client_uri'], $metadata['registration_access_token']);

Token Introspection

See RFC7662 - OAuth 2.0 Token Introspection.

use Facile\OpenIDClient\Service\Builder\IntrospectionServiceBuilder;

$service = (new IntrospectionServiceBuilder())->build();

$params = $service->introspect($client, $token);

Token Revocation

See RFC7009 - OAuth 2.0 Token Revocation.

use Facile\OpenIDClient\Service\Builder\RevocationServiceBuilder;

$service = (new RevocationServiceBuilder())->build();

$params = $service->revoke($client, $token);

Request Object

You can create a request object authorization request with the Facile\OpenIDClient\RequestObject\RequestObjectFactory class.

This will create a signed (and optionally encrypted) JWT token based on your client metadata.

use Facile\OpenIDClient\RequestObject\RequestObjectFactory;

$factory = new RequestObjectFactory();
$requestObject = $factory->create($client, [/* custom claims to include in the JWT*/]);

Then you can use it to create the AuthRequest:

use Facile\OpenIDClient\Authorization\AuthRequest;

$authRequest = AuthRequest::fromParams([
    'client_id' => $client->getMetadata()->getClientId(),
    'redirect_uri' => $client->getMetadata()->getRedirectUris()[0],
    'request' => $requestObject,

Aggregated and Distributed Claims

The library can handle aggregated and distributed claims:

use Facile\OpenIDClient\Claims\AggregateParser;
use Facile\OpenIDClient\Claims\DistributedParser;

$aggregatedParser = new AggregateParser();

$claims = $aggregatedParser->unpack($client, $userInfo);

$distributedParser = new DistributedParser();
$claims = $distributedParser->fetch($client, $userInfo);

Using middlewares

There are some middlewares and handles available:


This middleware should always be on top of middlewares chain to provide a session for state and nonce parameters.

To use it you should install the dflydev/fig-cookies package:

$ composer require "dflydev/fig-cookies:^2.0"
use Facile\OpenIDClient\Middleware\SessionCookieMiddleware;
use Psr\SimpleCache\CacheInterface;

// Use your PSR-16 simple-cache implementation to persist sessions
/** @var CacheInterface $cache */
$middleware = new SessionCookieMiddleware($cache/* , $cookieName = "openid", $ttl = 300 */);

The middleware provides a Facile\OpenIDClient\Session\AuthSessionInterface attribute with an Facile\OpenIDClient\Session\AuthSessionInterface stateful instance used to persist session data.

Using another session storage

If you have another session storage, you can handle it and provide a Facile\OpenIDClient\Session\AuthSessionInterface instance in the Facile\OpenIDClient\Session\AuthSessionInterface attribute.


This middleware should always be on top of middlewares chain to provide the client to the other middlewares.

use Facile\OpenIDClient\Middleware\ClientProviderMiddleware;

$client = $container->get('openid.clients.default');
$middleware = new ClientProviderMiddleware($client);


This middleware provide the auth request to use with the AuthRedirectHandler.

use Facile\OpenIDClient\Middleware\AuthRequestProviderMiddleware;
use Facile\OpenIDClient\Authorization\AuthRequest;

$authRequest = AuthRequest::fromParams([
    'scope' => 'openid',
    // other params...
$middleware = new AuthRequestProviderMiddleware($authRequest);


This handler will redirect the user to the OpenID authorization page.

use Facile\OpenIDClient\Middleware\AuthRedirectHandler;
use Facile\OpenIDClient\Service\AuthorizationService;

/** @var AuthorizationService $authorizationService */
$authorizationService = $container->get(AuthorizationService::class);
$middleware = new AuthRedirectHandler($authorizationService);


This middleware will handle the callback from the OpenID provider.

It will provide a Facile\OpenIDClient\Token\TokenSetInterface attribute with the final TokenSet object.

use Facile\OpenIDClient\Middleware\CallbackMiddleware;
use Facile\OpenIDClient\Service\AuthorizationService;

/** @var AuthorizationService $authorizationService */
$authorizationService = $container->get(AuthorizationService::class);
$middleware = new CallbackMiddleware($authorizationService);


This middleware will fetch user data from the userinfo endpoint and will provide an Facile\OpenIDClient\Middleware\UserInfoMiddleware attribute with user infos as array.

use Facile\OpenIDClient\Middleware\UserInfoMiddleware;
use Facile\OpenIDClient\Service\UserInfoService;

/** @var UserInfoService $userInfoService */
$userInfoService = $container->get(UserInfoService::class);
$middleware = new UserInfoMiddleware($userInfoService);

Performance improvements for production environment

It's important to use a cache to avoid to fetch issuer configuration and keys on every request.

use Psr\SimpleCache\CacheInterface;
use Facile\OpenIDClient\Issuer\IssuerBuilder;
use Facile\OpenIDClient\Issuer\Metadata\Provider\MetadataProviderBuilder;
use Facile\JoseVerifier\JWK\JwksProviderBuilder;

/** @var CacheInterface $cache */
$cache = $container->get(CacheInterface::class); // get your simple-cache implementation

$metadataProviderBuilder = (new MetadataProviderBuilder())
    ->setCacheTtl(86400*30); // Cache metadata for 30 days 
$jwksProviderBuilder = (new JwksProviderBuilder())
    ->setCacheTtl(86400); // Cache JWKS for 1 day
$issuerBuilder = (new IssuerBuilder())

$issuer = $issuerBuilder->build('');

Using Psalm

If you need to use Psalm you can include the plugin in your psalm.xml.

    <pluginClass class="Facile\JoseVerifier\Psalm\Plugin" />