Facile OpenID Client

https://github.com/facile-it/php-openid-client
Admin
Facile OpenID Client is a full OpenID Connect (OIDC) client library for PHP, supporting...
Tokens:199,668
Snippets:1,197
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install with Composer: composer require facile-it/php-openid-client

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Install the library via Composer. Requires PSR implementations for http-client, http-factory, and http-message. RSA signing algorithms are included; other algorithms require manual installation.

```bash
composer require facile-it/php-openid-client
```

--------------------------------

### Usage example — full middleware chain

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Example of setting up a full middleware chain including UserInfoMiddleware and retrieving the user info attribute.

```APIDOC
## Usage example — full middleware chain

### Description
Example of setting up a full middleware chain including UserInfoMiddleware and retrieving the user info attribute.

### Code
```php
use Facile\OpenIDClient\Middleware\SessionCookieMiddleware;
use Facile\OpenIDClient\Middleware\ClientProviderMiddleware;
use Facile\OpenIDClient\Middleware\AuthRequestProviderMiddleware;
use Facile\OpenIDClient\Middleware\AuthRedirectHandler;
use Facile\OpenIDClient\Middleware\CallbackMiddleware;
use Facile\OpenIDClient\Middleware\UserInfoMiddleware;
use Facile\OpenIDClient\Authorization\AuthRequest;

// SessionCookieMiddleware on top: provides AuthSessionInterface attribute
$middleware = new SessionCookieMiddleware($cache, 'openid', 300);

// Inside the chain:
$clientMiddleware = new ClientProviderMiddleware($client);
$authRequestMiddleware = new AuthRequestProviderMiddleware(
    AuthRequest::fromParams(['scope' => 'openid', 'client_id' => '...', 'redirect_uri' => '...'])
);
$redirectHandler = new AuthRedirectHandler($authorizationService); // handles the /login route
$callbackMiddleware = new CallbackMiddleware($authorizationService); // handles the /callback route
$userInfoMiddleware = new UserInfoMiddleware($userInfoService);

// Then in your route handler:
/** @var AuthSessionInterface $authSession */
$authSession = $request->getAttribute(Facile\OpenIDClient\Session\AuthSessionInterface::class);
/** @var TokenSetInterface $tokenSet */
$tokenSet = $request->getAttribute(Facile\OpenIDClient\Token\TokenSetInterface::class);
/** @var array<string, mixed> $userInfo */
$userInfo = $request->getAttribute(Facile\OpenIDClient\Middleware\UserInfoMiddleware::class);
```

```

--------------------------------

### Full middleware chain usage example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Shows how to set up a complete middleware chain including SessionCookieMiddleware, ClientProviderMiddleware, AuthRequestProviderMiddleware, AuthRedirectHandler, CallbackMiddleware, and UserInfoMiddleware. Also demonstrates retrieving attributes in a route handler.

```php
use Facile\OpenIDClient\Middleware\SessionCookieMiddleware;
use Facile\OpenIDClient\Middleware\ClientProviderMiddleware;
use Facile\OpenIDClient\Middleware\AuthRequestProviderMiddleware;
use Facile\OpenIDClient\Middleware\AuthRedirectHandler;
use Facile\OpenIDClient\Middleware\CallbackMiddleware;
use Facile\OpenIDClient\Middleware\UserInfoMiddleware;
use Facile\OpenIDClient\Authorization\AuthRequest;

// SessionCookieMiddleware on top: provides AuthSessionInterface attribute
$middleware = new SessionCookieMiddleware($cache, 'openid', 300);

// Inside the chain:
$clientMiddleware = new ClientProviderMiddleware($client);
$authRequestMiddleware = new AuthRequestProviderMiddleware(
    AuthRequest::fromParams(['scope' => 'openid', 'client_id' => '...', 'redirect_uri' => '...'])
);
$redirectHandler = new AuthRedirectHandler($authorizationService); // handles the /login route
$callbackMiddleware = new CallbackMiddleware($authorizationService); // handles the /callback route
$userInfoMiddleware = new UserInfoMiddleware($userInfoService);

// Then in your route handler:
/** @var AuthSessionInterface $authSession */
$authSession = $request->getAttribute(Facile\OpenIDClient\Session\AuthSessionInterface::class);
/** @var TokenSetInterface $tokenSet */
$tokenSet = $request->getAttribute(Facile\OpenIDClient\Token\TokenSetInterface::class);
/** @var array<string, mixed> $userInfo */
$userInfo = $request->getAttribute(Facile\OpenIDClient\Middleware\UserInfoMiddleware::class);
```

--------------------------------

### Revocation Usage Example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/introspection-revocation-services.md

Example of using the RevocationServiceBuilder to build a service and call the revoke method.

```APIDOC
## Revocation

```php
use Facile\OpenIDClient\Service\Builder\RevocationServiceBuilder;
use Facile\OpenIDClient\Exception\OAuth2Exception;

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

try {
    $service->revoke($client, $accessToken);
    // revoke with extra params, e.g. token_type_hint
    $service->revoke($client, $refreshToken, ['token_type_hint' => 'refresh_token']);
} catch (OAuth2Exception $e) {
    // provider returned an error for the revocation request
}
```
```

--------------------------------

### Basic fetch

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/userinfo-service.md

