Download the PHP package hvatum/oauth2-openid-connect-client without Composer

OpenID Connect Client for The PHP League OAuth2 Client

A generic OpenID Connect provider for The PHP League's OAuth2 Client, with built-in support for modern OAuth 2.0 security features:

• OpenID Connect Discovery — Automatic endpoint configuration via .well-known/openid-configuration
• PAR (Pushed Authorization Requests) — RFC 9126
• PKCE (Proof Key for Code Exchange) — RFC 7636 with S256
• DPoP (Demonstrating Proof of Possession) — RFC 9449
• Private Key JWT client authentication — RFC 7523
• ID Token validation — Signature verification, claim validation, nonce checking
• Rich Authorization Requests — RFC 9396 parameter transport with extension hooks
• RFC 9207 — Authorization Server Issuer Identification (mix-up attack protection)

Disclaimer

OAuth2 and its related standards are complex topics to understand and to get right. This library strives to be correct but mistakes can be made. There is NO WARRANTY, use at your own risk, and please leave a bug report or a pull request if you find something that seems off.

Requirements

• PHP 8.2 or later
• ext-json
• ext-openssl

Installation

Basic Usage

The simplest setup — just point to the issuer:

All endpoints (authorization, token, userinfo, JWKS, PAR) are automatically discovered from {issuer}/.well-known/openid-configuration.

Authorization Code Flow

Advanced Usage

Private Key JWT Authentication (RFC 7523)

Use private_key_jwt instead of client_secret for client authentication:

Supports EC (ES256/ES384/ES512) and RSA (RS256/RS384/RS512, PS256/PS384/PS512) keys in both PEM and JWK formats.

Loading keys from environment variables

For 12-factor / Kubernetes-style deployments where the key is injected via an environment variable rather than mounted on disk, use privateKey to pass the raw PEM or JWK JSON content directly:

privateKey (raw content) and privateKeyPath (filesystem path) are mutually exclusive — setting both throws an InvalidArgumentException at construction. An empty string is treated as unset, so an unset env var bound to '' falls back to a configured privateKeyPath rather than silently disabling client assertion.

DPoP Token Binding (RFC 9449)

Bind access tokens to a cryptographic key pair to prevent token theft:

DPoP keys follow the same contract as privateKey / privateKeyPath: dpopPrivateKey and dpopPublicKey accept raw PEM/JWK content for env-var deployments, while dpopPrivateKeyPath and dpopPublicKeyPath accept filesystem paths. Each *Key option is mutually exclusive with its *KeyPath counterpart. The public key may be omitted entirely — it is derived from the private key.

ID Token Validation

ID tokens are automatically validated when fetching resource owner details. You can also validate manually:

Validates: signature (ES256/384/512, RS256/384/512, PS256/384/512), issuer, audience, expiration, nonce, and more.

Caching

Well-known configuration and JWKS keys are cached using PSR-16 (SimpleCache). TTL is managed by the cache implementation, so expiry works correctly across PHP-FPM requests.

By default, a built-in filesystem cache is used. You can customize the directory and TTLs:

Or provide your own PSR-16 cache implementation (e.g. Redis, Memcached):

PSR-3 Logging

Pass a PSR-3 logger for debug output:

Key Generation

EC Key Pair (for DPoP or client assertion)

RSA Key Pair (for client assertion)

Extending for Specific Providers

This package is designed to be extended for provider-specific requirements:

Some authorization servers require the client assertion aud claim to be the issuer URL instead of the token endpoint (the default per RFC 7523 §3). Override getClientAssertionAudience():

Authorization Details (RFC 9396) and Profile Hooks

By default, authorization_details follows RFC 9396 parameter transport:

• Authorization request / PAR request: sent as JSON string parameter
• Token request: sent as JSON string parameter
• No default embedding into client_assertion claims

If a provider profile requires embedding authorization_details in client_assertion, override these hooks:

Supported RFCs

License

MIT License. See LICENSE for details.