Laravel Socialite

Introduction

In addition to typical, form based authentication, Laravel also provides a simple, convenient way to authenticate with OAuth providers using Laravel Socialite. Socialite currently supports authentication with Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, and Bitbucket.

lightbulb

Adapters for other platforms are listed at the community driven Socialite Providers website.

Installation

To get started with Socialite, use the Composer package manager to add the package to your project's dependencies:

1composer require laravel/socialite
1composer require laravel/socialite

Upgrading Socialite

When upgrading to a new major version of Socialite, it's important that you carefully review the upgrade guide.

Configuration

Before using Socialite, you will need to add credentials for the OAuth providers your application utilizes. These credentials should be placed in your application's config/services.php configuration file, and should use the key facebook, twitter, linkedin, google, github, gitlab, or bitbucket, depending on the providers your application requires:

1'github' => [
2 'client_id' => env('GITHUB_CLIENT_ID'),
3 'client_secret' => env('GITHUB_CLIENT_SECRET'),
4 'redirect' => 'http://example.com/callback-url',
5],
1'github' => [
2 'client_id' => env('GITHUB_CLIENT_ID'),
3 'client_secret' => env('GITHUB_CLIENT_SECRET'),
4 'redirect' => 'http://example.com/callback-url',
5],
lightbulb

If the redirect option contains a relative path, it will automatically be resolved to a fully qualified URL.

Authentication

Routing

To authenticate users using an OAuth provider, you will need two routes: one for redirecting the user to the OAuth provider, and another for receiving the callback from the provider after authentication. The example controller below demonstrates the implementation of both routes:

1use Laravel\Socialite\Facades\Socialite;
2 
3Route::get('/auth/redirect', function () {
4 return Socialite::driver('github')->redirect();
5});
6 
7Route::get('/auth/callback', function () {
8 $user = Socialite::driver('github')->user();
9 
10 // $user->token
11});
1use Laravel\Socialite\Facades\Socialite;
2 
3Route::get('/auth/redirect', function () {
4 return Socialite::driver('github')->redirect();
5});
6 
7Route::get('/auth/callback', function () {
8 $user = Socialite::driver('github')->user();
9 
10 // $user->token
11});

The redirect method provided by the Socialite facade takes care of redirecting the user to the OAuth provider, while the user method will read the incoming request and retrieve the user's information from the provider after they are authenticated.

Authentication & Storage

Once the user has been retrieved from the OAuth provider, you may determine if the user exists in your application's database and authenticate the user. If the user does not exist in your application's database, you will typically create a new record in your database to represent the user:

1use App\Models\User;
2use Illuminate\Support\Facades\Auth;
3use Laravel\Socialite\Facades\Socialite;
4 
5Route::get('/auth/callback', function () {
6 $githubUser = Socialite::driver('github')->user();
7 
8 $user = User::where('github_id', $githubUser->id)->first();
9 
10 if ($user) {
11 $user->update([
12 'github_token' => $githubUser->token,
13 'github_refresh_token' => $githubUser->refreshToken,
14 ]);
15 } else {
16 $user = User::create([
17 'name' => $githubUser->name,
18 'email' => $githubUser->email,
19 'github_id' => $githubUser->id,
20 'github_token' => $githubUser->token,
21 'github_refresh_token' => $githubUser->refreshToken,
22 ]);
23 }
24 
25 Auth::login($user);
26 
27 return redirect('/dashboard');
28});
1use App\Models\User;
2use Illuminate\Support\Facades\Auth;
3use Laravel\Socialite\Facades\Socialite;
4 
5Route::get('/auth/callback', function () {
6 $githubUser = Socialite::driver('github')->user();
7 
8 $user = User::where('github_id', $githubUser->id)->first();
9 
10 if ($user) {
11 $user->update([
12 'github_token' => $githubUser->token,
13 'github_refresh_token' => $githubUser->refreshToken,
14 ]);
15 } else {
16 $user = User::create([
17 'name' => $githubUser->name,
18 'email' => $githubUser->email,
19 'github_id' => $githubUser->id,
20 'github_token' => $githubUser->token,
21 'github_refresh_token' => $githubUser->refreshToken,
22 ]);
23 }
24 
25 Auth::login($user);
26 
27 return redirect('/dashboard');
28});
lightbulb

