비밀번호 재설정

업데이트됨

번역일: 2026년 6월 20일

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

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

비밀번호 재설정

소개
라우팅
- 비밀번호 재설정 링크 요청
- 비밀번호 재설정 처리
만료된 토큰 삭제
커스터마이징

소개

대부분의 웹 애플리케이션은 사용자가 비밀번호를 잊었을 때 재설정할 수 있는 기능을 제공합니다. Laravel은 이 기능을 매번 직접 구현하지 않아도 되도록, 비밀번호 재설정 링크 발송과 안전한 비밀번호 재설정을 위한 편리한 서비스를 기본으로 제공합니다.

NOTE

빠르게 시작하고 싶다면 새 Laravel 프로젝트에 애플리케이션 스타터 킷을 설치해 보세요. 스타터 킷은 비밀번호 재설정 기능을 포함한 전체 인증 시스템의 스캐폴딩을 자동으로 처리해 줍니다.

설정

비밀번호 재설정 관련 설정은 config/auth.php 파일에 있습니다. 이 파일에서 사용 가능한 옵션들을 확인해 두세요. 기본적으로 Laravel은 database 드라이버를 사용하도록 설정되어 있습니다.

driver 설정 옵션은 비밀번호 재설정 데이터를 어디에 저장할지를 결정합니다. Laravel은 두 가지 드라이버를 제공합니다.

database - 비밀번호 재설정 데이터를 관계형 데이터베이스에 저장합니다.
cache - 비밀번호 재설정 데이터를 캐시 스토어에 저장합니다.

드라이버 사전 요구사항

Database 드라이버

기본 database 드라이버를 사용할 경우, 비밀번호 재설정 토큰을 저장할 테이블이 필요합니다. 이 테이블은 Laravel 기본 마이그레이션 파일인 0001_01_01_000000_create_users_table.php에 이미 포함되어 있습니다.

Cache 드라이버

별도의 데이터베이스 테이블 없이 캐시를 이용해 비밀번호 재설정을 처리할 수도 있습니다. 캐시 항목은 사용자의 이메일 주소를 키로 사용하므로, 애플리케이션의 다른 부분에서 이메일 주소를 캐시 키로 사용하고 있지 않은지 확인하세요.

'passwords' => [
    'users' => [
        'driver' => 'cache',
        'provider' => 'users',
        'store' => 'passwords', // 선택사항...
        'expire' => 60,
        'throttle' => 60,
    ],
],

artisan cache:clear 명령을 실행할 때 비밀번호 재설정 데이터가 함께 삭제되는 것을 방지하려면, store 설정 키를 이용해 별도의 캐시 스토어를 지정할 수 있습니다. 이 값은 config/cache.php에 설정된 스토어 이름과 일치해야 합니다.

모델 준비

Laravel의 비밀번호 재설정 기능을 사용하기 전에, App\Models\User 모델에 Illuminate\Notifications\Notifiable 트레이트가 포함되어 있는지 확인하세요. 새로운 Laravel 프로젝트의 기본 App\Models\User 모델에는 이미 이 트레이트가 포함되어 있습니다.

또한, App\Models\User 모델이 Illuminate\Contracts\Auth\CanResetPassword 계약(contract)을 구현하고 있는지 확인하세요. 프레임워크에서 기본 제공하는 App\Models\User 모델은 이미 이 인터페이스를 구현하고 있으며, Illuminate\Auth\Passwords\CanResetPassword 트레이트를 통해 필요한 메서드를 제공합니다.

신뢰할 수 있는 호스트 설정

기본적으로 Laravel은 HTTP 요청의 Host 헤더 값에 상관없이 모든 요청에 응답합니다. 또한 웹 요청 중 애플리케이션의 절대 URL을 생성할 때도 Host 헤더 값이 사용됩니다.

일반적으로는 Nginx나 Apache 같은 웹 서버에서 특정 호스트명에 대한 요청만 애플리케이션으로 전달하도록 설정하는 것이 좋습니다. 하지만 웹 서버를 직접 수정할 수 없는 환경이라면, bootstrap/app.php 파일에서 trustHosts 미들웨어 메서드를 사용해 Laravel이 특정 호스트명에만 응답하도록 설정할 수 있습니다. 비밀번호 재설정 기능을 제공하는 애플리케이션에서는 이 설정이 특히 중요합니다.

