인증
번역일: 2026년 6월 25일
인증
소개
대부분의 웹 애플리케이션은 사용자가 로그인할 수 있는 인증 기능을 제공합니다. 이 기능을 직접 구현하는 것은 복잡하고 보안 위험을 동반할 수 있습니다. 그래서 Laravel은 인증을 빠르고 안전하며 간편하게 구현할 수 있는 도구를 제공합니다.
Laravel 인증의 핵심은 가드(Guard) 와 프로바이더(Provider) 로 구성됩니다. 가드는 각 요청에서 사용자를 어떻게 인증할지 정의합니다. 예를 들어 기본으로 포함된 session 가드는 세션 스토리지와 쿠키를 사용해 인증 상태를 유지합니다.
프로바이더는 영구 저장소에서 사용자를 어떻게 불러올지 정의합니다. Laravel은 기본적으로 Eloquent와 쿼리 빌더를 이용한 두 가지 프로바이더를 지원합니다. 필요에 따라 추가 프로바이더를 직접 정의할 수도 있습니다.
인증 설정 파일은 config/auth.php에 있습니다. 이 파일에는 인증 동작을 세밀하게 조정할 수 있는 다양한 옵션이 잘 설명되어 있습니다.
NOTE
가드와 프로바이더는 "역할(role)"이나 "권한(permission)"과 다른 개념입니다. 권한을 통한 사용자 행위 제어는 인가(authorization) 문서를 참고하세요.
스타터 킷
빠르게 시작하고 싶다면 새 Laravel 프로젝트에 애플리케이션 스타터 킷을 설치하세요. 데이터베이스 마이그레이션 후 /register 또는 인증 관련 URL에 접근하면 스타터 킷이 전체 인증 시스템을 자동으로 구성해줍니다.
최종 프로젝트에 스타터 킷을 사용하지 않더라도, Laravel Breeze를 설치해보는 것은 Laravel 인증 기능의 실제 구현 방식을 익히기에 매우 좋은 방법입니다. Breeze가 생성하는 컨트롤러, 라우트, 뷰 코드를 살펴보면 인증 기능이 어떻게 구현되는지 명확히 이해할 수 있습니다.
데이터베이스 고려사항
Laravel은 기본적으로 app/Models 디렉터리에 App\Models\User Eloquent 모델을 포함합니다. 이 모델은 기본 Eloquent 인증 드라이버와 함께 사용됩니다. Eloquent를 사용하지 않는 경우에는 Laravel 쿼리 빌더를 사용하는 database 인증 프로바이더를 활용할 수 있습니다.
App\Models\User 모델의 데이터베이스 스키마를 구성할 때, password 컬럼은 최소 60자 이상이어야 합니다. 새 Laravel 애플리케이션에 포함된 기본 users 테이블 마이그레이션은 이미 이 길이를 초과하는 컬럼을 생성합니다.
또한 users 테이블(또는 동등한 테이블)에 100자의 nullable 문자열 컬럼 remember_token이 있는지 확인하세요. 이 컬럼은 "로그인 상태 유지" 옵션을 선택한 사용자의 토큰을 저장하는 데 사용됩니다. 마찬가지로 기본 마이그레이션에 이미 해당 컬럼이 포함되어 있습니다.
에코시스템 개요
Laravel은 인증과 관련된 여러 패키지를 제공합니다. 본격적으로 시작하기 전에, Laravel 인증 에코시스템 전체를 조망하고 각 패키지의 용도를 살펴보겠습니다.
브라우저 기반 인증의 동작 원리
웹 브라우저를 통한 인증의 흐름은 다음과 같습니다. 사용자가 로그인 폼에 이메일과 비밀번호를 입력합니다. 자격증명이 올바르면 애플리케이션은 인증된 사용자 정보를 세션에 저장합니다. 브라우저에는 세션 ID가 담긴 쿠키가 발급되며, 이후 요청에서 이 쿠키를 통해 올바른 세션을 찾아 사용자를 "인증된 상태"로 인식합니다.
API 인증
원격 서비스나 API 클라이언트는 웹 브라우저를 사용하지 않으므로 쿠키 기반 인증이 적합하지 않습니다. 대신 매 요청마다 API 토큰을 전송하고, 애플리케이션이 이 토큰을 유효한 토큰 목록과 대조하여 인증합니다.
Laravel 내장 브라우저 인증 서비스
Laravel은 Auth와 Session 파사드를 통해 접근하는 내장 인증 및 세션 서비스를 제공합니다. 이 서비스들은 웹 브라우저에서 시작된 요청에 대해 쿠키 기반 인증을 제공하며, 자격증명 검증, 사용자 인증, 세션 데이터 저장, 세션 쿠키 발급을 모두 처리합니다.
애플리케이션 스타터 킷
이러한 인증 서비스를 수동으로 구현할 수도 있지만, 더 빠르게 시작할 수 있도록 전체 인증 레이어를 스캐폴딩해주는 무료 패키지가 제공됩니다.
_Laravel Breeze_는 로그인, 회원가입, 비밀번호 재설정, 이메일 인증, 비밀번호 확인 등 모든 인증 기능을 간단하게 구현한 스타터 킷입니다. Blade 템플릿과 Tailwind CSS로 구성된 뷰 레이어를 제공하며, Livewire나 Inertia(Vue 또는 React) 기반 스캐폴딩 옵션도 선택할 수 있습니다.
_Laravel Fortify_는 Laravel을 위한 헤드리스(headless) 인증 백엔드입니다. 쿠키 기반 인증 외에도 2단계 인증, 이메일 인증 등의 기능을 구현합니다. Fortify 자체에는 UI가 없으며, Laravel Jetstream의 인증 백엔드로 사용되거나 Laravel Sanctum과 결합하여 SPA 인증 백엔드로 독립적으로 사용할 수 있습니다.
_Laravel Jetstream_은 Fortify의 인증 서비스를 바탕으로 Tailwind CSS, Livewire, Inertia를 활용한 아름답고 모던한 UI를 제공하는 강력한 스타터 킷입니다. 2단계 인증, 팀 관리, 브라우저 세션 관리, 프로필 관리, Laravel Sanctum 연동을 통한 API 토큰 인증 등을 지원합니다.
Laravel API 인증 서비스
API 토큰 관리 및 인증을 위해 Passport와 Sanctum 두 가지 패키지를 선택적으로 사용할 수 있습니다. 이 패키지들은 내장 쿠키 기반 인증과 상호 배타적이지 않으며, 함께 사용할 수 있습니다.
Passport
Passport는 OAuth2 인증 프로바이더로, 다양한 OAuth2 "그랜트 타입"을 통해 여러 종류의 토큰을 발급할 수 있습니다. 강력하고 풍부한 기능을 갖추고 있지만, 대부분의 애플리케이션에는 OAuth2의 복잡한 기능이 필요하지 않습니다. 또한 OAuth2를 이용한 SPA나 모바일 앱 인증 구현이 개발자들에게 혼란을 주는 경우도 많았습니다.
Sanctum
OAuth2의 복잡성에 대한 해결책으로 만들어진 Laravel Sanctum은 웹 브라우저의 퍼스트파티 요청과 API 토큰 기반 요청을 모두 처리할 수 있는 단순하고 통합된 인증 패키지입니다.
Sanctum 기반 애플리케이션에 요청이 들어오면, Sanctum은 먼저 세션 쿠키가 포함되어 있는지 확인합니다. 세션 쿠키가 없으면 API 토큰을 검사하고 토큰이 있으면 해당 토큰으로 인증합니다. 이 과정에 대한 자세한 내용은 Sanctum의 "동작 원리" 문서를 참고하세요.
Laravel Sanctum은 Laravel Jetstream에 기본 포함된 API 패키지로, 대부분의 웹 애플리케이션 인증 요구사항에 가장 적합한 솔루션입니다.
정리 및 스택 선택 가이드
상황에 따른 스택 선택을 정리하면 다음과 같습니다.
- 브라우저를 통한 모놀리식 Laravel 앱: Laravel 내장 인증 서비스 사용
- 서드파티가 소비하는 API 제공: Passport 또는 Sanctum 사용. 일반적으로 Sanctum이 권장됨 (SPA, 모바일, "스코프/어빌리티" 지원 포함)
- Laravel 백엔드 기반 SPA: Laravel Sanctum 사용. 인증 라우트를 직접 구현하거나 Laravel Fortify를 헤드리스 백엔드로 활용
- OAuth2 전체 스펙이 반드시 필요한 경우: Passport 사용
- 빠르게 시작하고 싶은 경우: Laravel Breeze 권장
인증 빠른 시작
WARNING
이 섹션은 Laravel 애플리케이션 스타터 킷을 사용한 인증을 설명합니다. 스타터 킷 없이 Laravel 인증 시스템과 직접 연동하려면 수동으로 사용자 인증하기 섹션을 참고하세요.
스타터 킷 설치
먼저 Laravel 애플리케이션 스타터 킷을 설치하세요. Laravel Breeze와 Laravel Jetstream 모두 새 Laravel 애플리케이션에 인증을 통합하기 위한 멋진 출발점을 제공합니다.
Laravel Breeze는 로그인, 회원가입, 비밀번호 재설정, 이메일 인증, 비밀번호 확인 등 모든 인증 기능을 간단하게 구현합니다. Blade 템플릿과 Tailwind CSS로 뷰가 구성되며, Livewire 또는 Inertia(Vue/React) 기반 스캐폴딩을 선택할 수 있습니다.
Laravel Jetstream은 더 강력한 스타터 킷으로 Livewire 또는 Inertia + Vue를 선택할 수 있습니다. 2단계 인증, 팀 관리, 프로필 관리, 브라우저 세션 관리, Laravel Sanctum 연동, 계정 삭제 기능도 선택적으로 제공합니다.
인증된 사용자 조회
스타터 킷을 설치하고 사용자가 등록 및 로그인할 수 있게 된 후에는, 현재 인증된 사용자와 상호작용해야 하는 경우가 자주 있습니다. 요청을 처리하는 중에 Auth 파사드의 user 메서드로 현재 인증된 사용자에 접근할 수 있습니다.
use Illuminate\Support\Facades\Auth;
// 현재 인증된 사용자 가져오기
$user = Auth::user();
// 현재 인증된 사용자의 ID 가져오기
$id = Auth::id();또는 Illuminate\Http\Request 인스턴스를 통해 인증된 사용자에 접근할 수 있습니다. 타입힌트된 클래스는 컨트롤러 메서드에 자동으로 주입되므로, Request 객체를 타입힌트하면 애플리케이션 어디서든 편리하게 인증된 사용자를 가져올 수 있습니다.
<?php
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class FlightController extends Controller
{
/**
* 기존 항공편 정보를 업데이트합니다.
*/
public function update(Request $request): RedirectResponse
{
$user = $request->user();
// ...
return redirect('/flights');
}
}현재 사용자의 인증 여부 확인
현재 HTTP 요청을 보낸 사용자가 인증되었는지 확인하려면 Auth 파사드의 check 메서드를 사용합니다. 인증된 경우 true를 반환합니다.
use Illuminate\Support\Facades\Auth;
if (Auth::check()) {
// 사용자가 로그인 상태입니다...
}NOTE
check 메서드로 인증 여부를 확인할 수 있지만, 일반적으로는 미들웨어를 사용해 특정 라우트나 컨트롤러에 접근하기 전에 인증 여부를 검사합니다. 자세한 내용은 라우트 보호 문서를 참고하세요.
라우트 보호
라우트 미들웨어를 사용하면 인증된 사용자만 특정 라우트에 접근할 수 있도록 제한할 수 있습니다. Laravel은 Illuminate\Auth\Middleware\Authenticate 클래스를 참조하는 auth 미들웨어를 기본 제공하므로, 라우트에 미들웨어만 연결하면 됩니다.
Route::get('/flights', function () {
// 인증된 사용자만 접근 가능합니다...
})->middleware('auth');미인증 사용자 리디렉션
auth 미들웨어가 미인증 사용자를 감지하면 login 이름 있는 라우트로 리디렉션합니다. 이 동작은 app/Http/Middleware/Authenticate.php 파일의 redirectTo 함수를 수정하여 변경할 수 있습니다.
use Illuminate\Http\Request;
/**
* 사용자를 리디렉션할 경로를 반환합니다.
*/
protected function redirectTo(Request $request): string
{
return route('login');
}가드 지정
auth 미들웨어를 라우트에 연결할 때 어떤 가드를 사용할지 지정할 수 있습니다. 지정하는 가드 이름은 auth.php 설정 파일의 guards 배열에 있는 키 중 하나여야 합니다.
Route::get('/flights', function () {
// 인증된 사용자만 접근 가능합니다...
})->middleware('auth:admin');로그인 횟수 제한
Laravel Breeze 또는 Laravel Jetstream 스타터 킷을 사용하는 경우, 로그인 시도에 대한 속도 제한이 자동으로 적용됩니다. 기본적으로 여러 번 잘못된 자격증명을 입력하면 1분 동안 로그인이 차단됩니다. 이 제한은 사용자의 이메일/사용자명과 IP 주소를 기준으로 적용됩니다.
NOTE
애플리케이션의 다른 라우트에도 속도 제한을 적용하려면 속도 제한 문서를 참고하세요.
수동으로 사용자 인증하기
Laravel 스타터 킷의 인증 스캐폴딩을 반드시 사용해야 하는 것은 아닙니다. 스캐폴딩 없이 구현하려면 Laravel 인증 클래스를 직접 사용하면 됩니다.
Auth 파사드를 통해 인증 서비스에 접근합니다. 로그인 폼의 인증 처리에는 주로 attempt 메서드를 사용합니다. 인증에 성공하면 세션 고정 공격을 방지하기 위해 세션을 재생성해야 합니다.
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;
class LoginController extends Controller
{
/**
* 인증 시도를 처리합니다.
*/
public function authenticate(Request $request): RedirectResponse
{
$credentials = $request->validate([
'email' => ['required', 'email'],
'password' => ['required'],
]);
if (Auth::attempt($credentials)) {
$request->session()->regenerate();
return redirect()->intended('dashboard');
}
return back()->withErrors([
'email' => '입력하신 자격증명이 일치하는 계정을 찾을 수 없습니다.',
])->onlyInput('email');
}
}attempt 메서드는 키/값 쌍의 배열을 첫 번째 인자로 받습니다. 배열의 값은 데이터베이스에서 사용자를 찾는 데 사용됩니다. 위 예시에서는 email 컬럼으로 사용자를 조회합니다. 사용자를 찾으면 데이터베이스에 저장된 해시된 비밀번호와 배열로 전달된 password 값을 비교합니다. 요청의 password 값을 직접 해시할 필요가 없습니다 — 프레임워크가 데이터베이스의 해시 비밀번호와 비교하기 전에 자동으로 해시 처리합니다. 두 해시 비밀번호가 일치하면 인증된 세션이 시작됩니다.
intended 메서드는 인증 미들웨어에 의해 가로채이기 전에 사용자가 접근하려 했던 URL로 리디렉션합니다. 의도한 목적지를 사용할 수 없는 경우를 위해 폴백 URI를 지정할 수 있습니다.
추가 조건 지정
이메일과 비밀번호 외에 추가적인 쿼리 조건을 인증 쿼리에 포함할 수 있습니다. 예를 들어 사용자가 "활성(active)" 상태인지 확인할 수 있습니다.
if (Auth::attempt(['email' => $email, 'password' => $password, 'active' => 1])) {
// 인증 성공...
}복잡한 쿼리 조건이 필요하다면 자격증명 배열에 클로저를 포함할 수 있습니다. 이 클로저는 쿼리 인스턴스와 함께 호출되어 쿼리를 커스터마이징할 수 있습니다.
use Illuminate\Database\Eloquent\Builder;
if (Auth::attempt([
'email' => $email,
'password' => $password,
fn (Builder $query) => $query->has('activeSubscription'),
])) {
// 인증 성공...
}WARNING
위 예시에서 email은 필수 옵션이 아닌 예시용 컬럼입니다. 데이터베이스 테이블에서 "사용자명"에 해당하는 컬럼 이름을 사용하세요.
attemptWhen 메서드는 두 번째 인자로 클로저를 받아, 실제 인증 전에 잠재적 사용자를 더 세밀하게 검사할 수 있습니다. 클로저는 잠재적 사용자를 받아 인증 가능 여부를 나타내는 true 또는 false를 반환해야 합니다.
if (Auth::attemptWhen([
'email' => $email,
'password' => $password,
], function (User $user) {
return $user->isNotBanned();
})) {
// 인증 성공...
}특정 가드 인스턴스 접근
Auth 파사드의 guard 메서드를 통해 사용자를 인증할 때 어떤 가드 인스턴스를 사용할지 지정할 수 있습니다. 이를 통해 서로 다른 Authenticatable 모델이나 사용자 테이블을 사용하는 애플리케이션의 각 파트에 대한 인증을 분리하여 관리할 수