Social Accounts Laravel Package

Product Decisions This Supports

• Sign-up and login funnel design — decides whether "Continue with Google/Facebook/GitHub" ships in the next release, and whether social-only accounts (nullable email/password) are acceptable for your user base. The package ships the migration stub for that explicitly.
• Build vs. buy for OAuth plumbing — the recurring question of whether to hand-roll redirect/callback/state/token-exchange per provider or take a dependency. This package makes "buy" a ~1-day integration instead of a 1–3 sprint build.
• Account linking as a product surface, not just a login button — the polymorphic social_accounts relation supports use cases beyond auth: connecting a brand's Instagram/Twitter account for publishing, analytics pulls, or agency/tenant setups where one workspace owns many provider accounts.
• Roadmap sequencing for "connected accounts" — the SocialAccountAdded / SocialUserCreated events plus the Strategy interface (FindUser, FindOrCreateUser, AddSocialAccount) let you defer onboarding flows, profile sync, and permission prompts to later releases without re-architecting.
• Security and compliance scoping — the docs are explicit that tokens are not encrypted at rest by default and are not auto-refreshed. That forces a decision on whether token custody is in scope for v1 or a documented follow-up, which shapes both infra work and privacy review.
• API contract decisions — SocialAccountResource gives you a typed JSON shape for "which providers is this user connected to," useful if a mobile app or SPA needs to render connection state.
• Enterprise/SSO positioning — clarifies a boundary: this is consumer social login, not SAML/OIDC workforce SSO. Useful for saying "no" to a sales request without a research spike.

When to Consider This Package

Consider it when:

• You are on Laravel and already comfortable with Laravel Socialite; this is a thin, conventional layer on top of it (laravel/socialite ^5.0 is the only external dependency).
• You need multiple providers attached to multiple models, and you don't want provider columns colonising users. The polymorphic relation and config-driven model/table/column overrides cover this cleanly.
• You want first-party control of the OAuth flow but not the boilerplate: named routes per provider (social-accounts.login.{provider}, social-accounts.callback.{provider}), automatic redirect-URI wiring, optional gate hooks (login-with-provider, add-social-account), and the ability to disable the built-in routes and own the controller.
• The team accepts extending rather than forking — overriding the model via the config model key and the resource via resource key is the sanctioned path.
• Social login is a convenience feature, not the sole authentication mechanism, for v1.

Look elsewhere when:

• You need automatic refresh-token lifecycle management. This package deliberately leaves that to you — budget a queued job and a provider-specific service class.
• You need encryption-at-rest out of the box. You must add encrypted casts yourself; if your security review treats that as non-negotiable-and-pre-solved, this adds work.
• You need workforce SSO (SAML, SCIM, OIDC with IdP-initiated flows), MFA policy, or directory sync. Wrong tool; look at dedicated SSO/identity vendors.
• You need a vendor with a support SLA, security disclosures process, or a meaningful adoption signal. Two stars and a single maintainer is the headline risk — treat this as "adoptable source code," not "adoptable vendor."
• Your stack is not Laravel, or you're on a Laravel version outside what the v9.x line targets.
• You need rich, pre-built per-provider behaviour: the package normalises provider access but does not special-case each provider's quirks, scopes, or rate limits. Complex providers (Instagram Graph, LinkedIn org pages) will need your own logic regardless.

Adoption guardrails if you proceed: add the user_id + provider unique index yourself if one-account-per-provider-per-user is a product rule (the default migration only enforces provider + provider_id); add encrypted casts on token/refresh_token; keep the built-in routes off in production if you need extra state parameters; and vendor-pin the version, since upstream release cadence is unpredictable.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed Laravel component that gives us "Sign in with Google/Facebook/GitHub" and a place to store users' connected social accounts. It converts roughly one to three sprints of undifferentiated OAuth plumbing into roughly one to three days of integration, at zero licence cost. It is not a strategic dependency — it sits on top of Laravel Socialite, which we'd depend on anyway, and the code is small enough that we could absorb it in-house if the maintainer walks away. Recommendation: adopt for the social-login slice of the roadmap, with two small hardening tasks (token encryption, token refresh job) scoped as our own work rather than assumed as included.

To engineering: It's conventional Laravel — a HasSocialAccounts trait, a config-driven SocialAccount model, per-provider routes, events, and a Strategy interface for custom login-vs-link behaviour. No internal dependencies, tests use Mockery against Socialite contracts. The parts we own: token encryption casts, refresh-token scheduling, the one-account-per-provider uniqueness rule, and any provider with non-standard scopes. Config-driven model and resource overrides mean we extend rather than fork, which keeps upstream merges cheap. Main risk is maintenance, not architecture — pin the version and keep our extensions in our own namespace.

To security/compliance: Tokens are persisted in the database and are not encrypted by default, and refresh is not automatic. Treat both as our deliverables before any provider with write scope (publishing, messaging) is enabled. Read-only scopes on login-only providers can ship earlier.

Ask: approve the integration for the next release, and approve a follow-on ticket for token encryption plus a refresh job so we don't ship a connected-accounts feature with stale tokens.