Example of fetching user info using the UserInfoServiceBuilder.

```APIDOC
## Basic fetch

```php
use Facile\OpenIDClient\Service\Builder\UserInfoServiceBuilder;

$userInfoService = (new UserInfoServiceBuilder())->build();

$userInfo = $userInfoService->getUserInfo($client, $tokenSet);
$email = $userInfo['email'] ?? null;
```
```

--------------------------------

### Install dflydev/fig-cookies for SessionCookieMiddleware

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Composer command to install the required package for SessionCookieMiddleware. Version ^2.0 is specified.

```bash
$ composer require "dflydev/fig-cookies:^2.0"
```

--------------------------------

### Basic OpenID Connect Flow with Authorization and UserInfo

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Shows the core usage: build an issuer from a discovery URL, create client metadata, build a client, perform authorization, handle callback, refresh token, and fetch user info. Requires PSR-7 server request for callback. The example includes custom params like 'login_hint' and throws RuntimeException if no ID token.

```php
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())
    ->build('https://example.com/.well-known/openid-configuration');
$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' => [
        'https://my-rp.com/callback',    
    ],
]);
$client = (new ClientBuilder())
    ->setIssuer($issuer)
    ->setClientMetadata($clientMetadata)
    ->build();

// Authorization

$authorizationService = (new AuthorizationServiceBuilder())->build();
$redirectAuthorizationUri = $authorizationService->getAuthorizationUri(
    $client,
    ['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, if returned
$accessToken = $tokenSet->getAccessToken(); // Access token, if returned
$refreshToken = $tokenSet->getRefreshToken(); // Refresh token, if returned

// check if we have an authenticated user
if ($idToken) {
    $claims = $tokenSet->claims(); // IdToken claims
} else {
    throw new \RuntimeException('Unauthorized');
}


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


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

--------------------------------

### Manual AuthSession usage

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/session.md

Manual usage example showing how to create an AuthSession, set state, nonce, code_verifier, and customs, serialize to JSON, and restore from the serialized array. Demonstrates the round-trip behavior.

```php
use Facile\OpenIDClient\Session\AuthSession;

$session = new AuthSession();
$session->setState('opaque-state');
$session->setNonce('opaque-nonce');
$session->setCodeVerifier('pkce-verifier');
$session->setCustoms(['login_hint' => 'user@example.com']);

$json = $session->jsonSerialize();
// ['state' => 'opaque-state', 'nonce' => 'opaque-nonce',
//  'code_verifier' => 'pkce-verifier', 'customs' => ['login_hint' => 'user@example.com']]

$restored = AuthSession::fromArray($json);
$restored->getState();       // 'opaque-state'
$restored->getCodeVerifier(); // 'pkce-verifier'
```

--------------------------------

### Static registration metadata example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client-metadata.md

Shows how to create client metadata statically using ClientMetadata::fromArray with common fields. The resulting object provides getters for token endpoint auth method and request object signing algorithm.

```php
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;

$metadata = ClientMetadata::fromArray([
    'client_id' => 'my-client',
    'client_secret' => 'super-secret',
    'redirect_uris' => ['https://rp.example.com/callback'],
    'token_endpoint_auth_method' => 'client_secret_post',
    'request_object_signing_alg' => 'RS256',
    'jwks' => ['keys' => [/* ... */]],
]);

$authMethod = $metadata->getTokenEndpointAuthMethod();  // 'client_secret_post'
$signingAlg = $metadata->getRequestObjectSigningAlg();  // 'RS256'

```

--------------------------------

### Metadata factory usage example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client-metadata.md

Shows how to use the MetadataFactory to create client metadata from an array. The factory's fromArray method returns a ClientMetadataInterface instance.

```php
use Facile\OpenIDClient\Client\Metadata\MetadataFactory;
use Facile\OpenIDClient\Client\Metadata\ClientMetadataInterface;

$factory = new MetadataFactory();
/** @var ClientMetadataInterface $clientMetadata */
$clientMetadata = $factory->fromArray(['client_id' => 'my-client', 'client_secret' => 's3cret']);

```

--------------------------------

### Usage example — full import block

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/functions.md

Full import block and typical usage of the Facile\OpenIDClient functions. Shows how to encode a random token, parse callback params, and call parse_metadata_response with expected status 200, catching OAuth2Exception. Also demonstrates jose_secret_key for HS256 (direct base64url secret) and derived_key for SHA-256 derived 32-byte key.

```php
use function Facile\OpenIDClient\base64url_decode;
use function Facile\OpenIDClient\base64url_encode;
use function Facile\OpenIDClient\check_server_response;
use function Facile\OpenIDClient\derived_key;
use function Facile\OpenIDClient\get_endpoint_uri;
use function Facile\OpenIDClient\jose_secret_key;
use function Facile\OpenIDClient\parse_callback_params;
use function Facile\OpenIDClient\parse_metadata_response;

// Typical application usage
$token = base64url_encode(random_bytes(32));
$params = parse_callback_params($serverRequest);

try {
    $data = parse_metadata_response($response, 200); // JSON body required, status 200
} catch (Facile\OpenIDClient\Exception\OAuth2Exception $e) {
    // error response from the provider
}

