Manages OAuth social authentication with Laravel Socialite. Activate when adding social login providers; configuring OAuth redirect/callback flows; retrieving authenticated user details; customizing scopes or parameters; setting up community providers; testing with Socialite fakes; or when the user mentions social login, OAuth, Socialite, or third-party authentication.
Use search-docs for detailed Socialite patterns and documentation (installation, configuration, routing, callbacks, testing, scopes, stateless auth).
Built-in: facebook, twitter, twitter-oauth-2, linkedin, linkedin-openid, google, github, gitlab, bitbucket, slack, slack-openid, twitch
Community: 150+ additional providers at socialiteproviders.com. For provider-specific setup, use WebFetch on https://socialiteproviders.com/{provider-name}.
Configuration key in config/services.php must match the driver name exactly — note the hyphenated keys: twitter-oauth-2, linkedin-openid, slack-openid.
Twitter/X: Use twitter-oauth-2 (OAuth 2.0) for new projects. The legacy twitter driver is OAuth 1.0. Driver names remain unchanged despite the platform rebrand.
Community providers differ from built-in providers in the following ways:
composer require socialiteproviders/{name}search-docs for the registration patternAdd the provider's client_id, client_secret, and redirect to config/services.php. The config key must match the driver name exactly.
Two routes are needed: one that calls Socialite::driver('provider')->redirect() to send the user to the OAuth provider, and one that calls Socialite::driver('provider')->user() to receive the callback and retrieve user details.
In the callback, use updateOrCreate to find or create a user record from the provider's response (id, name, email, token, refreshToken), then call Auth::login().
scopes() — merge additional scopes with the provider's defaultssetScopes() — replace all scopes entirelywith() — pass optional parameters (e.g., ['hd' => 'example.com'] for Google)asBotUser() — Slack only; generates a bot token (xoxb-) instead of a user token (xoxp-). Must be called before both redirect() and user(). Only the token property will be hydrated on the user object.stateless() — for API/SPA contexts where session state is not maintainedclient_id, client_secret, and redirect are all presentUse search-docs for complete code examples of each step.
Use search-docs for usage details on: enablePKCE(), userFromToken($token), userFromTokenAndSecret($token, $secret) (OAuth 1.0), retrieving user details.
User object: getId(), getName(), getEmail(), getAvatar(), getNickname(), token, refreshToken, expiresIn, approvedScopes
Socialite provides Socialite::fake() for testing redirects and callbacks. Use search-docs for faking redirects, callback user data, custom token properties, and assertion methods.
linkedin-openid, slack-openid, twitter-oauth-2). Mismatch silently fails.client_id, client_secret, and redirect in config/services.php. Missing any one causes cryptic errors.scopes() merges with defaults; setScopes() replaces all scopes entirely.stateless() in API/SPA contexts causes InvalidStateException.config/services.php must exactly match the provider's OAuth dashboard (including trailing slashes and protocol).state, response_type, client_id, redirect_uri, or scope via with() — these are reserved.SocialiteWasCalled.user() throws when the user declines authorization. Always handle denied grants.