자세한 내용은 TrustHosts 미들웨어 문서를 참고하세요.

라우팅

비밀번호 재설정 기능을 구현하려면 여러 개의 라우트를 정의해야 합니다. 크게 두 가지 흐름으로 나뉩니다.

사용자가 이메일로 비밀번호 재설정 링크를 요청하는 라우트 쌍
사용자가 이메일의 링크를 클릭한 후 실제로 비밀번호를 재설정하는 라우트 쌍

비밀번호 재설정 링크 요청

재설정 링크 요청 폼

먼저 비밀번호 재설정 링크 요청에 필요한 라우트를 정의합니다. 사용자에게 이메일 입력 폼을 보여주는 GET 라우트부터 시작합니다.

Route::get('/forgot-password', function () {
    return view('auth.forgot-password');
})->middleware('guest')->name('password.request');

이 라우트가 반환하는 뷰에는 사용자가 이메일 주소를 입력할 수 있는 email 필드가 포함된 폼이 있어야 합니다.

폼 제출 처리

다음으로, "비밀번호 찾기" 폼 제출을 처리하는 POST 라우트를 정의합니다. 이 라우트는 이메일 주소를 유효성 검사한 후, 해당 사용자에게 비밀번호 재설정 링크를 발송합니다.

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;

Route::post('/forgot-password', function (Request $request) {
    $request->validate(['email' => 'required|email']);

    $status = Password::sendResetLink(
        $request->only('email')
    );

    return $status === Password::ResetLinkSent
        ? back()->with(['status' => __($status)])
        : back()->withErrors(['email' => __($status)]);
})->middleware('guest')->name('password.email');

이 라우트의 동작을 좀 더 자세히 살펴보겠습니다. 먼저 요청의 email 필드를 유효성 검사합니다. 그런 다음 Laravel 내장 "패스워드 브로커"(Password 파사드)를 사용해 해당 사용자에게 비밀번호 재설정 링크를 발송합니다. 패스워드 브로커는 지정된 필드(여기서는 이메일 주소)로 사용자를 조회한 뒤, Laravel의 내장 알림 시스템을 통해 재설정 링크를 이메일로 보냅니다.

sendResetLink 메서드는 처리 결과를 나타내는 "상태 슬러그(status slug)"를 반환합니다. 이 상태값은 Laravel의 다국어 지원 헬퍼를 통해 사용자에게 친숙한 메시지로 번역할 수 있습니다. 번역은 lang/{lang}/passwords.php 언어 파일에 정의되어 있으며, 가능한 모든 상태값에 대한 항목이 포함되어 있습니다.

NOTE

기본 Laravel 애플리케이션 스켈레톤에는 lang 디렉터리가 포함되어 있지 않습니다. Laravel의 언어 파일을 커스터마이징하려면 lang:publish Artisan 명령으로 먼저 게시(publish)하세요.

Password 파사드의 sendResetLink 메서드가 어떻게 데이터베이스에서 사용자를 조회하는지 궁금할 수 있습니다. 패스워드 브로커는 인증 시스템의 "사용자 프로바이더(user provider)"를 활용해 데이터베이스 레코드를 조회합니다. 사용할 사용자 프로바이더는 config/auth.php의 passwords 설정 배열에서 지정합니다. 커스텀 사용자 프로바이더 작성에 대한 자세한 내용은 인증 문서를 참고하세요.

NOTE

비밀번호 재설정을 직접 구현하는 경우, 뷰와 라우트의 내용을 직접 작성해야 합니다. 인증 및 검증 로직을 포함한 전체 스캐폴딩이 필요하다면 Laravel 애플리케이션 스타터 킷을 활용하세요.

비밀번호 재설정 처리

비밀번호 재설정 폼

이제 사용자가 이메일의 재설정 링크를 클릭했을 때 실제로 비밀번호를 변경하는 라우트를 정의합니다. 먼저 재설정 폼을 표시하는 GET 라우트를 정의합니다. 이 라우트는 나중에 요청 검증에 사용할 token 파라미터를 URL로 받습니다.

Route::get('/reset-password/{token}', function (string $token) {
    return view('auth.reset-password', ['token' => $token]);
})->middleware('guest')->name('password.reset');

이 라우트가 반환하는 뷰에는 email 필드, password 필드, password_confirmation 필드, 그리고 라우트에서 받은 $token 값을 담은 숨김(hidden) token 필드가 포함된 폼이 있어야 합니다.