// Symmetric signing key for HS algorithms
$jwk = jose_secret_key('my-secret', 'HS256'); // kty=oct, direct base64url of the secret
$derived = derived_key('my-secret', 256);     // kty=oct, SHA-256 derived 32-byte key
```

--------------------------------

### Manual construction with extra claims and error handling

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/issuer-metadata.md

Example of constructing IssuerMetadata from an array with custom claims and handling missing required keys.

```APIDOC
## Manual construction with extra claims and error handling

### Description
Shows how to create an IssuerMetadata instance from an array, preserving unknown claims, and catching exceptions for missing required fields.

### Method
N/A (PHP method calls)

### Endpoint
N/A

### Parameters
#### Request Body
- **issuer** (string) - Required - The issuer identifier.
- **authorization_endpoint** (string) - Required - The authorization endpoint URL.
- **jwks_uri** (string) - Required - The JWKS URI.
- **token_endpoint** (string) - Optional - The token endpoint URL.
- **scopes_supported** (list<string>) - Optional - Supported scopes.
- **custom_claim** (mixed) - Optional - Any custom claim to preserve.

### Request Example
```php
use Facile\OpenIDClient\Issuer\Metadata\IssuerMetadata;
use Facile\OpenIDClient\Exception\InvalidArgumentException;

try {
    $metadata = IssuerMetadata::fromArray([
        'issuer' => 'https://op.example.com',
        'authorization_endpoint' => 'https://op.example.com/authorize',
        'jwks_uri' => 'https://op.example.com/jwks',
        'token_endpoint' => 'https://op.example.com/token',
        'scopes_supported' => ['openid', 'profile'],
        'custom_claim' => 'kept-as-is',
    ]);
    // Unknown claim is preserved and reachable
    $custom = $metadata->get('custom_claim'); // 'kept-as-is'
} catch (InvalidArgumentException $e) {
    // thrown when issuer / authorization_endpoint / jwks_uri are missing
    // message lists the missing keys
}
```

### Response
#### Success Response (200)
- **custom_claim** (mixed) - The custom claim value.

#### Response Example
```php
$custom; // 'kept-as-is'
```

#### Error Response
- **InvalidArgumentException** - Thrown when required fields (issuer, authorization_endpoint, jwks_uri) are missing.
```

--------------------------------

### GET [clientUri]

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/registration-service.md

Reads the current client registration from the provider using the registration client URI and access token.

```APIDOC
## GET [clientUri]

### Description
Reads the current client registration from the provider using the registration client URI and access token.

### Method
GET

### Endpoint
`{clientUri}` (the `registration_client_uri` from registration)

### Parameters
#### Path Parameters
- **clientUri** (string) - Required - The registration client URI.

#### Query Parameters
None

#### Request Headers
- **Authorization** (string) - Required - Bearer token (the `registration_access_token`).

### Request Example
```http
GET /register/client123 HTTP/1.1
Host: provider.example.com
Authorization: Bearer token123
Accept: application/json
```

### Response
#### Success Response (200)
- **client_id** (string) - The client identifier.
- **client_secret** (string) - The client secret.
- **registration_access_token** (string) - Access token for client management.
- **registration_client_uri** (string) - URI for client management.

#### Response Example
```json
{
  "client_id": "client123",
  "client_secret": "secret123",
  "registration_access_token": "token123",
  "registration_client_uri": "https://provider.example.com/register/client123"
}
```
```

--------------------------------

### IssuerBuilder with caching and error handling

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/issuer.md

Production example with caching for discovery metadata and JWKS, plus error handling for runtime and invalid argument exceptions.

```php
use Facile\OpenIDClient\Issuer\IssuerBuilder;
use Facile\OpenIDClient\Issuer\Metadata\Provider\MetadataProviderBuilder;
use Facile\JoseVerifier\JWK\JwksProviderBuilder;
use Facile\OpenIDClient\Exception\RuntimeException;
use Facile\OpenIDClient\Exception\InvalidArgumentException;
use Psr\SimpleCache\CacheInterface;

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

$metadataProviderBuilder = (new MetadataProviderBuilder())
    ->setCache($cache)
    ->setCacheTtl(86400 * 30); // cache discovery metadata for 30 days

$jwksProviderBuilder = (new JwksProviderBuilder())
    ->setCache($cache)
    ->setCacheTtl(86400); // cache JWKS for 1 day

$issuerBuilder = (new IssuerBuilder())
    ->setMetadataProviderBuilder($metadataProviderBuilder)
    ->setJwksProviderBuilder($jwksProviderBuilder);

try {
    $issuer = $issuerBuilder->build('https://example.com');
} catch (RuntimeException $e) {
    // provider unreachable, bad response, or issuer mismatch
} catch (InvalidArgumentException $e) {
    // metadata is not a valid OpenID configuration
}
```

--------------------------------

### DiscoveryProvider

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Concrete discovery provider class with usage example using PSR-18 client and PSR-17 factories.

```APIDOC
## DiscoveryProvider

### Description
Concrete class for discovery metadata provider. Uses PSR-18 client and PSR-17 factories.

### Constructor
- **__construct(Psr\Http\Client\ClientInterface $client, Psr\Http\Message\RequestFactoryInterface $requestFactory, Psr\Http\Message\UriFactoryInterface $uriFactory)** - Creates a new DiscoveryProvider instance.

