446 lines
12 KiB
Markdown
446 lines
12 KiB
Markdown
# Laravel Socialite
|
||
|
||
* Introduction
|
||
* Installation
|
||
* Upgrading Socialite
|
||
* Configuration
|
||
* Authentication
|
||
* Routing
|
||
* Authentication and Storage
|
||
* Access Scopes
|
||
* Slack Bot Scopes
|
||
* Optional Parameters
|
||
* Retrieving User Details
|
||
|
||
## Introduction
|
||
|
||
In addition to typical, form based authentication, Laravel also provides a
|
||
simple, convenient way to authenticate with OAuth providers using [Laravel
|
||
Socialite](https://github.com/laravel/socialite). Socialite currently supports
|
||
authentication via Facebook, X, LinkedIn, Google, GitHub, GitLab, Bitbucket,
|
||
and Slack.
|
||
|
||
Adapters for other platforms are available via the community driven [Socialite
|
||
Providers](https://socialiteproviders.com/) 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
|
||
|
||
|
||
composer require laravel/socialite
|
||
|
||
## Upgrading Socialite
|
||
|
||
When upgrading to a new major version of Socialite, it's important that you
|
||
carefully review [the upgrade
|
||
guide](https://github.com/laravel/socialite/blob/master/UPGRADE.md).
|
||
|
||
## Configuration
|
||
|
||
Before using Socialite, you will need to add credentials for the OAuth
|
||
providers your application utilizes. Typically, these credentials may be
|
||
retrieved by creating a "developer application" within the dashboard of the
|
||
service you will be authenticating with.
|
||
|
||
These credentials should be placed in your application's `config/services.php`
|
||
configuration file, and should use the key `facebook`, `x`, `linkedin-openid`,
|
||
`google`, `github`, `gitlab`, `bitbucket`, `slack`, or `slack-openid`,
|
||
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],
|
||
|
||
|
||
'github' => [
|
||
'client_id' => env('GITHUB_CLIENT_ID'),
|
||
'client_secret' => env('GITHUB_CLIENT_SECRET'),
|
||
'redirect' => 'http://example.com/callback-url',
|
||
],
|
||
|
||
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 routes below
|
||
demonstrate 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});
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
Route::get('/auth/redirect', function () {
|
||
return Socialite::driver('github')->redirect();
|
||
});
|
||
|
||
Route::get('/auth/callback', function () {
|
||
$user = Socialite::driver('github')->user();
|
||
|
||
// $user->token
|
||
});
|
||
|
||
The `redirect` method provided by the `Socialite` facade takes care of
|
||
redirecting the user to the OAuth provider, while the `user` method will
|
||
examine the incoming request and retrieve the user's information from the
|
||
provider after they have approved the authentication request.
|
||
|
||
### Authentication and 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](/docs/12.x/authentication#authenticate-a-user-instance). 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::updateOrCreate([
|
||
|
||
9 'github_id' => $githubUser->id,
|
||
|
||
10 ], [
|
||
|
||
11 'name' => $githubUser->name,
|
||
|
||
12 'email' => $githubUser->email,
|
||
|
||
13 'github_token' => $githubUser->token,
|
||
|
||
14 'github_refresh_token' => $githubUser->refreshToken,
|
||
|
||
15 ]);
|
||
|
||
16
|
||
|
||
17 Auth::login($user);
|
||
|
||
18
|
||
|
||
19 return redirect('/dashboard');
|
||
|
||
20});
|
||
|
||
|
||
use App\Models\User;
|
||
use Illuminate\Support\Facades\Auth;
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
Route::get('/auth/callback', function () {
|
||
$githubUser = Socialite::driver('github')->user();
|
||
|
||
$user = User::updateOrCreate([
|
||
'github_id' => $githubUser->id,
|
||
], [
|
||
'name' => $githubUser->name,
|
||
'email' => $githubUser->email,
|
||
'github_token' => $githubUser->token,
|
||
'github_refresh_token' => $githubUser->refreshToken,
|
||
]);
|
||
|
||
Auth::login($user);
|
||
|
||
return redirect('/dashboard');
|
||
});
|
||
|
||
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 use the `scopes` method to specify the
|
||
"scopes" that should be included in the authentication request. This method
|
||
will merge all previously specified scopes with the scopes that you specify:
|
||
|
||
|
||
|
||
1use Laravel\Socialite\Facades\Socialite;
|
||
|
||
2
|
||
|
||
3return Socialite::driver('github')
|
||
|
||
4 ->scopes(['read:user', 'public_repo'])
|
||
|
||
5 ->redirect();
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
return Socialite::driver('github')
|
||
->scopes(['read:user', 'public_repo'])
|
||
->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();
|
||
|
||
|
||
return Socialite::driver('github')
|
||
->setScopes(['read:user', 'public_repo'])
|
||
->redirect();
|
||
|
||
### Slack Bot Scopes
|
||
|
||
Slack's API provides [different types of access
|
||
tokens](https://api.slack.com/authentication/token-types), each with their own
|
||
set of [permission scopes](https://api.slack.com/scopes). Socialite is
|
||
compatible with both of the following Slack access tokens types:
|
||
|
||
* Bot (prefixed with `xoxb-`)
|
||
* User (prefixed with `xoxp-`)
|
||
|
||
By default, the `slack` driver will generate a `user` token and invoking the
|
||
driver's `user` method will return the user's details.
|
||
|
||
Bot tokens are primarily useful if your application will be sending
|
||
notifications to external Slack workspaces that are owned by your
|
||
application's users. To generate a bot token, invoke the `asBotUser` method
|
||
before redirecting the user to Slack for authentication:
|
||
|
||
|
||
|
||
1return Socialite::driver('slack')
|
||
|
||
2 ->asBotUser()
|
||
|
||
3 ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
|
||
|
||
4 ->redirect();
|
||
|
||
|
||
return Socialite::driver('slack')
|
||
->asBotUser()
|
||
->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
|
||
->redirect();
|
||
|
||
In addition, you must invoke the `asBotUser` method before invoking the `user`
|
||
method after Slack redirects the user back to your application after
|
||
authentication:
|
||
|
||
|
||
|
||
1$user = Socialite::driver('slack')->asBotUser()->user();
|
||
|
||
|
||
$user = Socialite::driver('slack')->asBotUser()->user();
|
||
|
||
When generating a bot token, the `user` method will still return a
|
||
`Laravel\Socialite\Two\User` instance; however, only the `token` property will
|
||
be hydrated. This token may be stored in order to [send notifications to the
|
||
authenticated user's Slack workspaces](/docs/12.x/notifications#notifying-
|
||
external-slack-workspaces).
|
||
|
||
### Optional Parameters
|
||
|
||
A number of OAuth providers support other optional parameters on 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();
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
return Socialite::driver('google')
|
||
->with(['hd' => 'example.com'])
|
||
->redirect();
|
||
|
||
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 application's 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.
|
||
|
||
Differing properties and methods may be available on this object 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});
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
Route::get('/auth/callback', function () {
|
||
$user = Socialite::driver('github')->user();
|
||
|
||
// OAuth 2.0 providers...
|
||
$token = $user->token;
|
||
$refreshToken = $user->refreshToken;
|
||
$expiresIn = $user->expiresIn;
|
||
|
||
// OAuth 1.0 providers...
|
||
$token = $user->token;
|
||
$tokenSecret = $user->tokenSecret;
|
||
|
||
// All providers...
|
||
$user->getId();
|
||
$user->getNickname();
|
||
$user->getName();
|
||
$user->getEmail();
|
||
$user->getAvatar();
|
||
});
|
||
|
||
#### Retrieving User Details From a Token
|
||
|
||
If you already have a valid access token for a user, you can retrieve their
|
||
user details using Socialite's `userFromToken` method:
|
||
|
||
|
||
|
||
1use Laravel\Socialite\Facades\Socialite;
|
||
|
||
2
|
||
|
||
3$user = Socialite::driver('github')->userFromToken($token);
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
$user = Socialite::driver('github')->userFromToken($token);
|
||
|
||
If you are using Facebook Limited Login via an iOS application, Facebook will
|
||
return an OIDC token instead of an access token. Like an access token, the
|
||
OIDC token can be provided to the `userFromToken` method in order to retrieve
|
||
user details.
|
||
|
||
#### Stateless Authentication
|
||
|
||
The `stateless` method may be used to disable session state verification. This
|
||
is useful when adding social authentication to a stateless API that does not
|
||
utilize cookie based sessions:
|
||
|
||
|
||
|
||
1use Laravel\Socialite\Facades\Socialite;
|
||
|
||
2
|
||
|
||
3return Socialite::driver('google')->stateless()->user();
|
||
|
||
|
||
use Laravel\Socialite\Facades\Socialite;
|
||
|
||
return Socialite::driver('google')->stateless()->user();
|
||
|