Package Oidc

type OpenIDConnectClientFactory¶

Assembles an OpenIDConnectClient and every collaborator it is composed of, from a shared HTTP fetcher, clock, and logger. A caller wiring up one client per integration never reaches for new on the client or its internal collaborators (state store, provider metadata resolver, ID token verifier, claims validator, token endpoint client) itself - those are not part of this library's public API.

Deliberately not final, unlike most classes in this library - a consumer that wants a different wiring (an extra collaborator, a different assembly order) can subclass it rather than reimplementing make() from scratch.

make¶

Builds one OpenIDConnectClient. $stateCache is a PSR-16 cache used to persist authorization state, nonce, and the PKCE code verifier between the redirect and the callback - session storage is fine for a single-server app; a load-balanced deployment needs something shared, like Memcache or Redis, injected here instead. $cacheKeySuffix namespaces cache keys when one process builds more than one client (e.g. multi-tenant).

The logger defaults to a no-op - passing one is opt-in. It only ever receives detail behind a failure that already produces a deliberately generic exception.

type OpenIDConnectClientConfig¶

Everything needed to talk to one OpenID Connect provider for one call - a single immutable value instead of a chain of setter calls. The same shape covers both a statically-known integration (provider URL, issuer, and credentials fixed at boot) and a multi-tenant one (issuer/credentials resolved per request from a database row).

Parameters¶

Withers¶

Every property has a matching with*() method returning a new instance - the original is never mutated. withScopes(), withEndpointOverrides(), and withExtraAuthParams() merge with the existing value; withAudience(), withAllowedHosts(), and withAllowedAlgorithms() replace it, since those narrow a security boundary rather than add to a list of extras.

↑ back to index

Logging¶

This library's logging is deliberately, sometimes irritatingly, noisy at the debug level - most collaborators trace their own happy path in addition to every failure, by design, so a request can be followed step by step without anything having failed at all. That is a lot of log volume to hand a caller's own logger unfiltered. LogLevelFilterLogger exists specifically to mediate it - wrap your own logger in one to receive only the levels you actually want, rather than reconfiguring or replacing your logger just to cope with the noise.

This library assumes the logger passed in never throws. Nothing here catches an exception a logger raises - it propagates like any other exception and interrupts whichever call was in progress, including one already past the point of no return. In AuthorizationStateStore::consume() specifically, the cache entry backing an attempt is deleted before that method logs anything, so a throwing logger there aborts an otherwise-successful login and leaves the attempt unrecoverable - the same callback cannot be retried, since the entry it depended on is already gone. A logger that might throw (a remote log shipper timing out, a full disk) should be wrapped in one that catches its own exceptions before being passed to this library, if that failure mode matters to the caller.

The levels this library actually emits, for choosing what to pass into LogLevelFilterLogger's $levels:

notice, critical, and emergency are never used - there is nothing to opt into at those levels. Counts are call sites in src/, not runtime volume - one debug call on a hot path can still outnumber every error call combined in an actual log stream, which is exactly why LogLevelFilterLogger exists.

error is by far the largest category, so it is worth breaking down further. The table below groups its 68 call sites by the collaborator that raises them, alongside how many of each are security_relevant: true - see below for what that means:

The concentration is not an accident: IdTokenVerifier and ClaimsValidator are the two collaborators that sit closest to the token itself - decoding it, checking its signature, checking its claims - so nearly every shape an attacker could actually manipulate lands in one of those two classes. Every other collaborator's failures are further from the token's own content: transport, discovery, endpoint shape - which is why none of their error calls are currently marked security_relevant: true. That is a statement about where a curated, high-confidence indicator was found so far, not a claim that those classes can never see one - see "How this could evolve" below.

Every log call passes a context array alongside the message. Which keys show up varies by call site - each one logs whatever is actually diagnostic for its own failure, not a single fixed envelope - but related call sites agree on the same names and shapes for the same kind of failure, and a caller writing a log processor or a PSR-3 formatter that pulls specific fields out of context can rely on these names wherever they appear. state is by far the most common of them, showing up on nearly every failure that happens within an authorization flow - it is the closest thing to a transaction ID this library logs, letting every log line from one redirect/callback pair be correlated together across every class that touched that flow. Every exception this library throws carries the same state value too, via getState() - see Exceptions - so a caller catching one directly gets the same correlation id without having to opt into a logger at all.