For more information regarding what user information is available from specific OAuth providers, please consult the documentation on retrieving user details.

Access Scopes

Before redirecting the user, you may also add additional "scopes" to the authentication request using the scopes method. This method will merge all existing scopes with the scopes that you supply:

1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('github')
4 ->scopes(['read:user', 'public_repo'])
5 ->redirect();
1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('github')
4 ->scopes(['read:user', 'public_repo'])
5 ->redirect();

You can overwrite all existing scopes on the authentication request using the setScopes method:

1return Socialite::driver('github')
2 ->setScopes(['read:user', 'public_repo'])
3 ->redirect();
1return Socialite::driver('github')
2 ->setScopes(['read:user', 'public_repo'])
3 ->redirect();

Optional Parameters

A number of OAuth providers support optional parameters in the redirect request. To include any optional parameters in the request, call the with method with an associative array:

1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('google')
4 ->with(['hd' => 'example.com'])
5 ->redirect();
1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('google')
4 ->with(['hd' => 'example.com'])
5 ->redirect();
exclamation

When using the with method, be careful not to pass any reserved keywords such as state or response_type.

Retrieving User Details

After the user is redirected back to your authentication callback route, you may retrieve the user's details using Socialite's user method. The user object returned by the user method provides a variety of properties and methods you may use to store information about the user in your own database. Different properties and methods may be available depending on whether the OAuth provider you are authenticating with supports OAuth 1.0 or OAuth 2.0:

1use Laravel\Socialite\Facades\Socialite;
2 
3Route::get('/auth/callback', function () {
4 $user = Socialite::driver('github')->user();
5 
6 // OAuth 2.0 providers...
7 $token = $user->token;
8 $refreshToken = $user->refreshToken;
9 $expiresIn = $user->expiresIn;
10 
11 // OAuth 1.0 providers...
12 $token = $user->token;
13 $tokenSecret = $user->tokenSecret;
14 
15 // All providers...
16 $user->getId();
17 $user->getNickname();
18 $user->getName();
19 $user->getEmail();
20 $user->getAvatar();
21});
1use Laravel\Socialite\Facades\Socialite;
2 
3Route::get('/auth/callback', function () {
4 $user = Socialite::driver('github')->user();
5 
6 // OAuth 2.0 providers...
7 $token = $user->token;
8 $refreshToken = $user->refreshToken;
9 $expiresIn = $user->expiresIn;
10 
11 // OAuth 1.0 providers...
12 $token = $user->token;
13 $tokenSecret = $user->tokenSecret;
14 
15 // All providers...
16 $user->getId();
17 $user->getNickname();
18 $user->getName();
19 $user->getEmail();
20 $user->getAvatar();
21});

Retrieving User Details From A Token (OAuth2)

If you already have a valid access token for a user, you can retrieve their details using Socialite's userFromToken method:

1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('github')->userFromToken($token);
1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('github')->userFromToken($token);

Retrieving User Details From A Token And Secret (OAuth1)

If you already have a valid token and secret for a user, you can retrieve their details using Socialite's userFromTokenAndSecret method:

1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);
1use Laravel\Socialite\Facades\Socialite;
2 
3$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

Stateless Authentication

The stateless method may be used to disable session state verification. This is useful when adding social authentication to an API:

1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('google')->stateless()->user();
1use Laravel\Socialite\Facades\Socialite;
2 
3return Socialite::driver('google')->stateless()->user();
exclamation

Stateless authentication is not available for the Twitter driver, which uses OAuth 1.0 for authentication.

Comments

No Comments Yet

“Laravel” is a Trademark of Taylor Otwell.
The source documentation is released under MIT license. See laravel/docs on GitHub for details.
The translated documentations are released under MIT license. See cornch/laravel-docs-l10n on GitHub for details.