Download the PHP package itk-dev/openid-connect-bundle without Composer

OpenId Connect Bundle

Symfony bundle for authorization via OpenID Connect.

[!NOTE]

Symfony Native OIDC Support

Since this bundle was created Symfony has added support for OpenID Connect as documented in "Using OpenID Connect (OIDC)".

Symfony's native OIDC support has improved significantly in recent releases:

• OIDC discovery was added in Symfony 7.3 (May 2025), removing the need for manual keyset configuration. Keys are fetched and cached automatically from the provider's .well-known/openid-configuration endpoint.
• OAuth2 Token Introspection (RFC 7662) support was added in Symfony 7.3, useful when access tokens are opaque (not JWTs).
• JWE (encrypted token) support was added in Symfony 7.3 for OIDC token handlers.

However, Symfony's native OIDC support is designed for stateless bearer token validation (the access_token authenticator) only. It validates tokens that are already present on the request (e.g. in an Authorization: Bearer header).

It does not implement the authorization code flow — the browser-based login where the application redirects to the IdP, handles the callback with an authorization code, exchanges it for tokens, and establishes a session. This is tracked upstream in symfony/symfony#50896.

This means the following features of this bundle have no native Symfony equivalent:

Feature	This bundle	Symfony native
Authorization code flow	✅	❌
Session-based browser login	✅	❌
Multiple named OIDC providers	✅	❌ ¹
CLI login tokens	✅	❌
OIDC discovery	✅	✅
Bearer token validation (API)	❌	✅
OAuth2 token introspection	❌	✅

¹ Symfony's access_token handler accepts multiple issuers for token validation, but this is not the same as this bundle's named provider model with distinct client credentials, redirect URIs, and selectable login routes per provider.

If your application needs browser-based OIDC login, this bundle is still required.

Installation

To install run

Usage

Before being able to use the bundle, you must have your own User entity and database setup.

Once you have this, you need to

• Configure variables for OpenId Connect
• Create an Authenticator class that extends the bundle authenticator, OpenIdLoginAuthenticator
• Configure LoginTokenAuthenticator in order to use CLI login.

Variable configuration

In /config/packages/ you need the following itkdev_openid_connect.yaml file for configuring OpenId Connect variables

With the following .env environment variables

Set the actual values your env.local file to ensure they are not committed to Git.

Client secret expiry

An expired client secret breaks every login: the token exchange starts failing with invalid_client and there is nothing in the flow that says why. The expiry date is known when the secret is created, so telling the bundle about it turns an outage into a calendar item.

Any date strtotime() understands is accepted, and the value is normally supplied from an environment variable as above. Date-only values are anchored to midnight UTC so the day count does not drift with the time of day the check runs.

A value that cannot be parsed — a typo, or an environment variable that is set but blank — reports the provider as unknown and logs an error saying it is not being monitored. It is not a fatal error, because a mistyped date should not take an application down; but it is not silent either, because the effect is that nothing is watching that secret.

Each provider is then in one of four states:

unknown is deliberately distinct from ok: an installation that has not set a date is not fine, it is unmonitored.

What the bundle does with each state, when a login is attempted:

Nothing here blocks a login. The status depends on a manually maintained date, which can fall out of step with the secret it describes: rotate a secret without updating client_secret_expires_at and the date reads expired while the secret works perfectly. The date is therefore an indicator, not authority — the identity provider is what decides whether a secret still works. These records exist so that when it does stop working, the reason is already in the log.

For a genuinely expired secret that means the login still fails, at the callback, with invalid_client — but the critical record here and the failure record from the callback together name the cause without anyone having to reproduce it.

client_secret_expires_at is required, because the bundle cannot warn about an expiry it does not know about. Quote it: YAML reads an unquoted 2027-01-31 as a number, and a value that is not a string is rejected while the container compiles.

A provider still reaches unknown at runtime when the value resolves to something unusable — an environment variable that is set but blank, or a date DateTimeImmutable cannot parse — and that is reported at error, because an unmonitored secret is no better than not having this feature.

Monitoring expiry

The records above only appear when somebody attempts a login, which is no help on a quiet Sunday before a Monday-morning expiry. For scheduled monitoring, inject ClientSecretExpiryChecker — it is a public service — and surface it through whatever health endpoint the application already has:

getAllStatuses() returns a ClientSecretExpiry per provider, keyed by provider key, each with isExpired(), isExpiringSoon(), status and toArray().

The bundle ships no health endpoint of its own, and that is deliberate:

• Monitoring should have one endpoint to poll. A second one, differently shaped and living under this bundle's route prefix, is the one that gets forgotten.
• The application owns how such an endpoint is authenticated. That reasoning can be subtle — an application whose user provider is database-backed may need to authenticate its health route at the edge rather than in Symfony, so the endpoint can still answer during a database outage. A route shipped by this bundle would sit outside that decision.
• The application owns what may be disclosed. Provider keys and expiry dates are information about a deployment, and whether they belong in a public readiness response or an authenticated detail response is not this bundle's call.

Exposing the data rather than a verdict also avoids a lossy mapping. The checker distinguishes four states, and unknown — a provider with no date configured — is not the same as healthy. Collapsing that into another library's pass/fail result would throw the distinction away, whereas an application mapping it itself can decide whether "nobody is tracking this secret" counts as degraded.

This composes with whatever health system is in use:

• a bespoke aggregator, as in the example above;
• macpaw/symfony-health-check-bundle, where checks implement its own CheckInterface and are listed by service id in configuration;
• liip/monitor-bundle, which auto-discovers any class implementing Laminas\Diagnostics\Check\CheckInterface.

If an adapter is ever shipped from here, that last one is the target: the laminas/laminas-diagnostics contract depends on nothing but PHP, and its Success/Warning/Failure/Skip results map onto this bundle's four states almost exactly — including Skip for a provider with no date configured. It is not shipped today because no consuming application uses it yet, and a dependency added for hypothetical reach is a dependency to carry for nothing.

Logging

The bundle logs every login failure: an invalid state, an empty nonce, a failed token exchange, an unknown or unreachable provider, and the CLI login token paths. This is how a problem like an expired client_secret becomes visible — the IdP's own message is logged, with the causing exception attached to the record as context['exception'].

The bundle decides how severe each failure is; your application decides which levels it keeps. Severity is not configurable, because it is a property of the event rather than of a deployment:

The warning events are routine and client-driven — a stale bookmark, a replayed callback, a probe. The error events are the ones an operator needs to act on.

Default: nothing to configure

The bundle's services are tagged onto the openid_connect Monolog channel, so records flow to whatever handlers your application already has. Your existing monolog configuration therefore determines what is written, with no extra setup.

A dedicated channel with its own level

To give this bundle its own log file and threshold — for example to keep only error and above — add a handler scoped to the channel, and exclude that channel from your default handler so records are not written twice:

The level key on the handler is what gives you "only errors and above". Raising it filters out the warning events in the table above while keeping every error.

Using a different logger service

logging_options.logger takes any PSR-3 service id. Note that it replaces the channel logger rather than composing with it, so it is an escape hatch for sending these records somewhere else entirely — not the way to filter them:

Turning logging off

Point it at the NullLogger the bundle registers for the purpose:

Your authenticator must be an autoconfigured service to receive a configured logger, since it is applied through registerForAutoconfiguration(). That is the default for services in config/services.yaml. With autoconfiguration disabled the authenticator falls back to a NullLogger and logs nothing, while the rest of the bundle keeps logging.

A configured logger also takes precedence over a setLogger() call on the authenticator's own service definition. Disabling autoconfiguration is the way to wire a logger yourself.

Audit logging

Separately from the failure logging above, the bundle can write an authentication audit trail: who logged in, when, by which method, and which attempts were refused. This answers a different question from the error log — "who did what?" rather than "is something broken?" — which is why it is a separate channel rather than another level.

[!IMPORTANT] The audit trail records personal data (user identifiers, IP addresses). It is off by default, and enabling it makes retention, access control and the lawful basis for that processing your responsibility. Nothing is recorded, and no record is even assembled, while it is disabled.

Records are written at info on the openid_connect_audit channel, with one fixed context schema so the trail can be queried:

Events: authentication.login_succeeded, authentication.login_failed, authentication.cli_token_issued, authentication.cli_token_reissued, authentication.cli_token_denied.

Give it a handler that will not be filtered out by an operational threshold, and retain it on whatever schedule your policy requires:

Only logins that went through this bundle's authenticators are recorded. Symfony dispatches its login events for every authenticator in the application, so if a project also offers password or API-token login, those events reach this subscriber and are deliberately ignored: an OIDC bundle silently recording an application's password logins would extend the personal-data processing past what was opted into, and provider would be meaningless for them. Applications wanting a complete authentication trail should subscribe to the same events themselves.

Both method and authenticator are recorded because they answer different questions. method is stable and queryable; authenticator says which class actually ran, which matters because consumers subclass OpenIdLoginAuthenticator and an application may have several — one per provider, for instance.

Three details worth knowing:

• Failed OIDC logins carry no subject. This bundle raises its failures while building the passport, so at that point Symfony has no authenticated identity to report. The record still carries the provider, the IP and the reason.
• CLI login tokens are never recorded. The token is bearer-equivalent, so issuance is audited by subject only — the token and the login URL that embeds it stay out of the trail.

