Laravel Social Auth Laravel Package

Getting Started

1. Install the package and publish its assets:

   composer require cable8mm/laravel-social-auth
   php artisan vendor:publish --tag=social-auth-config
   php artisan vendor:publish --tag=social-auth-migrations
   php artisan migrate
   

2. Start in the published config file (config/social-auth.php or the package's equivalent). This is the single source of truth for enabled providers, credentials, scopes, redirect behaviour, and route registration. Read it top to bottom before touching any controller — most "why isn't this working" questions are answered there.

3. Read .replworks/TECH_STACK.md (renamed from FRAMEWORK.md in v1.3.0) and the docs under .replworks/. The docs were reorganised this release; if you're following older blog posts or the v1.2.x README, cross-check against these files first, because several config keys and unused code paths were removed in PR #43.

4. Add the provider credentials to .env. For OAuth providers you need a client ID/secret; for GitHub App (new in v1.3.0) you need the App ID, client ID, client secret, and private key, plus a webhook secret if you want deauthorisation callbacks:

   GITHUB_CLIENT_ID=
   GITHUB_CLIENT_SECRET=
   GITHUB_APP_ID=
   GITHUB_APP_PRIVATE_KEY=   # or a path, depending on config
   GITHUB_WEBHOOK_SECRET=
   

5. First use case: drop a "Continue with GitHub" link on your login page pointing at the package's redirect route (check php artisan route:list | grep -i social for the exact names). The flow is redirect → provider consent → callback → package resolves the provider user → your handler maps it to an Authenticatable. You should not need to write a controller for the happy path; the package ships one.

Implementation Patterns

Provider configuration, not provider code. Each provider is a config block (driver, credentials, scopes, mapping). Adding a provider is normally a config entry plus env vars, not a new class. Resist subclassing the driver until you've confirmed the package has no extension hook for what you need.

Separate the two flows. The package distinguishes login (create-or-find a user) from connect (attach a social identity to an already-authenticated user). In v1.3.0 the connect intent is bound to the issued state value rather than a global/session-wide key (PR #44). This means:

• Always initiate connect from a route behind auth middleware.
• Let the package issue and consume the state; don't manually stash "linking user X" in the session yourself, or you'll reintroduce exactly the race the fix closed.
• Expect the callback handler to be able to tell you which intent was in flight; wire your controller to branch on that rather than on Auth::check() alone.

Handle the callback in one place. Point every provider at a single callback action and switch on the resolved provider. Two things to do there:

1. Persist the social identity (provider, provider_user_id, tokens, expiry) via the package's model/table.
2. Resolve to an application user — match on provider_user_id first, then fall back to email, and make the email-collision decision explicit (auto-link vs. reject vs. prompt). Do not leave this to chance; it is the single most common source of account-takeover bugs in social auth.

Consent and post-consent redirects. v1.3.0 keeps the sign-up start page as the post-consent redirect (PR #39). If you add a consent screen of your own (terms, marketing opt-in), the user should land back on the page they came from, not the dashboard. Verify this still holds after any route or middleware changes on your side; a redirect()->intended() in your own code can silently override it.

Webhooks and deauthorisation. GitHub App login (PR #38) and Naver disconnect/revoke (PR #45) bring webhook/callback endpoints into play. Register them in the config, exclude them from CSRF (VerifyCsrfToken $except, or the package's route group if it handles this), and verify signatures using the configured secret. Wire them to mark the social account revoked rather than deleting the user — users expect their local account to survive an unlink from the provider side.

Kakao unlink (PR #41). Treat Kakao's unlink as a first-class event: your "disconnect this provider" action should call the package's revoke path so the token is actually invalidated at Kakao, not just deleted locally. Otherwise re-login can resurrect a stale link.

Testing. Use Socialite's fake/stub mechanism to drive the callback and assert on your user-resolution rules: existing identity, new email, existing email, revoked token. The security-relevant logic lives in that mapping, so it deserves tests independent of the package.

Gotchas and Tips

• GitHub App ≠ GitHub OAuth App. This is the biggest trap in v1.3.0. The credentials, the callback URL registration, and the permission model differ. If you already had a GitHub OAuth App configured, don't assume the new driver will pick up GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET and just work — check which config keys the App driver reads, and confirm the App is installed on the relevant account/org. "Bad credentials" during token exchange usually means App ID vs. client ID confusion.
• State and nonce are session-bound. The nonce hardening (PR #41) and state-bound connect intent (PR #44) both depend on the session surviving the round trip to the provider. Common breakers: SESSION_DOMAIN not covering the callback host, SameSite=Strict on the session cookie, a proxy terminating TLS and rewriting the scheme, or multiple app servers without a shared session store. Symptom: intermittent "invalid state" on production only.
• Don't cache stale config. php artisan config:cache after any config/social-auth.php change. Several config keys were removed in PR #43; if you copied the old file into your app, you may be carrying dead keys that no longer do anything — diff against the freshly published config.
• Post-consent redirect behaviour is now intentional. If users complain they land back on the sign-up start page after consenting, that's the v1.3.0 fix, not a bug. Change it via config/your own redirect, not by patching the package.
• Webhook routes and CSRF. If you get 419s on provider callbacks, the route isn't excluded from CSRF or isn't in the package's route group. Check route:list and the middleware stack before assuming a signature failure.
• Naver revoke specifics. Naver's disconnect callback and token revoke follow their own guide (PR #45), which differs from the generic OAuth revoke pattern. If you wrote a custom disconnect, re-check it against the new implementation — the old assumptions may now be wrong.
• Docs moved. Anything under .replworks/ is now the reference (and TECH_STACK.md replaces FRAMEWORK.md). Update internal onboarding links; broken doc links after an upgrade are a support-ticket generator.
• Upgrade check. v1.3.0 is a minor release but bundles security fixes (nonce, state binding, webhook handling). Treat it as a security upgrade: pull it in promptly, re-test your callback and disconnect paths, and re-run your account-linking tests specifically.