### Methods

#### isAllowedUri
- **isAllowedUri(string $uri): bool** - Checks if the given URI is allowed.

#### discovery
- **discovery(string $url): array** - Performs discovery against the given URL and returns metadata array.

### Usage Example
```php
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;
use Facile\OpenIDClient\Issuer\Metadata\Provider\DiscoveryProvider;

$discovery = new DiscoveryProvider(
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findUriFactory()
);

if ($discovery->isAllowedUri('https://op.example.com')) {
    $metadata = $discovery->discovery('https://op.example.com'); // array
}
```
```

--------------------------------

### Validation error and custom claims example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client-metadata.md

Demonstrates validation error when required keys are missing and how to create metadata with custom claims. The constructor allows custom claims, and the has/get methods check and retrieve them, returning null for missing keys.

```php
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Exception\InvalidArgumentException;

try {
    ClientMetadata::fromArray(['redirect_uris' => ['https://rp.example.com/callback']]);
} catch (InvalidArgumentException $e) {
    // 'Invalid client metadata. Missing keys: client_id'
}

$metadata = new ClientMetadata('client-id', [
    'custom_extension_claim' => ['x' => 1],
]);
$metadata->has('custom_extension_claim'); // true
$metadata->get('custom_extension_claim'); // ['x' => 1]
$metadata->get('missing');                // null

```

--------------------------------

### Error handling for SessionCookieMiddleware

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Shows how to catch LogicException when dflydev/fig-cookies is not installed and RuntimeException when the cache write fails with 'Unable to save session'.

```php
use Facile\OpenIDClient\Middleware\SessionCookieMiddleware;
use Facile\OpenIDClient\Exception\LogicException;
use Facile\OpenIDClient\Exception\RuntimeException;

try {
    $response = (new SessionCookieMiddleware($cache))->process($request, $handler);
} catch (LogicException $e) {
    // dflydev/fig-cookies is not installed
} catch (RuntimeException $e) {
    // 'Unable to save session' — cache write failed
}
```

--------------------------------

### base64url_encode usage example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/functions.md

Example usage of base64url_encode. It encodes the string 'openid' to 'b3Blbmlk'.

```php
use function Facile\OpenIDClient\base64url_encode;

$encoded = base64url_encode('openid'); // 'b3Blbmlk'
```

--------------------------------

### Builder composition with caching

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Shows how to build a metadata provider with a PSR-16 cache and TTL, then fetch metadata via WebFinger or discovery. Throws RuntimeException if all providers fail.

```php
use Facile\OpenIDClient\Issuer\Metadata\Provider\MetadataProviderBuilder;
use Facile\OpenIDClient\Exception\RuntimeException;
use Psr\SimpleCache\CacheInterface;

/** @var CacheInterface $cache */
$provider = (new MetadataProviderBuilder())
    ->setCache($cache)
    ->setCacheTtl(3600)
    ->build();

try {
    $rawMetadata = $provider->fetch('acct:user@op.example.com'); // webfinger path
    // or $provider->fetch('https://op.example.com'); // discovery path
} catch (RuntimeException $e) {
    // 'Unable to fetch issuer metadata' — all providers failed
}
```

--------------------------------

### Introspection Usage Example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/introspection-revocation-services.md

Example of using the IntrospectionServiceBuilder to build a service and call the introspect method.

```APIDOC
## Introspection

```php
use Facile\OpenIDClient\Service\Builder\IntrospectionServiceBuilder;

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

$params = $service->introspect($client, $accessToken);
$active = true === $params['active'];
```
```

--------------------------------

### base64url_decode usage example

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/functions.md

Example usage of base64url_decode. It decodes the base64url string 'b3Blbmlk' back to 'openid'.

```php
use function Facile\OpenIDClient\base64url_decode;

$decoded = base64url_decode('b3Blbmlk'); // 'openid'
```

--------------------------------

### Instantiate ClientProviderMiddleware

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Creates a ClientProviderMiddleware with a client instance. This middleware should be on top of the chain to provide the client to other middlewares.

```php
use Facile\OpenIDClient\Middleware\ClientProviderMiddleware;

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

--------------------------------

### ClientMetadata::get

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client-metadata.md

Gets a metadata claim value.

```APIDOC
## ClientMetadata::get

### Description
Returns the value of a metadata claim, or null if not present.

### Method
get

### Signature
public function get(string $name): mixed

### Parameters
- **name** (string) - Required - The claim name.

### Returns
mixed - The claim value, or null if not present.

### Example
```php
$metadata->get('custom_extension_claim'); // ['x' => 1]
$metadata->get('missing');                // null
```
```

--------------------------------

### Direct use with a PSR client

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Shows how to instantiate DiscoveryProvider with PSR-18 and PSR-17 discovery, check allowed URI, and fetch metadata.

```php
use Http\Discovery\Psr17FactoryDiscovery;
use Http\Discovery\Psr18ClientDiscovery;
use Facile\OpenIDClient\Issuer\Metadata\Provider\DiscoveryProvider;

$discovery = new DiscoveryProvider(
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findUriFactory()
);

if ($discovery->isAllowedUri('https://op.example.com')) {
    $metadata = $discovery->discovery('https://op.example.com'); // array
}
```