Pseudonymising identifiers

Setting identifier: hashed replaces the identifier with an HMAC-SHA256 keyed on the application secret. It is stable, so records for the same person still correlate, but it is not reversible from a list of known email addresses — which a plain digest would be.

[!NOTE] identifier cannot come from an environment variable. The key is chosen while the container compiles, so the mode has to be known then; an environment variable would leave it hashing with an empty key, which looks pseudonymised without being so. To vary it per environment, use Symfony's environment-specific configuration (when@prod:), which is resolved at compile time.

Configuring the HTTP client

Each provider accepts an optional http_client_options block that is forwarded to the underlying Guzzle HTTP client used by league/oauth2-client. The bundle applies a sensible default timeout of 30 seconds so a slow IdP cannot block worker processes indefinitely (Guzzle's own default is 0, i.e. wait forever). Override it per provider, or set it to 0 to opt back into Guzzle's behaviour.

The bundle accepts only timeout, proxy, and verify under http_client_options — these are the keys league/oauth2-client forwards to Guzzle (verify is consulted only when proxy is set). Any other key causes an InvalidConfigurationException at container compile time.

Why Guzzle and not Symfony HttpClient? league/oauth2-client, which the underlying itk-dev/openid-connect library extends, hard-types its HTTP client as GuzzleHttp\ClientInterface. Symfony HttpClient implements PSR-18 / HTTPlug, not Guzzle's interface, and no maintained adapter goes Symfony → Guzzle. Configure Guzzle via the options above; full transport replacement is not currently possible without a custom adapter we are not yet shipping.

In /config/routes/ you need a similar itkdev_openid_connect.yaml file for configuring the routing

It is not necessary to add a prefix to the bundle routes, but in case you want i.e. another /login route, it makes distinguishing between them easier.

When invoking the login controller action (route itkdev_openid_connect_login) the key of a provider must be set in the provider parameter, e.g.

Make sure to allow anonymous access to the login controller route, i.e. something along the lines of

CLI login

In order to use the CLI login feature the following environment variable must be set in order for Symfony to be able to generate URLs in commands:

See Symfony documentation: Generating URLs in Commands for more information.

You must also add the bundles CliLoginTokenAuthenticator to the security.yaml file:

Finally, configure the Symfony route to use for login links: cli_login_options: route. If yoy have multiple firewalls that are active for different url patterns you need to make sure you add LoginTokenAuthenticator to the firewall active for the route specified here.

Creating the Authenticator

The bundle can help you get the claims received from the authorizer – the only functions that need to be implemented are authenticate(), onAuthenticationSuccess() and start().

See below for a full authenticator example.

Make sure to add your authenticator to the security.yaml file - and if you have more than one to add an entry point.

Example authenticator functions

Here is an example using a User with a name and email property. First we extract data from the claims, then check if this user already exists and finally update/create it based on whether it existed or not.

Sign in from command line

Rather than signing in via OpenId Connect, you can get a sign in url from the command line by providing a username. Make sure to configure OIDC_CLI_REDIRECT_URL. Run

or

for details.

Be aware that a login token only can be used once before it is removed, and if you used email as your user provider property the email goes into the username argument.

Development Setup

A docker-compose.yml file with a PHP 8.3+ image is included in this project. A Taskfile is used to run common development tasks.

To set up the project:

This starts the Docker containers and installs Composer dependencies.

Running All CI Checks

To run all checks locally (coding standards, static analysis, tests):

Unit Testing

Test Matrix

Run the test suite across all supported PHP versions (8.3, 8.4, 8.5) with both lowest and stable dependencies, mirroring the CI matrix:

This runs PHPUnit with coverage for each combination and prints a summary of pass/fail results.

Mutation Testing

Line coverage shows which code the tests execute; mutation testing shows which code they actually verify. Infection applies small changes (mutants) to the source code — flipping a comparison, removing a method call — and runs the test suite against each one. If the tests still pass, the mutant "escaped": a potential bug the tests would not catch.

The minimum mutation score (minCoveredMsi) is defined in infection.json5 and enforced both locally and in CI — no command line flags needed. CI annotates escaped mutants inline on pull requests, and results for develop are published to the Stryker dashboard, which also feeds the mutation score badge above. Detailed reports are written to infection.log and infection.html on each run.

PHPStan Static Analysis

Coding Standards

Check all coding standards:

Fix PHP coding standards (php-cs-fixer):

Fix Markdown files:

Fix YAML files:

Available Tasks

Run task --list to see all available tasks.

CI

GitHub Actions are used to run the test suite, mutation tests and code style checks on all PRs.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE.md file for details