폼 제출 처리

실제 비밀번호 재설정 폼 제출을 처리하는 라우트도 정의해야 합니다. 이 라우트는 들어오는 요청을 유효성 검사하고, 데이터베이스의 사용자 비밀번호를 업데이트합니다.

use App\Models\User;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;

Route::post('/reset-password', function (Request $request) {
    $request->validate([
        'token' => 'required',
        'email' => 'required|email',
        'password' => 'required|min:8|confirmed',
    ]);

    $status = Password::reset(
        $request->only('email', 'password', 'password_confirmation', 'token'),
        function (User $user, string $password) {
            $user->forceFill([
                'password' => Hash::make($password)
            ])->setRememberToken(Str::random(60));

            $user->save();

            event(new PasswordReset($user));
        }
    );

    return $status === Password::PasswordReset
        ? redirect()->route('login')->with('status', __($status))
        : back()->withErrors(['email' => [__($status)]]);
})->middleware('guest')->name('password.update');

이 라우트의 동작을 단계별로 살펴보겠습니다.

token, email, password 필드를 유효성 검사합니다.
Password 파사드(패스워드 브로커)를 사용해 재설정 요청의 자격 증명을 검증합니다.
토큰, 이메일, 비밀번호가 모두 유효하면 reset 메서드에 전달된 클로저가 실행됩니다.
클로저 안에서 사용자 인스턴스와 평문 비밀번호를 받아, 데이터베이스의 비밀번호를 업데이트합니다.

reset 메서드도 처리 결과를 나타내는 "상태 슬러그"를 반환하며, Laravel의 다국어 지원 헬퍼로 사용자 친화적인 메시지로 번역할 수 있습니다. 번역은 lang/{lang}/passwords.php 언어 파일에 정의됩니다. lang 디렉터리가 없다면 lang:publish Artisan 명령으로 생성하세요.

Password 파사드의 reset 메서드 역시 config/auth.php의 passwords 설정 배열에서 지정한 사용자 프로바이더를 통해 데이터베이스 레코드를 조회합니다. 커스텀 사용자 프로바이더에 대한 내용은 인증 문서를 참고하세요.

만료된 토큰 삭제

database 드라이버를 사용하는 경우, 만료된 비밀번호 재설정 토큰이 데이터베이스에 계속 남아 있을 수 있습니다. auth:clear-resets Artisan 명령으로 이러한 레코드를 손쉽게 삭제할 수 있습니다.

php artisan auth:clear-resets

이 과정을 자동화하려면 애플리케이션의 스케줄러에 해당 명령을 등록하는 것을 권장합니다.

use Illuminate\Support\Facades\Schedule;

Schedule::command('auth:clear-resets')->everyFifteenMinutes();

커스터마이징

재설정 링크 URL 커스터마이징

ResetPassword 알림 클래스의 createUrlUsing 메서드를 사용하면 비밀번호 재설정 링크 URL을 직접 정의할 수 있습니다. 이 메서드는 알림을 받는 사용자 인스턴스와 재설정 토큰을 인자로 받는 클로저를 인수로 받습니다. 보통 AppServiceProvider의 boot 메서드에서 호출합니다.

use App\Models\User;
use Illuminate\Auth\Notifications\ResetPassword;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    ResetPassword::createUrlUsing(function (User $user, string $token) {
        return 'https://example.com/reset-password?token='.$token;
    });
}

재설정 이메일 커스터마이징

비밀번호 재설정 링크를 발송하는 데 사용하는 알림 클래스를 직접 교체할 수도 있습니다. App\Models\User 모델에서 sendPasswordResetNotification 메서드를 오버라이드하면 됩니다. 이 메서드 안에서 직접 만든 알림 클래스를 사용해 알림을 발송할 수 있습니다. 비밀번호 재설정 $token은 메서드의 첫 번째 인수로 전달됩니다. 이 토큰을 사용해 원하는 재설정 URL을 구성하고 사용자에게 알림을 보내세요.

use App\Notifications\ResetPasswordNotification;

/**
 * 사용자에게 비밀번호 재설정 알림을 발송합니다.
 *
 * @param  string  $token
 */
public function sendPasswordResetNotification($token): void
{
    $url = 'https://example.com/reset-password?token='.$token;

    $this->notify(new ResetPasswordNotification($url));
}