--------------------------------

### UserInfoServiceBuilder

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/userinfo-service.md

Documentation for the UserInfoServiceBuilder class, including its methods and usage examples.

```APIDOC
## Class `UserInfoServiceBuilder` (final)

`src/Service/Builder/UserInfoServiceBuilder.php` — `@psalm-api`, extends `AbstractServiceBuilder`.

```php
final class UserInfoServiceBuilder extends AbstractServiceBuilder
{
    private ?TokenVerifierBuilderInterface $userInfoVerifierBuilder = null;

    protected function getUserInfoVerifierBuilder(): TokenVerifierBuilderInterface
    {
        return $this->userInfoVerifierBuilder ??= new UserInfoVerifierBuilder();
    }

    public function build(): UserInfoService
}
```

| Method | Notes |
|--------|-------|
| `setHttpClient(ClientInterface)` / `setRequestFactory(RequestFactoryInterface)` | inherited from `AbstractServiceBuilder` (see [authorization-service.md](authorization-service.md)) |
| `getUserInfoVerifierBuilder()` | protected; the verifier builder cannot be injected from outside — it is always `new UserInfoVerifierBuilder()` |
| `build()` | returns a new `UserInfoService` |
```

--------------------------------

### Register, read, update, and delete a client with RegistrationServiceBuilder

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Shows the full lifecycle of dynamic client registration: register with initial token, read metadata, update metadata, and delete the client. Uses the RegistrationServiceBuilder from Facile\OpenIDClient.

```php
use Facile\OpenIDClient\Service\Builder\RegistrationServiceBuilder;

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

// registration
$metadata = $registration->register(
    $issuer,
    [
        'client_name' => 'My client name',
        'redirect_uris' => ['https://my-rp.com/callback'],
    ],
    'my-initial-token'
);

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

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

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

--------------------------------

### CallbackMiddleware Constructor

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Initializes the middleware with the required authorization service and optional client, redirect URI, and max age parameters.

```php
public function __construct(
    AuthorizationService $authorizationService,
    ?ClientInterface $client = null,
    ?string $redirectUri = null,
    ?int $maxAge = null
)
```

--------------------------------

### Error handling

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Example of handling exceptions thrown by the middleware chain.

```APIDOC
## Error handling

### Description
Example of handling exceptions thrown by the middleware chain.

### Code
```php
use Facile\OpenIDClient\Middleware\SessionCookieMiddleware;
use Facile\OpenIDClient\Exception\LogicException;
use Facile\OpenIDClient\Exception\RuntimeException;

try {
    $response = (new SessionCookieMiddleware($cache))->process($request, $handler);
} catch (LogicException $e) {
    // dflydev/fig-cookies is not installed
} catch (RuntimeException $e) {
    // 'Unable to save session' — cache write failed
}
```

```

--------------------------------

### UserInfoMiddleware::__construct

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Creates a new UserInfoMiddleware instance with a UserInfoService and an optional ClientInterface.

```APIDOC
## UserInfoMiddleware::__construct

### Description
Creates a new UserInfoMiddleware instance.

### Method
__construct

### Signature
```php
public function __construct(
    UserInfoService $userInfoService,
    ?ClientInterface $client = null
)
```

### Parameters
- **userInfoService** (UserInfoService) - Required - Service fetching the user claims
- **client** (?ClientInterface) - Optional - The client; defaults to null, falls back to the attribute

```

--------------------------------

### MetadataProviderBuilder

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Builder class for metadata providers with caching support and usage example.

```APIDOC
## MetadataProviderBuilder

### Description
Builder class for constructing metadata providers with optional caching.

### Methods

#### setCache
- **setCache(Psr\SimpleCache\CacheInterface $cache): self** - Sets the cache implementation.

#### setCacheTtl
- **setCacheTtl(int $ttl): self** - Sets the cache TTL in seconds.

#### build
- **build(): RemoteProviderInterface** - Builds and returns the metadata provider.

### Usage Example
```php
use Facile\OpenIDClient\Issuer\Metadata\Provider\MetadataProviderBuilder;
use Facile\OpenIDClient\Exception\RuntimeException;
use Psr\SimpleCache\CacheInterface;

/** @var CacheInterface $cache */
$provider = (new MetadataProviderBuilder())
    ->setCache($cache)
    ->setCacheTtl(3600)
    ->build();

try {
    $rawMetadata = $provider->fetch('acct:user@op.example.com'); // webfinger path
    // or $provider->fetch('https://op.example.com'); // discovery path
} catch (RuntimeException $e) {
    // 'Unable to fetch issuer metadata' — all providers failed
}
```
```

--------------------------------

### WebFingerProvider::__construct

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Constructor for WebFingerProvider. Initializes the provider with required HTTP client, request factory, URI factory, and discovery provider.

```APIDOC
## WebFingerProvider::__construct

### Description
Constructor for the WebFingerProvider class. Initializes the provider with the required dependencies.

### Method
Constructor

### Signature
```php
public function __construct(
    ClientInterface $client,
    RequestFactoryInterface $requestFactory,
    UriFactoryInterface $uriFactory,
    DiscoveryProviderInterface $discoveryProvider
)
```

