Laravel 8.x Laravel Socialite

イントロダクションIntroduction

Laravelは、一般的なフォームベースの認証に加えて、Laravel Socialite(ソーシャライト：名士)を使用したOAuthプロバイダで認証するためのシンプルで便利な方法も提供します。Socialiteは現在、Facebook、Twitter、LinkedIn、Google、GitHub、GitLab、Bitbucketでの認証をサポートしています。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 with Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, and Bitbucket.

lightbulb">Tip!! 他のプラットフォームのアダプタは、コミュニティにより管理されているSocialiteプロバイダWebサイトで一覧できます。{tip} Adapters for other platforms are listed at the community driven Socialite Providers[https://socialiteproviders.com/] website.

インストールInstallation

Socialiteを使い始めるには、Composerパッケージマネージャーを使用して、プロジェクトの依存関係へパッケージを追加します。To get started with Socialite, use the Composer package manager to add the package to your project's dependencies:

composer require laravel/socialite

SocialiteのアップグレードUpgrading Socialite

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

Socialiteを使用する前に、アプリケーションが使用するOAuthプロバイダの資格情報を追加する必要があります。これらの認証情報は、アプリケーションのconfig/services.php設定ファイルへ配置しておく必要があり、アプリケーションに必要なプロバイダに応じキーとしてfacebook、twitter、linkedin、google、github、gitlab、bitbucketを使用する必要があります。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:

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

lightbulb">Tip!! redirectオプションが相対パスである場合、自動的に完全なURLへ解決されます。{tip} If the redirect option contains a relative path, it will automatically be resolved to a fully qualified URL.

認証Authentication

ルートRouting

OAuthプロバイダを使用してユーザーを認証するには、２つのルートが必要です。１つはユーザーをOAuthプロバイダにリダイレクトするためのもので、もう１つは認証後にプロバイダからのコールバックを受信するためのものです。以下のコントローラの例は、両方のルートの実装を示しています。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:

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
});

Socialiteファサードが提供するredirectメソッドは、ユーザーをOAuthプロバイダへリダイレクトしますが、userメソッドは、受信したリクエストを読み取り、認証後にプロバイダからユーザーの情報を取得します。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

OAuthプロバイダからユーザーを取得したら、そのユーザーがアプリケーションのデータベースに存在するかを判断し、ユーザーを認証します。ユーザーがアプリケーションのデータベースに存在していない場合は通常、そのユーザーを表す新しいレコードをデータベースに作成します。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/{{version}}/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:

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::where('github_id', $githubUser->id)->first();

    if ($user) {
        $user->update([
            'github_token' => $githubUser->token,
            'github_refresh_token' => $githubUser->refreshToken,
        ]);
    } else {
        $user = User::create([
            'name' => $githubUser->name,
            'email' => $githubUser->email,
            'github_id' => $githubUser->id,
            'github_token' => $githubUser->token,
            'github_refresh_token' => $githubUser->refreshToken,
        ]);
    }

    Auth::login($user);

    return redirect('/dashboard');
});

lightbulb">Tip!! 特定のOAuthプロバイダからどんなユーザー情報が得られるかについては、ユーザー情報の取得ドキュメントを参照してください。{tip} For more information regarding what user information is available from specific OAuth providers, please consult the documentation on retrieving user details[#retrieving-user-details].

アクセススコープAccess Scopes

ユーザーをリダイレクトする前に、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:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

setScopesメソッドを使用して、認証リクエストの既存のスコープをすべて上書きできます。You can overwrite all existing scopes on the authentication request using the setScopes method:

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

オプションのパラメータOptional Parameters

多くのOAuthプロバイダがリダイレクトリクエスト中のオプションパラメータをサポートしています。リクエストにオプションパラメータを含めるには、withメソッドを呼び出し、連想配列を渡します。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:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')
    ->with(['hd' => 'example.com'])
    ->redirect();

Note: note withメソッド使用時は、stateやresponse_typeなどの予約キーワードを渡さないように注意してください。{note} When using the with method, be careful not to pass any reserved keywords such as state or response_type.

ユーザー詳細情報の取得Retrieving User Details

ユーザーを認証コールバックルートへリダイレクトした後、Socialiteのuserメソッドを使用してユーザーの詳細を取得できます。userメソッドが返すユーザーオブジェクトは、ユーザーに関する情報を独自のデータベースに保存するために使用できるさまざまなプロパティとメソッドを提供します。認証するOAuthプロバイダがOAuth1.0またはOAuth2.0のどちらをサポートしているかに応じて、さまざまなプロパティとメソッドが使用できます。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:

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // OAuth2.0プロバイダ
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // OAuth1.0プロバイダ
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // 両プロバイダ
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

トークンからのユーザー詳細情報の取得(OAuth2)Retrieving User Details From A Token (OAuth2)

ユーザーの有効なアクセストークンを既に持っている場合は、SocialiteのuserFromTokenメソッドを使用してユーザーの詳細を取得できます。If you already have a valid access token for a user, you can retrieve their details using Socialite's userFromToken method:

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('github')->userFromToken($token);

トークンとSecretからのユーザー詳細情報の取得(OAuth1)Retrieving User Details From A Token And Secret (OAuth1)

ユーザーの有効なトークンとシークレットが既にある場合は、SocialiteのuserFromTokenAndSecretメソッドを使用してユーザーの詳細を取得できます。If you already have a valid token and secret for a user, you can retrieve their details using Socialite's userFromTokenAndSecret method:

use Laravel\Socialite\Facades\Socialite;

$user = Socialite::driver('twitter')->userFromTokenAndSecret($token, $secret);

ステートレス認証Stateless Authentication

statelessメソッドを使用して、セッション状態の検証を無効にすることができます。これは、APIにソーシャル認証を追加するときに役立ちます。The stateless method may be used to disable session state verification. This is useful when adding social authentication to an API:

use Laravel\Socialite\Facades\Socialite;

return Socialite::driver('google')->stateless()->user();

Note: note ステートレス認証は、認証にOAuth1.0を使用するTwitterドライバでは使用できません。{note} Stateless authentication is not available for the Twitter driver, which uses OAuth 1.0 for authentication.