Download the PHP package jeffersongoncalves/laravel-oidc without Composer

Laravel OIDC

Laravel OIDC adds first-class OpenID Connect support to Laravel by registering a custom Laravel Socialite driver named oidc. Unlike vanilla Socialite — which covers OAuth 2.0 but stops at the userinfo step — this package implements the OIDC pieces Socialite leaves out: discovery (/.well-known/openid-configuration), JWKS-based id_token validation, nonce-based replay protection, and PKCE.

It is designed for multi-tenant SaaS: configuration is supplied at runtime, so each tenant can connect its own Azure AD, Okta, Auth0, Google Workspace, Keycloak, or any other spec-compliant OpenID Provider.

Compatibility

Why?

Laravel Socialite ships drivers for fixed providers (GitHub, Google, etc.) and a small set of OAuth 2.0 helpers. It does not:

• Read the IdP's .well-known/openid-configuration discovery document.
• Validate the id_token JWT against the IdP's JWKS.
• Send and verify a nonce to mitigate replay attacks.
• Make per-request configuration easy in multi-tenant scenarios.

This package adds those pieces while staying inside the Socialite mental model: you still call Socialite::driver('oidc')->redirect() and ->user().

Installation

Optionally publish the config file:

Configuration

The package works out of the box. For single-tenant apps, set the default IdP in .env:

For multi-tenant apps, leave the default block empty and supply an OidcConfig at runtime (see below).

Usage

Single-tenant (config from .env)

Multi-tenant (runtime config)

On callback:

HasOidcConfig trait for tenant models

If you store IdP configuration on a model (a typical multi-tenant pattern), drop in the trait. It expects columns issuer_url, client_id, client_secret (cast to encrypted), redirect_uri, and an optional scopes JSON column.

Discovery without Socialite

Supported Identity Providers

Any IdP that publishes a .well-known/openid-configuration discovery document and signs id_tokens with one of the allowed algorithms (RS256, RS384, RS512, ES256, ES384) will work. Examples:

Security

• id_token validation. Every id_token is decoded against the IdP's JWKS using firebase/php-jwt. The iss, aud, exp, and iat claims are checked, with a configurable clock-skew window.
• Algorithm allow-list. Only the algorithms in oidc.jwt.allowed_algorithms are accepted. Symmetric algorithms (HS256 & friends) are intentionally absent — accepting them with a JWKS would enable trivial key-confusion attacks.
• Replay protection. A random nonce is generated, stored in the session, and verified against the nonce claim in the returned id_token.
• PKCE. Enabled by default with S256. Disable per request with new OidcConfig(..., usePkce: false).
• Caching. The discovery document is cached for 1 hour and the JWKS for 6 hours by default; both TTLs are configurable. Use Oidc::clearCache($issuer) to invalidate after a key rotation.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Pull requests are welcome. Please make sure tests, PHPStan and Pint all pass before opening a PR:

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.