### Parameters
- **client** (Psr\Http\Client\ClientInterface) - Required - HTTP client used for requests.
- **requestFactory** (Psr\Http\Message\RequestFactoryInterface) - Required - Factory for creating HTTP requests.
- **uriFactory** (Psr\Http\Message\UriFactoryInterface) - Required - Factory for creating URI instances.
- **discoveryProvider** (DiscoveryProviderInterface) - Required - Used to resolve the discovered href to full metadata.

### Response
No return value.
```

--------------------------------

### Read-only inspection

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/issuer-metadata.md

Example of reading issuer metadata values using getter methods.

```APIDOC
## Read-only inspection

### Description
Demonstrates how to retrieve issuer metadata values such as issuer, token endpoint, PKCE support, and registration endpoint support.

### Method
N/A (PHP method calls)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
use Facile\OpenIDClient\Issuer\Metadata\IssuerMetadata;

$metadata = IssuerMetadata::fromArray($discoveryDocument);

$issuer = $metadata->getIssuer();
$tokenEndpoint = $metadata->getTokenEndpoint(); // ?string
$supportPkce = in_array('S256', $metadata->getCodeChallengeMethodsSupported() ?? []);
$supportsRegistration = null !== $metadata->getRegistrationEndpoint();
```

### Response
#### Success Response (200)
- **issuer** (string) - The issuer identifier.
- **tokenEndpoint** (string|null) - The token endpoint URL.
- **codeChallengeMethodsSupported** (list<string>|null) - Supported PKCE code challenge methods.
- **registrationEndpoint** (string|null) - The registration endpoint URL.

#### Response Example
```php
$issuer; // 'https://op.example.com'
$tokenEndpoint; // 'https://op.example.com/token' or null
$supportPkce; // true or false
$supportsRegistration; // true or false
```
```

--------------------------------

### Build with Issuer and static metadata

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client.md

Shows how to construct a client with an issuer and static metadata using the ClientBuilder.

```APIDOC
## Build with Issuer and static metadata

### Description
Demonstrates how to build a client using an issuer and static client metadata.

### Code Example
```php
use Facile\OpenIDClient\Client\ClientBuilder;
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Issuer\IssuerBuilder;

$issuer = (new IssuerBuilder())->build('https://op.example.com/.well-known/openid-configuration');

$clientMetadata = ClientMetadata::fromArray([
    'client_id' => 'client-id',
    'client_secret' => 'my-client-secret',
    'token_endpoint_auth_method' => 'client_secret_basic',
    'redirect_uris' => ['https://my-rp.com/callback'],
]);

$client = (new ClientBuilder())
    ->setIssuer($issuer)
    ->setClientMetadata($clientMetadata)
    ->build();
```
```

--------------------------------

### get(string $name)

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/issuer-metadata.md

Returns the value of the specified metadata claim, or null when absent.

```APIDOC
## get(string $name)

### Description
Returns the value of the metadata claim identified by `$name`, or `null` when the claim is absent. The implementation is `$this->metadata[$name] ?? null`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
#### Path Parameters
- **$name** (string) - Required - The claim name to retrieve.

### Response
#### Success Response
- **mixed** - The claim value, or `null` if not present.

#### Response Example
```json
null
```
```

--------------------------------

### Handling errors and non-200 responses

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/userinfo-service.md

Example of handling errors and non-200 responses when fetching user info.

```APIDOC
## Handling errors and non-200 responses

```php
use Facile\OpenIDClient\Service\Builder\UserInfoServiceBuilder;
use Facile\OpenIDClient\Exception\OAuth2Exception;
use Facile\OpenIDClient\Exception\RuntimeException;
use Facile\OpenIDClient\Exception\RemoteException;

$userInfoService = (new UserInfoServiceBuilder())->build();

try {
    $userInfo = $userInfoService->getUserInfo($client, $tokenSet, true); // POST form body
} catch (OAuth2Exception $e) {
    // provider returned an OAuth2 error payload
} catch (RemoteException $e) {
    // non-200 response whose body was not a parseable OAuth2 error JSON
    $status = $e->getResponse()->getStatusCode();
} catch (RuntimeException $e) {
    // network error, 'Unable to get an access token...', sub mismatch, etc.
}
```
```

--------------------------------

### Instantiate UserInfoMiddleware

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Creates a UserInfoMiddleware with a UserInfoService. This middleware fetches user data from the userinfo endpoint and provides an attribute with user infos as array.

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

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

--------------------------------

### IssuerInterface definition

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/issuer.md

Interface defining the contract for an issuer, requiring methods to get metadata and JWKS provider.

```php
interface IssuerInterface
{
    public function getMetadata(): IssuerMetadataInterface;

    public function getJwksProvider(): JwksProviderInterface;
}
```

--------------------------------

### Configure client metadata for signing/encryption and handle errors

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/request-object-factory.md

Configures client metadata for signing and encryption of request objects, then builds the client and creates a request object with error handling. Also shows how to use a custom algorithm manager with only the required algorithms (e.g., RS256).

