Authentication Bundle Laravel Package

Getting Started

Day-one reality check. This is a Symfony bundle (RetItaliaSpA/AuthenticationBundle, Symfony bundle naming and DI conventions), not a Laravel package. There is no service provider, no facade, no config/*.php to publish, and composer require retitalia/authentication-bundle will land classes that Laravel's container will never autowire. If you are the Laravel developer on this, the correct first move is not to install it — it's to read it as a reference implementation of Google OAuth2 and implement the flow with Socialite. Only install it if the target application is actually Symfony.

Where to look first (in this order):

1. composer.json — this is your compatibility truth source. Check the PHP constraint, the symfony/* constraints, and the OAuth2 client it depends on (league/oauth2-google, knpu/oauth2-client, or hand-rolled). If it pins an old Symfony major, stop here.
2. DependencyInjection/Configuration.php — the config tree. This tells you the entire supported configuration surface: client ID/secret, redirect route, scopes, user provider, role mapping.
3. Security/ — the authenticator(s) and user provider. This is where the actual OAuth2 dance, token handling, and user provisioning live.
4. Controller/ — the redirect and callback actions, plus the route names you'll need to reference in the firewall.
5. Resources/config/ — service wiring and route definitions; confirms whether routes are prefixable.
6. LICENSE — confirm you can fork it, because you will.

First use case — Laravel developer porting the flow. Build the Socialite equivalent and use the bundle as your spec:

Ship the spike as: route GET /auth/google/redirect → GET /auth/google/callback → find-or-create user → Auth::login() → redirect to intended('/dashboard').

If you are genuinely on Symfony: register the bundle in config/bundles.php, add the config block under config/packages/, point the firewall at the bundle's authenticator, and verify the routes don't collide with your existing prefix before writing anything else.

Implementation Patterns

Adapter-first, always. Wrap whatever you use — the bundle on Symfony, Socialite on Laravel — behind your own interface:

interface SsoProvider {
    public function redirectUrl(): string;
    public function handleCallback(Request $request): SsoIdentity;
}

SsoIdentity is a plain value object (id, email, emailVerified, name, avatar, hostedDomain). Every call site depends on this, never on Socialite or RetItalia\.... Given this package has zero stars, zero dependents, and no maintainer community, the adapter is the single cheapest insurance you can buy — it turns a future migration from N rewrites into N small changes.

Provisioning pattern (the one that actually matters day to day). Handle three cases explicitly in the callback, in this order:

1. Returning user — match on google_id, update name/avatar, log in. No new record.
2. First SSO login, existing account by email — only link if email_verified === true and the domain is in your allowlist. Otherwise refuse with a clear error; silent linking is an account-takeover path.
3. Brand-new user — create the record with google_id, email, no password, and a password_set_at = null flag so you can prompt for optional credential setup later.

Domain restriction pattern. This is the only piece of business logic worth lifting from the bundle verbatim if you're not adopting it. Google returns an hd claim on the ID token / user object for Workspace accounts. Check hd === 'yourcompany.com' and an email suffix check — they're not redundant, hd can be absent for consumer accounts and is only present when the Workspace domain is verified.

Role mapping pattern. Google has no roles. Two options: pull Workspace groups via the Admin SDK (requires domain-wide delegation — heavy), or keep a local role column and let admins assign it post-provisioning. For internal tools, default everyone to member and promote manually. Don't build group sync in v1.

Config pattern. Keep credentials out of code: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI in .env, referenced from config/services.php. Use config('services.google.redirect') everywhere — one place to change when you move from staging to prod.

Testing pattern. Never hit Google in tests. In Laravel, fake the Socialite user:

Socialite::shouldReceive('driver->user')->andReturn($fakeSocialiteUser);

Then test the three provisioning cases above plus the rejected-domain case. On Symfony, stub the provider service in the test container. If you adopted the bundle, this is the first test suite you write — it has none.

Feature-flag the rollout. Put the SSO button behind a config flag and keep the existing login path live for at least one release cycle. An SSO outage behind a flag is an inconvenience; without one it's a lockout.

Gotchas and Tips

The framework mismatch is the headline gotcha. Everything below assumes you've already decided whether you're on Symfony (bundle is viable) or Laravel (use Socialite, lift the business rules). If a teammate has already added this to composer.json on a Laravel app, that's the first thing to review.

Redirect URI must match byte-for-byte. Google's OAuth console compares the redirect URI exactly — scheme, host, path, and trailing slash. http://localhost:8000/auth/google/callback and http://localhost:8000/auth/google/callback/ are different registrations. Google also treats localhost and 127.0.0.1 as different hosts. This swallows more hours than any other single mistake in this flow.

Consent screen "Testing" mode bites you on refresh tokens. While the OAuth consent screen is unverified, refresh tokens expire after 7 days and you're capped at 100 test users. Long-lived refresh-token tests will "mysteriously" fail a week later. Publish the consent screen (or use internal/Workspace-only user type) before you draw conclusions about token handling.

Check state and PKCE. Socialite handles state for you (->stateless() disables it — only use that for genuine stateless APIs, never for browser sessions). If you're reading the bundle's source, explicitly confirm it generates and verifies state, and check whether PKCE is implemented. If neither is present, that's a finding for your security review, not a "we'll fix it later."

Don't trust email without email_verified. Google returns both. A mismatch is rare but the failure mode is silent account takeover via email linking. Hard-fail if email_verified !== true.

Session fixation. Always session()->regenerate() (Laravel) immediately after Auth::login(). If you're on Symfony, confirm the firewall's session strategy does this — don't assume. This is a one-line fix that's invisible until it's a pentest finding.

SSO logout ≠ Google logout. Logging the user out of your app leaves them signed into Google. For internal tools that's usually fine; for shared-device scenarios it isn't. If you need true logout, redirect to Google's logout endpoint — and accept that you can't reliably kill a Google session from a third-party app anyway.

Pin, don't track branches. If you do adopt the bundle on Symfony, pin an exact tag or commit SHA in composer.json, and pin the transitive OAuth2 client library explicitly. Zero stars means no compatibility guarantees across Symfony majors — let the install fail loudly at composer update time rather than behave oddly at runtime.

Watch for Symfony version drift. Symfony's security component changed substantially across 5→6→7 (authenticator-based security replaced guards). A bundle targeting an older major will force you onto an unsupported framework version or a shim. Check composer.json before you plan anything.

Vendor/fork within the first quarter if you adopt. No dependents means no CVE feed, no community patches, and a maintainer team you don't have an SLA with. Mirror it in your own VCS, name an owner, and annotate it in your dependency inventory as "internal fork, unmaintained upstream" so a future SBOM scan doesn't re-litigate the decision from scratch.

Write the runbook during the spike, not after. Configuration reference, failure-mode table (bad client ID, mismatched redirect, unverified consent screen, expired refresh token, rejected domain), and rollback-to-password-login steps. That document plus the adapter is the durable output — it survives whether you adopt, fork, or reject this package.

Extension points worth knowing. Laravel: the SocialiteWasCalled event lets you register custom drivers without touching the vendor package. Symfony with the bundle: the user provider and role-mapping hooks in Security/ are where RetItalia-specific conventions live — read those before deciding the bundle adds anything over knpu/oauth2-client. In most cases it won't, and that's the answer.