Laravel Config Sso Laravel Package

Getting Started

This is cleaniquecoders/laravel-config-sso — a config-driven SSO package with a Livewire/Flux admin screen at /admin/settings/sso. The 1.0.2 release fixed icons and workbench/tooling. The 1.1.0 release is a minor with no breaking API changes called out, but it includes an important sign-in security behavior change: SSO sign-in can now claim an existing unverified local account matched by email.

Minimal path from zero to a working login:

1. composer require cleaniquecoders/laravel-config-sso and publish the package config (php artisan vendor:publish — pick the SSO provider tag). Run migrations if the package persists settings/identities.
2. Read docs/ in this order: architecture (how the flow and settings store fit together), configuration (every key and its env var), api/usage (routes, guards, helpers). Then read the 1.1.0 security note and event docs. The README is a thin overview with screenshots — the docs tree is the real reference.
3. Confirm the admin UI prerequisite: the settings screen is Livewire + Flux. Flux is a commercial Livewire package and ships Heroicons only. If Flux isn't installed/licensed you'll hit Flux component [icon.*] does not exist the moment you open the settings page.
4. First use case: wire one IdP (Okta / Entra ID / Google Workspace), point the IdP at your ACS/callback URL, and protect a single route group with the SSO middleware. Verify with a test user before touching your main web guard.
5. Test the account-claim path explicitly: create an unverified local user whose email matches a test IdP user, sign in via SSO, and confirm the 1.1.0 behavior (email marked verified, password and remember token rotated).
6. For local work, use the bundled workbench: composer serve boots the demo app. Use composer build for compiled Tailwind + Flux assets rather than the CDN.

Implementation Patterns

Treat the published config as the environment contract. Put IdP URLs, entity/client IDs, and certificates behind env vars so local, staging, and production differ only by .env. Keep one committed config file with safe defaults and no secrets.

Decide early whether the admin UI or the config file is the source of truth. If the Livewire screen writes to the database, document the precedence (typically: DB override → config default) and make sure a fresh deploy without DB rows still boots from config. Ambiguity here is the most common source of “works on my machine” SSO bugs.

Protect routes by group, not per-route. Apply the package middleware to a route group and keep a separate local-auth guard for break-glass admin access. Never let an SSO outage lock every admin out — keep at least one password/CLI-driven path in.

Map claims deliberately. Resolve the IdP subject to a local user by a stable identifier (subject/object ID) rather than email, and treat email as a linking heuristic only. Handle the first-login case (create vs. reject) explicitly, and log the claim payload on mismatch — name/email casing and multi-valued attributes bite regularly.

Handle the 1.1.0 unverified-account claim deliberately. When SSO sign-in matches an existing local account by email and that account is not yet verified, the package now claims it: it rotates the password and remember token, marks the email verified, and then signs the user in. This prevents pre-account takeover, but it changes onboarding flows. If your app creates unverified local users as invitations or placeholders, audit that path: the first matching SSO login will take the account over.

Listen to UnverifiedAccountClaimed. Register a listener for CleaniqueCoders\ConfigSso\Events\UnverifiedAccountClaimed to revoke app-specific credentials that should not survive an account claim: 2FA enrollment, API tokens, passkeys, remembered devices, or other downstream sessions. Keep the listener idempotent and decide whether it should run synchronously or on a queue.

Mirror the package's own test strategy in your app. Feature tests alone are insufficient for Flux views: in the test harness Flux renders icons as no-ops, so a bad icon name passes CI and 500s in production. Add a small static test (like the upstream FluxIconTest) that greps your admin views for flux:icon.* / <x-icon> names and asserts each is a real Heroicon. Also add a test for the unverified-account claim path: assert email_verified_at is set, password and remember token are rotated, and UnverifiedAccountClaimed is dispatched.

Develop against the workbench. Run composer serve for a disposable app, and use composer build for the compiled Tailwind + Flux stylesheet rather than the CDN — the CDN works but hides Tailwind purge/config problems that appear in a real build. Same applies to your app's own admin views.

Extension points to reach for before forking: the config file, publishable views for the settings screen, custom user resolution/claim mapping, event listeners for UnverifiedAccountClaimed, and your own guard + middleware aliases.

Gotchas and Tips

• Email-matched unverified accounts are now auto-claimed. In 1.1.0, an SSO sign-in matching an unverified local account by email marks it verified and rotates the password and remember token before sign-in. This is intended to prevent pre-account takeover, but audit any invite/placeholder-user flows that rely on unverified local accounts.
• The claim event is not a general login event. UnverifiedAccountClaimed fires only on this claim path. Do not put ordinary SSO-login 2FA or token-revocation logic there unless you also handle normal sign-ins.
• forceFill is used for SSO-created users. The release fixes email_verified_at being blocked by mass-assignment. Do not assume $fillable protects verification state elsewhere; if you have custom user creation, set verification explicitly.
• Password rotation breaks existing password login. After a claim, the previous local password no longer works. Make sure your break-glass admin path does not depend on the same email being claimed.
• Remember-token rotation invalidates remembered sessions. Existing “remember me” cookies for the claimed account should be treated as revoked.
• Lucide icon names are fatal. Flux resolves Heroicons only. The 1.0.2 fixes map ellipsis → ellipsis-horizontal, trash-2 → trash, eye-off → eye-slash. Any custom view you publish inherits this constraint — audit your own icon usage, not just the package's.
• The icon failure is lazy. Flux component [icon.x] does not exist is thrown at render time, in the browser, not at boot. Nothing in php artisan about or route:list will warn you.
• HTTP tests will not catch icon errors. Flux deliberately no-ops icons in the test harness. Don't “fix” this by asserting on rendered SVG; add the static guard test instead.
• Debugging order for a failed login: your app log → the SSO settings screen values actually in effect → IdP-side event log. The usual culprits are a redirect/ACS URL mismatch (scheme, trailing slash, port), clock skew invalidating an assertion, and a certificate rotated on the IdP without updating config.
• Cache after config changes. php artisan config:cache in deploys will freeze SSO settings; if the admin UI persists to DB, remember that a config-cached deploy ignores .env edits until re-cached.
• Stale Testbench cache. If every package route 500s in the workbench, it's provider discovery, not your code: re-run discovery / composer serve. Pin >=1.0.2 if you rely on the demo.
• Local dev without an IdP is the friction point — prefer the workbench or a stub/fake driver over disabling middleware, and never ship a “SSO disabled” branch that can be flipped by env in production without an explicit guard.