Laravel Socialite

번역일: 2026년 6월 20일

Laravel Socialite

소개
설치
Socialite 업그레이드
설정
인증
사용자 정보 조회

소개

Laravel은 폼 기반의 일반적인 인증 외에도, Laravel Socialite를 통해 OAuth 공급자 기반 소셜 로그인을 간단하게 구현할 수 있습니다. Socialite는 현재 Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, Bitbucket, Slack 인증을 지원합니다.

NOTE

위에서 언급되지 않은 플랫폼(카카오, 네이버 등)에 대한 어댑터는 커뮤니티 기반의 Socialite Providers 웹사이트에서 찾을 수 있습니다.

설치

Composer로 패키지를 설치합니다.

composer require laravel/socialite

Socialite 업그레이드

Socialite의 새로운 메이저 버전으로 업그레이드할 때는 반드시 업그레이드 가이드를 꼼꼼히 검토하시기 바랍니다.

설정

Socialite를 사용하려면 먼저 각 OAuth 공급자의 인증 정보를 애플리케이션에 등록해야 합니다. 이 인증 정보는 보통 각 서비스의 개발자 콘솔에서 애플리케이션을 등록하면 발급받을 수 있습니다.

발급받은 정보는 config/services.php 파일에 다음 키 이름으로 추가합니다. 지원되는 키 이름은 facebook, twitter(OAuth 1.0), twitter-oauth-2(OAuth 2.0), linkedin-openid, google, github, gitlab, bitbucket, slack입니다.

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

NOTE

redirect 값에 상대 경로를 지정하면 Laravel이 자동으로 완전한 URL로 변환해 줍니다.

인증

라우팅

OAuth 인증을 처리하려면 두 개의 라우트가 필요합니다. 하나는 사용자를 OAuth 공급자로 리다이렉트하는 라우트이고, 다른 하나는 인증 완료 후 공급자로부터 콜백을 받는 라우트입니다.

아래는 두 라우트의 기본 구현 예시입니다.

use Laravel\Socialite\Facades\Socialite;

// 사용자를 GitHub 로그인 페이지로 리다이렉트
Route::get('/auth/redirect', function () {
    return Socialite::driver('github')->redirect();
});

// GitHub 인증 완료 후 콜백 처리
Route::get('/auth/callback', function () {
    $user = Socialite::driver('github')->user();

    // $user->token
});

Socialite 파사드의 redirect 메서드는 사용자를 OAuth 공급자로 리다이렉트하고, user 메서드는 콜백 요청을 분석하여 공급자로부터 사용자 정보를 가져옵니다.

인증 및 저장

OAuth 공급자로부터 사용자 정보를 받은 뒤에는, 해당 사용자가 데이터베이스에 이미 존재하는지 확인하고 사용자 인증을 처리합니다. 존재하지 않는 경우에는 새 레코드를 생성합니다.

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

NOTE

각 OAuth 공급자에서 제공하는 사용자 정보의 종류는 아래 사용자 정보 조회 섹션을 참고하세요.

액세스 스코프

사용자를 리다이렉트하기 전에 scopes 메서드로 요청할 권한 범위(scope)를 지정할 수 있습니다. 이 메서드는 이미 지정된 스코프에 새 스코프를 추가(병합)합니다.

use Laravel\Socialite\Facades\Socialite;

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

기존 스코프를 완전히 덮어쓰려면 setScopes 메서드를 사용합니다.

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

Slack 봇 스코프

Slack API는 여러 종류의 액세스 토큰을 제공하며, 각 토큰마다 사용 가능한 권한 스코프가 다릅니다. Socialite는 아래 두 가지 Slack 토큰 유형을 모두 지원합니다.

Bot 토큰 (xoxb- 접두사)
User 토큰 (xoxp- 접두사)

기본적으로 slack 드라이버는 User 토큰을 생성하며, user 메서드를 호출하면 해당 사용자의 정보가 반환됩니다.

Bot 토큰은 애플리케이션이 사용자의 Slack 워크스페이스에 알림을 전송해야 할 때 주로 사용합니다. Bot 토큰을 발급받으려면 Slack으로 리다이렉트하기 전에 asBotUser 메서드를 호출하세요.

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

콜백에서 사용자 정보를 가져올 때도 마찬가지로 asBotUser를 먼저 호출해야 합니다.

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

Bot 토큰으로 인증할 경우 user 메서드는 Laravel\Socialite\Two\User 인스턴스를 반환하지만, token 속성만 채워집니다. 이 토큰을 저장해 두면 이후 인증된 사용자의 Slack 워크스페이스에 알림을 전송할 때 활용할 수 있습니다.

선택적 파라미터

일부 OAuth 공급자는 리다이렉트 요청에 추가 파라미터를 지원합니다. with 메서드에 연관 배열을 전달하면 이를 포함할 수 있습니다.

use Laravel\Socialite\Facades\Socialite;

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

WARNING

with 메서드 사용 시 state, response_type 등 OAuth 프로토콜에서 예약된 키워드는 전달하지 않도록 주의하세요.

사용자 정보 조회

사용자가 인증을 마치고 콜백 라우트로 돌아오면, Socialite의 user 메서드로 사용자 정보를 가져올 수 있습니다. 반환되는 사용자 객체는 데이터베이스에 저장할 때 활용할 수 있는 다양한 속성과 메서드를 제공합니다.

사용 가능한 속성은 OAuth 공급자가 OAuth 1.0과 OAuth 2.0 중 어느 버전을 사용하는지에 따라 다릅니다.

use Laravel\Socialite\Facades\Socialite;

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

    // OAuth 2.0 공급자에서 사용 가능한 속성
    $token = $user->token;
    $refreshToken = $user->refreshToken;
    $expiresIn = $user->expiresIn;

    // OAuth 1.0 공급자에서 사용 가능한 속성
    $token = $user->token;
    $tokenSecret = $user->tokenSecret;

    // 모든 공급자에서 공통으로 사용 가능한 메서드
    $user->getId();
    $user->getNickname();
    $user->getName();
    $user->getEmail();
    $user->getAvatar();
});

토큰으로 사용자 정보 조회 (OAuth2)

이미 유효한 액세스 토큰을 보유하고 있다면, userFromToken 메서드로 사용자 정보를 직접 가져올 수 있습니다.

use Laravel\Socialite\Facades\Socialite;

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

토큰과 시크릿으로 사용자 정보 조회 (OAuth1)

OAuth 1.0의 경우, 토큰과 시크릿을 함께 가지고 있다면 userFromTokenAndSecret 메서드를 사용하세요.

use Laravel\Socialite\Facades\Socialite;

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

상태 비저장 인증 (Stateless)

쿠키 기반 세션을 사용하지 않는 Stateless API에 소셜 로그인을 추가할 때는 stateless 메서드를 사용하여 세션 상태 검증을 비활성화할 수 있습니다.

use Laravel\Socialite\Facades\Socialite;

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

WARNING

Twitter OAuth 1.0 드라이버는 Stateless 인증을 지원하지 않습니다.