repository·5.x·Indexed 26 days ago
https://github.com/laravel/socialiteA package providing a fluent interface for OAuth authentication with multiple social media and service providers. It includes built-in drivers for Bitbucket, Facebook, GitHub, GitLab, Google, LinkedIn, Slack, Twitch, and X, and supports over 150 community-driven adapters. The documentation covers provider configuration in services.php, implementing redirect and callback routes, handling stateless authentication for APIs/SPAs, customizing scopes, and testing flows using Socialite::fake().
Laravel Socialite provides an expressive, fluent interface for OAuth authentication. It simplifies the process of implementing social authentication by handling the boilerplate code required for various providers.
Supported official providers include:
Socialite::fake() to allow testing redirect and callback flows without making actual network requests to OAuth providers. You can use it to fake redirects, mock callback user data, and assert that specific drivers were used.To use a provider, you must add its credentials to config/services.php. The configuration key must match the driver name exactly, including hyphens.
Required keys for each provider:
client_idclient_secretredirect (This must exactly match the Redirect URL registered in the provider's OAuth dashboard, including protocol and trailing slashes).When upgrading to Socialite 5.0 from version 4.x, ensure your environment meets the following minimum requirements:
A standard Socialite flow requires two routes:
Socialite::driver('provider')->redirect() to send the user to the OAuth provider.Socialite::driver('provider')->user() to receive the callback and retrieve user details.Important: In API or SPA contexts where session state is not maintained, you must call stateless() on the driver to avoid InvalidStateException.
When upgrading to Socialite 4.0 from version 3.x, ensure your environment meets the following minimum requirements:
config/services.php must match the driver name exactly. Hyphenated drivers like linkedin-openid or slack-openid require hyphenated keys. Mismatches fail silently.client_id, client_secret, and redirect. Missing any of these causes cryptic errors.stateless() on the driver.redirect value in config/services.php must be an exact match to the URL registered in the provider's dashboard.user() method throws an exception if the user declines authorization. Always wrap your callback logic in a try/catch or handle denied grants appropriately.SocialiteWasCalled event listener.You can modify the redirect request using the following methods:
scopes(): Merges additional scopes with the provider's default scopes.setScopes(): Replaces all default scopes with the provided list.with(array $parameters): Passes optional parameters to the provider (e.g., ['hd' => 'example.com'] for Google). Do not pass reserved parameters like state, response_type, client_id, redirect_uri, or scope via this method.asBotUser(): Slack only. Generates a bot token (xoxb-) instead of a user token (xoxp-). This must be called before both redirect() and user(). Only the token property will be hydrated.twitter driver supports both OAuth 1 and OAuth 2. To use OAuth 2, include 'oauth' => 2 in your services.twitter configuration array.gitlab driver can be customized by providing a host key in your services.gitlab configuration array. If not provided, it defaults to the standard GitLab host.When calling user(), Socialite returns a user object containing the following properties and methods:
Methods:
getId()getName()getEmail()getAvatar()getNickname()Properties:
tokenrefreshTokenexpiresInapprovedScopes