Laravel 11.x Laravel Socialite

イントロダクションIntroduction

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

lightbulb Note: 他のプラットフォームのアダプタは、コミュニティにより管理されているSocialiteプロバイダWebサイトから利用できます。[!NOTE]
Adapters for other platforms are available via 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プロバイダの認証情報を追加する必要があります。通常、これらの認証情報は、認証するサービスのダッシュボード内で「開発者用アプリケーション」を作成することで取得できます。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.

こうした認証情報は、アプリケーションのconfig/services.php設定ファイルへ記述します。キーはfacebook, X、linkedin-openid、google、github、gitlab、bitbucket、slack、slack-openidで、アプリケーションで必要なプロバイダによります。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:

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

lightbulb Note: redirectオプションが相対パスである場合、自動的に完全なURLへ解決されます。[!NOTE]
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 routes below demonstrate 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 examine the incoming request and retrieve the user's information from the provider after they have approved the authentication request.

認証と保存Authentication and 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::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');
});

lightbulb Note: 特定のOAuthプロバイダからどんなユーザー情報が得られるかについては、ユーザー情報の取得ドキュメントを参照してください。[!NOTE]
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 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:

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

Slack BotスコープSlack Bot Scopes

SlackのAPIはさまざまなタイプのアクセストークンを提供しており、それぞれに許可スコープが設定されています。Socialiteは以下のSlackのアクセストークンに対応しています：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:

slackドライバはデフォルトで、userトークンを生成し、ドライバのuserメソッドを呼び出すと、そのユーザーの詳細を返します。By default, the slack driver will generate a user token and invoking the driver's user method will return the user's details.

ボットトークンは主に、アプリケーションのユーザーが所有する、外部のSlackワークスペースへ通知を送信する場合に便利です。ボットトークンを生成するには、ユーザーを認証のためにSlackにリダイレクトする前に、asBotUserメソッドを呼び出します：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:

return Socialite::driver('slack')
    ->asBotUser()
    ->setScopes(['chat:write', 'chat:write.public', 'chat:write.customize'])
    ->redirect();

さらに、認証後にSlackがユーザーをアプリケーションへリダイレクトした後、userメソッドを呼び出す前にasBotUserメソッドを呼び出す必要があります。In addition, you must invoke the asBotUser method before invoking the user method after Slack redirects the user back to your application after authentication:

$user = Socialite::driver('slack')->asBotUser()->user();

ボットトークンを生成するときでも、userメソッドはLaravel\Socialite\Two\Userインスタンスを返しますが、tokenプロパティだけがハイドレートされます。このトークンは、認証されたユーザーのSlackワークスペースに通知を送るために保存しておくべきでしょう。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/{{version}}/notifications#notifying-external-slack-workspaces].

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

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

use Laravel\Socialite\Facades\Socialite;

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

warning Warning! withメソッド使用時は、stateやresponse_typeなどの予約キーワードを渡さないように注意してください。[!WARNING]
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メソッドが返すユーザーオブジェクトは、ユーザーに関する情報をデータベースへ保存するために使用できる様々なプロパティやメソッドを提供します。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.

認証につかうOAuthプロバイダが、OAuth1.0とOAuth2.0のどちらをサポートしているかにより、このオブジェクトで利用できるプロパティやメソッドが異なります。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:

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

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

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

use Laravel\Socialite\Facades\Socialite;

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

iOSアプリケーションでFacebook限定ログインを使用している場合、Facebookはアクセストークンの代わりにOIDCトークンを返します。アクセストークンと同様に、OIDCトークンもuserFromTokenメソッドへ渡し、ユーザーの詳細情報を取得できます。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

statelessメソッドを使用すると、セッション状態の確認を無効にできます。これは、クッキーベースのセッションを利用しないステートレスAPIに、ソーシャル認証を追加する場合に有用です。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:

use Laravel\Socialite\Facades\Socialite;

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