Every error-level call also carries a security_relevant boolean, orthogonal to the level itself - it does not change what error, warning, or alert mean, only whether this particular failure is one this library can call a likely attack indicator with real confidence. It is true on a small, deliberately narrow set of call sites where the failure is essentially unexplainable except as tampering or forgery: an ID token declaring the "none" algorithm, a signature that fails verification, an at_hash that does not match the access token, a JWKS key type that does not match the token's algorithm, and a nonce that does not match the one this client generated. Every other error call - the other 63, as of this writing - carries security_relevant: false. That does not mean "confirmed benign" - a misconfigured provider, a network blip, and a genuine attack that happens not to fit one of the five curated shapes above all log false identically. It means only "not in this small curated set," not "safe to ignore." A caller wanting a lightweight tamper/attack signal can filter on this key without having to enumerate message strings or guess at severity; a caller wanting every failure still gets every failure, since the key never suppresses anything, it only adds a flag alongside.

Why a flat boolean, not a graded scale. An earlier draft of this feature considered a confidence gradient - a string enum, or an integer scale from "not an issue" through "ambiguous" to "security issue" - to capture the calls that sit between the five curated true sites and the rest (an audience mismatch, say, is not nothing, but is far more often a client misconfiguration than an attack). That was deliberately rejected: grading every one of the 63 false calls onto a scale would mean assigning each one a confidence level with no real usage data to justify a specific cut point, which just relocates the same judgment call into more categories without resolving it. A flat boolean, applied only where the evidence is genuinely unambiguous, says exactly as much as this library can currently stand behind, and no more.

How this could evolve. The true set is deliberately small today because it is curated by inspection, not by data - five call sites a maintainer could argue for individually, not five call sites production log volume had already picked out. The shape most likely to justify a real change here is usage data itself: if a caller aggregating this key across many deployments found that a specific false call site (the audience-mismatch or issuer-mismatch shapes in ClaimsValidator are the most plausible candidates, given how directly they touch token content) correlated with confirmed attacks far more often than the rest of the false population, that would be a concrete argument for moving it to true - or, symmetrically, for moving one of today's five back to false if it turned out to fire routinely for a benign reason nobody had anticipated (clock skew producing spurious signature failures at a provider that rotates keys unusually fast, say). A category dimension - not a confidence grade, but a label like "replay", "forgery", or "algorithm-confusion" on the five (and any future) true sites - is a more likely next step than a graded scale, since it adds information without asking this library to rank attacks it has no real basis for ranking. Any such change belongs on top of the flat boolean, which callers already filter on, rather than replacing it - a caller that only ever checked security_relevant === true should keep working exactly as before.

The three classes that fetch and validate an HTTP response - TokenEndpointClient, ProviderMetadataResolver, and IdTokenVerifier::fetchJwks() - log the same shape for every failure along that path: a URL identifier, http_status, content_type, and state, checking status before content type before JSON validity. http_status/content_type are logged as null rather than omitted when the failure happened before a response was ever received. A log query keyed on these fields reads the same shape regardless of which of the three fetches actually failed.

↑ back to index

type LogLevelFilterLogger¶

A PSR-3 decorator that forwards a log call to the wrapped logger only when its level is in an explicit allow-list, dropping every other level outright. A conventional "minimum severity" filter cannot express this on its own: set at debug, it lets everything through, since debug is already PSR-3's lowest severity - there is no threshold that means "debug only." Wrap your own logger in one of these to route, say, only this library's debug-level tracing somewhere separate (a different file, a different verbosity, temporarily on during troubleshooting) without also receiving, or reconfiguring, everything else your logger already handles.

$levels and $allow together express four distinct patterns, not just one allow-list:

The default, opt-in posture - "none, except" - is the same reason this class exists at all (see Logging): the default stance toward this library's noise is to filter all of it, not to let everything through until told otherwise. Pass an empty array with the default $allow and every log call is dropped, including a level a caller might assume always gets through, such as error - nothing passes unless its exact level is named.

$levels is a discrete set, not a range, in either the allow-list or the deny-list case - any combination is valid, including combinations no linear severity ordering could express together (debug and critical alone, with everything between them excluded). This class never validates a level against PSR-3's own eight constants (Psr\Log\LogLevel) - it is a plain string comparison, so $levels can equally well hold PSR-3's own levels, a caller's own custom level, or a mix of both. Pass it wherever this library expects a Psr\Log\LoggerInterface, e.g. OpenIDConnectClientFactory:

$logger = new LogLevelFilterLogger($yourAppLogger, [ LogLevel::DEBUG ]);

$factory = new OpenIDConnectClientFactory(logger: $logger);

"Every level, without having to name any of them" - the one case not reachable just by listing levels, custom or not, since it does not require knowing in advance which levels might ever be logged - is technically reachable directly as an empty deny-list (new LogLevelFilterLogger($logger, [], allow: false)), but that is not obviously what it means at a glance. Use the all() named constructor instead:

$logger = LogLevelFilterLogger::all($yourAppLogger);

