Laravel Socialite

업데이트됨

번역일: 2026년 8월 19일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 8월 19일
번역 갱신: 2026년 8월 19일

Laravel Socialite

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

소개

Laravel은 폼 기반의 일반 인증 외에도, Laravel Socialite를 통해 OAuth 제공업체를 이용한 소셜 로그인을 간편하게 구현할 수 있습니다. Socialite는 현재 Facebook, X(구 Twitter), LinkedIn, Google, GitHub, GitLab, Bitbucket, Slack 인증을 지원합니다.

NOTE

이 외의 플랫폼에 대한 어댑터는 커뮤니티 기반의 Socialite Providers 사이트에서 확인할 수 있습니다. 카카오, 네이버 등 국내 소셜 로그인도 해당 사이트를 통해 지원됩니다.

설치

Composer를 사용해 프로젝트에 Socialite 패키지를 추가합니다.

composer require laravel/socialite

Socialite 업그레이드

Socialite의 새로운 메이저 버전으로 업그레이드할 때는 반드시 업그레이드 가이드를 꼼꼼히 확인하세요.

설정

Socialite를 사용하기 전에, 사용할 OAuth 제공업체의 인증 정보를 등록해야 합니다. 이 정보는 각 서비스의 개발자 콘솔(예: GitHub Developer Settings, Google Cloud Console 등)에서 "앱 등록" 또는 "OAuth 앱 생성"을 통해 발급받을 수 있습니다.

발급받은 클라이언트 ID와 시크릿은 config/services.php 파일에 등록합니다. 키 이름은 사용하는 제공업체에 따라 facebook, x, linkedin-openid, google, github, gitlab, bitbucket, slack, slack-openid 중 하나를 사용합니다.

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

NOTE

redirect 값에 상대 경로를 입력하면 자동으로 절대 URL로 변환됩니다.

인증

라우팅

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

use Laravel\Socialite\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 메서드는 콜백 요청에서 사용자 정보를 가져옵니다.

인증 및 저장

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

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\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 메서드를 사용해 인증 요청에 포함할 권한 범위(스코프)를 지정할 수 있습니다. 이 메서드는 기존에 지정된 스코프에 새 스코프를 병합합니다.

use Laravel\Socialite\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 토큰을 생성하려면 리디렉션 전에 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\Socialite;

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

WARNING

with 메서드를 사용할 때 state나 response_type 같은 예약된 키워드는 전달하지 않도록 주의하세요.

사용자 정보 조회

사용자가 콜백 라우트로 돌아오면 Socialite의 user 메서드로 사용자 정보를 조회할 수 있습니다. 반환된 사용자 객체는 데이터베이스에 저장할 때 유용한 다양한 프로퍼티와 메서드를 제공합니다.

사용 가능한 프로퍼티와 메서드는 OAuth 제공업체가 OAuth 1.0을 사용하는지, OAuth 2.0을 사용하는지에 따라 다를 수 있습니다.

use Laravel\Socialite\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();
});

토큰으로 사용자 정보 조회

이미 유효한 액세스 토큰을 보유하고 있다면, userFromToken 메서드로 해당 사용자의 정보를 직접 조회할 수 있습니다.

use Laravel\Socialite\Socialite;

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

iOS 앱에서 Facebook Limited Login을 사용하는 경우, Facebook은 액세스 토큰 대신 OIDC 토큰을 반환합니다. 이 경우 로그인 시 사용했던 nonce를 userFromToken 메서드에 함께 전달해야 합니다.

$user = Socialite::driver('facebook')->userFromToken($token, $nonce);

상태 비저장(Stateless) 인증

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

use Laravel\Socialite\Socialite;

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

테스트

Laravel Socialite는 실제 OAuth 제공업체에 요청하지 않고도 소셜 인증 흐름을 테스트할 수 있는 편리한 방법을 제공합니다. fake 메서드를 사용하면 OAuth 제공업체의 동작을 모킹하고 반환할 사용자 데이터를 직접 정의할 수 있습니다.

리디렉션 페이크

리디렉션 라우트가 올바르게 동작하는지 테스트하려면 요청 전에 fake 메서드를 호출하세요. 이렇게 하면 Socialite가 실제 OAuth 제공업체 대신 가짜 인증 URL로 리디렉션합니다.

use Laravel\Socialite\Socialite;

test('user is redirected to github', function () {
    Socialite::fake('github');

    $response = $this->get('/auth/github/redirect');

    $response->assertRedirect();
});

콜백 페이크

콜백 라우트를 테스트하려면 fake 메서드에 반환할 User 인스턴스를 함께 전달하세요. User 인스턴스는 fake 메서드로 생성할 수 있습니다.

use Laravel\Socialite\Socialite;
use Laravel\Socialite\Two\User;

test('user can login with github', function () {
    Socialite::fake('github', User::fake([
        'id' => 'github-123',
        'name' => '홍길동',
        'email' => 'hong@example.com',
    ]));

    $response = $this->get('/auth/github/callback');

    $response->assertRedirect('/dashboard');

    $this->assertDatabaseHas('users', [
        'name' => '홍길동',
        'email' => 'hong@example.com',
        'github_id' => 'github-123',
    ]);
});

기본적으로 User 인스턴스에는 가짜 OAuth 토큰 값이 포함됩니다. 필요한 경우 fake 메서드에 추가 속성을 전달해 덮어쓸 수 있습니다.

$fakeUser = User::fake([
    'id' => 'github-123',
    'name' => '홍길동',
    'email' => 'hong@example.com',
    'token' => 'fake-token',
    'refreshToken' => 'fake-refresh-token',
    'expiresIn' => 3600,
    'approvedScopes' => ['read', 'write'],
]);

OAuth 1.0 제공업체의 사용자는 Laravel\Socialite\One\User 클래스를 사용해 페이크 처리할 수 있습니다.