```php
use Facile\OpenIDClient\RequestObject\RequestObjectFactory;
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Issuer\IssuerBuilder;
use Facile\OpenIDClient\Client\ClientBuilder;
use Facile\OpenIDClient\Exception\RuntimeException;

$clientMetadata = ClientMetadata::fromArray([
    'client_id' => 'my-client',
    'client_secret' => 'my-secret',
    'redirect_uris' => ['https://rp.example.com/callback'],
    'request_object_signing_alg' => 'HS256',                 // signed with the client secret
    'request_object_encryption_alg' => 'RSA-OAEP-256',       // encrypted to the issuer's JWKS
    'request_object_encryption_enc' => 'A256GCM',
]);

$client = (new ClientBuilder())
    ->setIssuer($issuer)
    ->setClientMetadata($clientMetadata)
    ->build();

try {
    $requestObject = (new RequestObjectFactory())->create($client);
} catch (RuntimeException $e) {
    // 'No key to sign with alg ...' or 'No key to encrypt with alg ...'
}

// Custom algorithm set: only what your issuer requires
use Facile\OpenIDClient\AlgorithmManagerBuilder;
use Jose\Component\Signature\Algorithm\RS256;

$factory = new RequestObjectFactory(
    (new AlgorithmManagerBuilder([RS256::class]))->build()
);
```

--------------------------------

### Custom Auth Method Configuration

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/introspection-revocation-services.md

Example of configuring custom authentication methods for the introspection and revocation endpoints via client metadata.

```APIDOC
## Custom auth method per endpoint

Both services use the metadata claims `introspection_endpoint_auth_method` and `revocation_endpoint_auth_method` respectively, falling back to `token_endpoint_auth_method` (see [client-metadata.md](client-metadata.md)). Configure them at registration time:

```php
$metadata = ClientMetadata::fromArray([
    'client_id' => 'my-client',
    'client_secret' => 's3cret',
    'introspection_endpoint_auth_method' => 'client_secret_post',
    'revocation_endpoint_auth_method' => 'client_secret_basic',
]);
```
```

--------------------------------

### Client::__construct

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/configuration.md

Constructor parameters for the Client class for direct instantiation.

```APIDOC
## Client Constructor

### Description
Directly instantiates a Client with required issuer and metadata, and optional dependencies.

### Parameters
- **issuer** (`IssuerInterface`) - Required - The resolved provider.
- **metadata** (`ClientMetadataInterface`) - Required - Client registration metadata.
- **jwksProvider** (`?JwksProviderInterface`) - Optional - Default: `new MemoryJwksProvider()` - Client signing keys provider.
- **authMethodFactory** (`?AuthMethodFactoryInterface`) - Optional - Default: all seven methods (ClientSecretBasic, ClientSecretJwt, ClientSecretPost, None, PrivateKeyJwt, TLSClientAuth, SelfSignedTLSClientAuth) - Token-endpoint auth methods factory.
- **httpClient** (`?Psr\Http\Client\ClientInterface`) - Optional - Default: `null` - Per-client HTTP client; services fall back to their own injected client.
```

--------------------------------

### RegistrationServiceBuilder::build()

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/registration-service.md

Builds and returns a RegistrationService instance using the configured HTTP client and request factory.

```APIDOC
## RegistrationServiceBuilder::build()

### Description
Builds a RegistrationService instance using the configured HTTP client and request factory.

### Method
build

### Signature
public function build(): RegistrationService

### Parameters
None

### Return Value
- **RegistrationService** - The built service instance.

### Example
```php
$registration = (new RegistrationServiceBuilder())->build();
```
```

--------------------------------

### Build client with issuer and static metadata

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client.md

Builds a client using an issuer discovered from the OpenID configuration URL and static client metadata. The metadata includes client_id, client_secret, token_endpoint_auth_method, and redirect_uris.

```php
use Facile\OpenIDClient\Client\ClientBuilder;
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Issuer\IssuerBuilder;

$issuer = (new IssuerBuilder())->build('https://op.example.com/.well-known/openid-configuration');

$clientMetadata = ClientMetadata::fromArray([
    'client_id' => 'client-id',
    'client_secret' => 'my-client-secret',
    'token_endpoint_auth_method' => 'client_secret_basic',
    'redirect_uris' => ['https://my-rp.com/callback'],
]);

$client = (new ClientBuilder())
    ->setIssuer($issuer)
    ->setClientMetadata($clientMetadata)
    ->build();
```

--------------------------------

### Client::__construct

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/client.md

Constructor for the Client class, bundling issuer, metadata, JWKS provider, auth method factory, and optional HTTP client.

```APIDOC
## Client Constructor

### Description
Creates a new Client instance bundling the issuer, client metadata, JWKS provider, auth method factory, and optional HTTP client.

### Method
Constructor

### Signature
```php
public function __construct(
    IssuerInterface $issuer,
    ClientMetadataInterface $metadata,
    ?JwksProviderInterface $jwksProvider = null,
    ?AuthMethodFactoryInterface $authMethodFactory = null,
    ?HttpClient $httpClient = null
)
```

### Parameters
- **issuer** (IssuerInterface) - Required - Resolved OpenID provider
- **metadata** (ClientMetadataInterface) - Required - Client metadata (must at least carry `client_id`)
- **jwksProvider** (?JwksProviderInterface) - Optional - Client's JWKS provider (`Facile\JoseVerifier\JWK`), defaults to `new MemoryJwksProvider()`
- **authMethodFactory** (?AuthMethodFactoryInterface) - Optional - Factory of token-endpoint auth methods, defaults to `new AuthMethodFactory([ClientSecretBasic, ClientSecretJwt, ClientSecretPost, None, PrivateKeyJwt, TLSClientAuth, SelfSignedTLSClientAuth])`
- **httpClient** (?Psr\Http\Client\ClientInterface as HttpClient) - Optional - Optional per-client HTTP client; when `null`, services fall back to their own injected client
```