The default, $allow: true, fails closed - a level nobody named gets dropped, including one this library or a wrapped logger adds later. $allow: false fails open - a level nobody named gets forwarded instead. That is a deliberate trade for the specific case it exists for (skip this library's debug tracing, forward every other level unconditionally), not a reason to prefer it generally over naming an allow-list directly. It is also why $levels is not called $allowedLevels or $excludedLevels: it holds an allow-list when $allow is true and a deny-list when it is false, and a name tied to one mode would be wrong in the other.

↑ back to index

enum PkceMode¶

How strictly RFC 7636 PKCE is enforced on the authorization code flow.

Disabled

Never generates a verifier - no code_challenge is sent, and none is sent back at token exchange.

Optional

Sends a code_challenge on every redirect. If the verifier is missing by completion (evicted from cache, TTL expired, or mismatched configs), proceeds without one and lets the token endpoint decide.

Required

Same as Optional, but a missing verifier at completion fails closed with AuthenticationFailedException before the token endpoint is ever contacted.

↑ back to index

enum ClientAuthMethod¶

Which OpenID Connect Core 1.0 §9 Client Authentication method the library uses for a confidential client. Has no effect on a public client - there is no secret to authenticate with under either method, so that case always identifies via a bare client_id in the request body.

Basic

HTTP Basic (RFC 6749 §2.3.1) - the spec default when no method is registered.

Post

Client credentials in the request body instead of the Authorization header.

client_secret_jwt and private_key_jwt are not implemented yet - both need a signed JWT assertion.

↑ back to index

interface AuthorizationFlowClientInterface¶

Interactive login: the authorization code flow (Clever, Google, Azure AD) and the implicit flow (e.g. LTI 1.3). Building a redirect never emits a response itself - it returns the URL and persists state/nonce as a side effect; the caller decides how to redirect.

buildAuthorizationCodeRedirect¶

Starts an authorization code flow attempt and returns the URL to send the user-agent to.

• throws AuthorizationStateException
• throws ProviderDiscoveryException

completeAuthorizationCodeFlow¶

Exchanges the callback's authorization code for tokens, verifies the returned ID token's signature and claims, and returns the result.

• throws AuthenticationFailedException
• throws ProviderDiscoveryException

buildImplicitFlowRedirect¶

Same as buildAuthorizationCodeRedirect(), but for the implicit flow (response_type=id_token).

• throws AuthorizationStateException
• throws ProviderDiscoveryException

completeImplicitFlow¶

Verifies the ID token returned directly on the callback fragment/params. Requires at_hash when an access token accompanies it (OpenID Connect Core 1.0 §3.2.2.10).

• throws AuthenticationFailedException
• throws ProviderDiscoveryException

↑ back to index

interface UserInfoClientInterface¶

Extends AuthorizationFlowClientInterface rather than standing alone, since nothing fetches UserInfo without having done the authorization flow first. An integration that never fetches UserInfo (e.g. LTI) can type-hint the narrower interface instead.

fetchUserInfo¶

$expectedSubject must be the sub claim from the authenticated ID token (AuthenticationResult::$claims->get('sub')) - OpenID Connect Core 1.0 §5.3.2 requires the UserInfo response's sub to be verified against it, to guard against token substitution. When the response is a signed JWT, its iss and aud are also validated; those two checks do not apply to a plain JSON response.

• throws ProviderDiscoveryException
• throws UserInfoRequestException

↑ back to index

interface TokenGrantClientInterface¶

Non-interactive token acquisition via the client credentials grant - e.g. a service-to-service integration that needs its own access token without a user in the loop.

requestClientCredentialsToken¶

$extraParams passes provider-specific extensions straight through on the request body - not for anything this library already models explicitly. A string value is sent as-is (a single audience, or a provider's space-separated convention); a list value is sent as that key repeated bare (resource=a&resource=b, the RFC 8707 convention for resource).

• throws ProviderDiscoveryException
• throws TokenRequestException

↑ back to index

interface RefreshTokenClientInterface¶

Stands alone rather than extending AuthorizationFlowClientInterface: redeeming a refresh token does not require having just completed an interactive flow in the same process - a background job holding a refresh token loaded from a database has no state/nonce, nothing this method needs beyond the refresh token and the original ID token's claims to validate a new one against (OpenID Connect Core 1.0 §12.2).

refresh¶

$originalIdToken and $originalClaims are the ID token and claims from the authentication this refresh token came from (AuthenticationResult::$idToken / ::$claims). The refresh response might not contain a new id_token at all - when it does not, the returned AuthenticationResult carries the original ID token and claims forward unchanged, alongside the new access/refresh tokens. When it does, the new ID token's iss, sub, and aud are validated against the original's, auth_time (if present) must still reflect the original authentication, and nonce (if present) must match the original's.

• throws AuthenticationFailedException
• throws ProviderDiscoveryException
• throws TokenRequestException

↑ back to index

type OpenIDConnectClient¶

The object returned by OpenIDConnectClientFactory::make(). Implements every capability interface above - TokenGrantClientInterface, UserInfoClientInterface (which itself extends AuthorizationFlowClientInterface), and RefreshTokenClientInterface. Construct it only via the factory or from test code - never with new directly in application code.

A consuming application typically type-hints the narrowest interface it actually needs (for example, AuthorizationFlowClientInterface for an integration that never fetches UserInfo) rather than this concrete class, so a test double such as MockOpenIDConnectClient can stand in for it.

One method below exists only here, not on any interface - keep this concrete type in scope where you specifically need it; everything else should still type-hint narrower.

buildImplicitFlowRedirectWithAccessToken¶

Same as buildImplicitFlowRedirect(), but requests response_type=id_token token instead of the bare id_token - an access token issued directly from the authorization endpoint, no token endpoint round trip. Deliberately not on AuthorizationFlowClientInterface: RFC 9700 recommends against Implicit entirely, and the one case this variant used to serve - a browser-only app needing an access token with no backend to exchange a code - is better served today by Authorization Code plus PKCE, which never puts a token in a redirect URL at all. Reach for this only for the rare case that still needs it (e.g. RP conformance certification). completeImplicitFlow() needs no equivalent variant - it already validates at_hash and returns the access token whenever the provider includes one, regardless of which method built the original redirect.

• throws AuthorizationStateException
• throws ProviderDiscoveryException

↑ back to index

type AuthorizationRedirect¶

A URL to send the user-agent to next - a login redirect. The caller decides how to issue the redirect; this library never emits a response itself.

↑ back to index

type IncomingAuthorizationResponse¶

What a provider sent back to the redirect URL - an authorization code (code flow), an ID token (implicit flow), or an error - parsed from a plain params array instead of reading superglobals directly.

errorSummary() returns a single ready-to-log string combining error and error_description when present, or null when there is no error. error/error_description are truncated to 255 characters - the callback endpoint is public and unauthenticated, so these reach this class straight from the query string with no prior validation.

$response = new IncomingAuthorizationResponse($_GET);

if ($response->hasError()) {
    log_error($response->errorSummary());
}

↑ back to index

type AuthenticationResult¶

The outcome of completing an authorization code or implicit flow, or of refreshing one.

↑ back to index

type TokenResult¶

A token endpoint response - shared by the authorization code exchange and the client credentials grant.

Constructed internally from the decoded JSON token endpoint response; a malformed response (missing or wrongly-typed access_token) throws TokenRequestException. Other malformed fields are logged and ignored rather than failing the whole response.

↑ back to index

type Claims¶

A bag of decoded claims - from a verified ID token or a UserInfo response. One shape for both.

$sub   = $result->claims->get('sub');
$email = $result->claims->get('email', default: null);

↑ back to index

interface HttpFetcherInterface¶

The seam every collaborator talks through instead of calling curl directly. Implement this to plug in an existing HTTP client instead of CurlHttpFetcher.

TLS verification is not a per-request concern: an implementation talking to real sockets is expected to always verify certificates and hostnames, full stop. $headers maps header name to value - no raw "Name: value" formatting.

• throws HttpTransportException when the request cannot be completed at all (connection failure, timeout).

↑ back to index

type CurlHttpFetcher¶

The library's own HttpFetcherInterface implementation, and the default used by OpenIDConnectClientFactory. Reuses a single curl handle across calls, never follows redirects (several calls here carry an Authorization header), and bounds the response body by $maxResponseBytes regardless of connection speed.

↑ back to index

type FetchResponse¶

↑ back to index

type CurrentClock¶

The default clock for OpenIDConnectClientFactory - wraps the system clock via PSR-20's ClockInterface, so tests can inject a fixed one instead.

↑ back to index

type MockOpenIDConnectClient¶

A hand-written fake for a consuming application's own controller tests - no network, no cache, no real cryptography. Every canned result is a public property so a test can override just the ones it cares about before exercising the controller. Defaults to a successful outcome everywhere; set the relevant *Exception property to simulate a failure instead.

$client = new MockOpenIDConnectClient(
    authenticationException: new AuthenticationFailedException('expired state'),
);

// Exercise a controller that type-hints AuthorizationFlowClientInterface
// and expect it to handle the failure path.

↑ back to index

namespace Oidc\Exceptions¶

Every exception this library throws extends OpenIDConnectException (itself a plain \RuntimeException), so a caller that only wants a single catch clause for "something in this library failed" always has one available.

OpenIDConnectException also carries getState() - the authorization flow's state value the failure happened within, when one was available. This is the same correlation id described in the Logging section above, now reachable without opting into a logger at all: catch the exception and call getState() directly. It's null whenever there was no flow to correlate with yet (building a redirect before one exists) or none in scope at all (UserInfoRequestException specifically - fetchUserInfo() isn't scoped to a stored flow the way the authorization/token/JWKS paths are).

getState¶

getIdToken¶

Only on AuthenticationFailedException. The raw ID token this failure happened against, when one was actually obtained - null for a failure with no token yet in hand (a state/nonce/PKCE mismatch, a missing authorization code, a provider-returned error, or a token response missing id_token entirely - that last case IS the failure, so there is nothing to attach). Signature/claims validation is fail-fast, so the log for whichever check trips first never shows the others; decoding this (it need not be signature-valid to decode) is the only way to see every claim the token carried at once.

getHttpStatus¶

On TokenRequestException and UserInfoRequestException. The response's HTTP status, when a response was actually received - null for a transport failure that never reached the server.

getRawBody¶

On TokenRequestException and UserInfoRequestException. The response's raw body, when a response was actually received - null under the same condition as getHttpStatus() above, and always the original, undecoded response text even when that body turns out not to be valid JSON. For a signed (application/jwt) UserInfo response that failed further verification or claims validation, this is the JWT itself, not a JSON body.

↑ back to index