Laravel Connect Identity Laravel Package

Getting Started

• Install with composer require oneofftech/laravel-connect-identity and confirm you land on ^0.6. This release's headline change is Laravel 13 compatibility, so pair it with a Laravel 13 app (and the PHP version Laravel 13 requires — check the composer.json php constraint before upgrading an older runtime).
• Publish the package config first: php artisan vendor:publish --tag=connect-identity-config (check php artisan vendor:publish output for the exact tag). Everything you need to get a login working — client credentials, issuer/discovery URL, scopes, redirect route — lives there.
• Read in this order: the README's quickstart, the published config file (it is the most accurate documentation of available keys), then the package's service provider to see what it registers (guard driver, routes, bindings). The service provider tells you what is configurable vs. hard-coded faster than any doc.
• First use case to validate the integration end-to-end: an external identity provider login against a single provider. Hit the package's redirect route, authenticate at the IdP, land on the callback, and confirm a local users record is created or matched. If that loop works, everything else is configuration.
• Set the basics in .env (APP_URL, session driver, and the client id/secret/issuer keys the config expects) before your first attempt — most first-run failures are misconfiguration, not bugs.

Implementation Patterns

• Guard-based auth is the primary integration point. Register the package's guard driver in config/auth.php, add a connect (or similarly named) guard, and use Auth::guard('connect') / auth:connect middleware on the routes you want protected. This keeps the package from colliding with your existing session guard.
• Route wiring: you own the entry point. Expose a route that redirects to the provider and a callback route that the IdP returns to. The callback must sit in the web middleware group — the OAuth state parameter is stored in the session, so api-only middleware will break the round trip.
• User provisioning: the package authenticates a remote identity; you decide how it maps to App\Models\User. Prefer keying on the subject claim (sub) stored in a dedicated column over matching by email. Email matching is convenient for existing user tables but breaks the moment someone's email changes at the IdP or two identities share an address.
• Custom resolution/rescue: listen to the package's authentication event or bind your own user resolver in a service provider to handle first-login creation, attribute sync, and "account disabled" cases. Keep this logic in one listener rather than scattering it across controllers.
• Multi-provider: define one guard per identity provider when you need more than one, each with its own config block. This is cleaner than trying to make a single guard provider-aware at runtime.
• Testing: fake the HTTP layer with Http::fake() for the token and userinfo/JWKS endpoints and assert the redirect → callback → authenticated state. For everything downstream of login, actingAs($user, 'connect') avoids hitting the IdP entirely. Keep one integration test that exercises the real callback path with a faked token response.
• API/SPA scenarios: if you use the package to obtain tokens for a frontend, keep token storage server-side and use Laravel's session or a sanctum-style flow for the client. Don't ship provider tokens to the browser.

Gotchas and Tips

• 0.x semver. You are on a pre-1.0 package: minor bumps can break. Pin to ^0.6 and read the changelog before each minor update. The v0.6.0 diff is small (Laravel 13 support only), but the same won't be true of every release.
• Upgrading to 0.6.0: after composer update, diff your published config against the package's stub (vendor/oneofftech/laravel-connect-identity/config/...). Re-publishing with --force will overwrite your environment-specific values. Also re-run your test suite against Laravel 13 — framework-level deprecations, not this package, are the likely source of breakage.
• Redirect URI mismatch is the single most common failure. The value sent in the authorization request must character-for-character match what is registered at the IdP, including scheme, trailing slash, and port. Behind a proxy, set TrustProxies correctly or the generated URL will be http:// while the IdP expects https://.
• State/session errors (invalid_state, missing session) usually mean: session driver misconfigured across multiple app servers, cookie domain mismatch, or the callback route outside the web group. Use a shared session store (Redis/DB) in any multi-node setup.
• Cookies and SameSite: the callback is a top-level cross-site redirect, so SameSite=Lax is what you want on the session cookie; Strict will drop the session and break state validation.
• Clock skew and key rotation: JWT validation failures after a while often mean cached JWKS keys went stale after the IdP rotated them. Check the cache TTL in config and make sure you can flush it. If validation fails only intermittently, look for a leeway/skew setting.
• Logout is local only unless the IdP supports RP-initiated logout. Logging out of your app does not end the IdP session — the next login may silently succeed. Document this for your users; it surprises people in shared-device scenarios.
• Debugging: enable debug logging for the token exchange, but never log access/ID tokens or client secrets. When something fails, capture the error/error_description from the IdP's redirect query string — the package's exception message is usually a paraphrase of it.
• Extension points to reach for first: the published config, the guard/user resolver binding, and the authentication event listener. If you find yourself subclassing internals, check whether a config key or event already covers it — pre-1.0 internals are not a stable API.