--------------------------------

### AuthSession cache round-trip

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/session.md

Round-trip example through a cache with fallback. Reads stored JSON (defaulting to '[]'), decodes with JSON_THROW_ON_ERROR, restores the session, mutates the state, and persists back with a 300-second TTL.

```php
use Facile\OpenIDClient\Session\AuthSession;

$stored = $cache->get($sessionId) ?? '[]';

/** @var array<string, mixed> $data */
$data = json_decode($stored, true, 512, JSON_THROW_ON_ERROR);
$session = AuthSession::fromArray($data);

// mutate, persist
$session->setState($newState);
$cache->set($sessionId, json_encode($session, JSON_THROW_ON_ERROR), 300);
```

--------------------------------

### WebFingerProvider constructor

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Constructor for WebFingerProvider. Requires PSR-18 client, PSR-17 request and URI factories, and a DiscoveryProviderInterface to resolve the discovered href to full metadata. All parameters are mandatory.

```php
public function __construct(
    ClientInterface $client,
    RequestFactoryInterface $requestFactory,
    UriFactoryInterface $uriFactory,
    DiscoveryProviderInterface $discoveryProvider
)
```

--------------------------------

### DiscoveryProvider

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/metadata-providers.md

Documentation for the DiscoveryProvider class, including its constructor, constants, and public methods.

```APIDOC
## Class `DiscoveryProvider` (final)

### Description
Final class implementing `DiscoveryProviderInterface` (which extends `RemoteProviderInterface`). It fetches OpenID Connect / OAuth 2.0 provider metadata via the well-known discovery documents.

### Constructor

```php
public function __construct(
    ClientInterface $client,
    RequestFactoryInterface $requestFactory,
    UriFactoryInterface $uriFactory
)
```

| Parameter | Type | Required |
|-----------|------|----------|
| `client` | `Psr\Http\Client\ClientInterface` | yes |
| `requestFactory` | `Psr\Http\Message\RequestFactoryInterface` | yes |
| `uriFactory` | `Psr\Http\Message\UriFactoryInterface` | yes |

### Constants

```php
private const OIDC_DISCOVERY = '/.well-known/openid-configuration';
private const OAUTH2_DISCOVERY = '/.well-known/oauth-authorization-server';
```

### Methods

#### `isAllowedUri`

```php
#[Override]
public function isAllowedUri(string $uri): bool
```

Returns `true` when the URI matches `https?://` (regex `preg_match('/https?:\/\//', $uri) > 0`).

#### `discovery`

```php
#[Override]
public function discovery(string $url): array
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | `string` | yes | Resource URL or host |

**Behavior:**
1. Parse `$url`; take its path (`'/'` when empty).
2. If the path already contains `/.well-known/`, fetch it directly.
3. Otherwise try, in order: `<path>/.well-known/openid-configuration`, then `<path>/.well-known/oauth-authorization-server` (the second URI becomes just `/.well-known/oauth-authorization-server` at root).
4. If all fetches throw `RuntimeException` (caught and swallowed per attempt), rethrows `RuntimeException('Unable to fetch provider metadata')`.

**Throws** `Facile\OpenIDClient\Exception\RuntimeException`:
- `'Unable to fetch provider metadata'` (with original `ClientExceptionInterface` as previous) when the HTTP client fails;
- `'Invalid metadata content, no "issuer" key found'` when the JSON body has no `issuer` key.

#### `fetch`

```php
#[Override]
public function fetch(string $uri): array
```

Delegates to `$this->discovery($uri)`.
```

--------------------------------

### UserInfoMiddleware constructor signature

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/middleware.md

Constructor for UserInfoMiddleware. Requires a UserInfoService and optionally a ClientInterface. If no client is provided, it falls back to the ClientInterface attribute on the request.

```php
public const USERINFO_ATTRIBUTE = self::class;

public function __construct(
    UserInfoService $userInfoService,
    ?ClientInterface $client = null
)
```

--------------------------------

### UserInfoService::getUserInfo signature

Source: https://github.com/facile-it/php-openid-client/blob/master/_autodocs/api-reference/userinfo-service.md

Method signature for retrieving UserInfo claims. Sends GET by default, or POST with access_token in the body when $useBody is true. Throws RuntimeException when no access token is present, InvalidArgumentException for a missing endpoint, and OAuth2Exception for non-200 responses.

```php
public function getUserInfo(OpenIDClient $client, TokenSetInterface $tokenSet, bool $useBody = false): array
```

--------------------------------

### Instantiate SessionCookieMiddleware

Source: https://github.com/facile-it/php-openid-client/blob/master/README.md

Creates a SessionCookieMiddleware with a PSR-16 cache implementation. The middleware must be on top of the middleware chain to provide session for state and nonce parameters. Optional parameters for cookie name and TTL are shown in comments.

```php
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 */);
```
Tokens:
Raw