Laravel 10.x パスワードリセット

イントロダクションIntroduction

ほとんどのWebアプリケーションは、ユーザーが忘れたパスワードをリセットする方法を提供します。Laravelでは、構築するすべてのアプリケーションでこれを手作業で再実装する必要はなく、パスワードリセットリンクを送信してパスワードを安全にリセットするための便利なサービスを提供しています。Most web applications provide a way for users to reset their forgotten passwords. Rather than forcing you to re-implement this by hand for every application you create, Laravel provides convenient services for sending password reset links and secure resetting passwords.

lightbulb Note: さっそく始めたいですか？Laravelアプリケーションスターターキットを新しいLaravelアプリケーションにインストールしてください。Laravelのスターターキットは、忘れたパスワードのリセットを含む、認証システム全体のスカフォールドの面倒を見ています。[!NOTE]
Want to get started fast? Install a Laravel application starter kit[/docs/{{version}}/starter-kits] in a fresh Laravel application. Laravel's starter kits will take care of scaffolding your entire authentication system, including resetting forgotten passwords.

モデルの準備Model Preparation

Laravelのパスワードリセット機能を使用する前に、アプリケーションのApp\Models\UserモデルでIlluminate\Notifications\Notifiableトレイトを使用する必要があります。通常、このトレイトは、新しいLaravelアプリケーションで作成されるデフォルトのApp\Models\Userモデルに最初から含まれています。Before using the password reset features of Laravel, your application's App\Models\User model must use the Illuminate\Notifications\Notifiable trait. Typically, this trait is already included on the default App\Models\User model that is created with new Laravel applications.

次に、App\Models\UserモデルがIlluminate\Contracts\Auth\CanResetPasswordコントラクトを実装していることを確認します。フレームワークに含まれているApp\Models\Userモデルは、最初からこのインターフェイスを実装しており、Illuminate\Auth\Passwords\CanResetPasswordトレイトを使用して、インターフェイスの実装に必要なメソッドを持っています。Next, verify that your App\Models\User model implements the Illuminate\Contracts\Auth\CanResetPassword contract. The App\Models\User model included with the framework already implements this interface, and uses the Illuminate\Auth\Passwords\CanResetPassword trait to include the methods needed to implement the interface.

データベース準備Database Preparation

アプリケーションのパスワードリセットトークンを保存するためのテーブルを作成する必要があります。このテーブルのマイグレーションはデフォルトのLaravelアプリケーションに含まれているため、データベースをマイグレーションするだけでこのテーブルを作成できます。A table must be created to store your application's password reset tokens. The migration for this table is included in the default Laravel application, so you only need to migrate your database to create this table:

php artisan migrate

信頼するホストの設定Configuring Trusted Hosts

デフォルトでは、LaravelはHTTPリクエストのhostヘッダの内容に関係なく受信したすべてのリクエストにレスポンスします。さらに、Webリクエスト中にアプリケーションへの絶対URLを生成するときに、hostヘッダの値を使用します。By default, Laravel will respond to all requests it receives regardless of the content of the HTTP request's Host header. In addition, the Host header's value will be used when generating absolute URLs to your application during a web request.

通常、NginxやApacheなどのウェブサーバは、与えられたホスト名にマッチするリクエストのみをアプリケーションに送信するように設定する必要があります。しかし、ウェブサーバを直接カスタマイズできず、Laravelに特定のホスト名にしか応答しないように指示する必要がある場合は、アプリケーションのミドルウェアであるApp\Http\Middleware\TrustHostsを有効にすることで、それが可能になります。これは、アプリケーションがパスワードリセット機能を提供している場合、特に重要です。Typically, you should configure your web server, such as Nginx or Apache, to only send requests to your application that match a given host name. However, if you do not have the ability to customize your web server directly and need to instruct Laravel to only respond to certain host names, you may do so by enabling the App\Http\Middleware\TrustHosts middleware for your application. This is particularly important when your application offers password reset functionality.

このミドルウェアについて詳しく知りたい方は、TrustHostsミドルウェアのドキュメントを参照してください。To learn more about this middleware, please consult the TrustHosts middleware documentation[/docs/{{version}}/requests#configuring-trusted-hosts].

ルートRouting

ユーザーがパスワードをリセットできるようにするためのサポートを適切に実装するには、ルートをいくつか定義する必要があります。最初に、ユーザーが自分の電子メールアドレスを介してパスワードリセットリンクをリクエストできるようにするためのルートのペアが必要になります。２つ目は、ユーザーが電子メールで送られてきたパスワードリセットリンクにアクセスしてパスワードリセットフォームに記入した後、実際にパスワードをリセットするためのルートが必要になります。To properly implement support for allowing users to reset their passwords, we will need to define several routes. First, we will need a pair of routes to handle allowing the user to request a password reset link via their email address. Second, we will need a pair of routes to handle actually resetting the password once the user visits the password reset link that is emailed to them and completes the password reset form.

パスワードリセットリンクの要求Requesting the Password Reset Link

パスワードリセットリンクリクエストフォームThe Password Reset Link Request Form

まず、パスワードリセットリンクをリクエストするために必要なルートを定義します。手始めに、パスワードリセットリンクリクエストフォームを使用してビューを返すルートを定義します。First, we will define the routes that are needed to request password reset links. To get started, we will define a route that returns a view with the password reset link request form:

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

このルートによって返されるビューには、emailフィールドを含むフォームが必要です。これにより、ユーザーは特定の電子メールアドレスのパスワードリセットリンクをリクエストできます。The view that is returned by this route should have a form containing an email field, which will allow the user to request a password reset link for a given email address.

フォーム送信処理Handling the Form Submission

次に、「パスワードを忘れた」ビューからのフォーム送信リクエストを処理するルートを定義します。このルートは、電子メールアドレスを検証し、対応するユーザーにパスワードリセットリクエストを送信する責任があります。Next, we will define a route that handles the form submission request from the "forgot password" view. This route will be responsible for validating the email address and sending the password reset request to the corresponding user:

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::RESET_LINK_SENT
                ? back()->with(['status' => __($status)])
                : back()->withErrors(['email' => __($status)]);
})->middleware('guest')->name('password.email');

先に進む前に、このルートをさらに詳しく調べてみましょう。最初に、リクエストのemail属性が検証されます。次に、Laravelの組み込みの「パスワードブローカ」(Passwordファサードが返す)を使用して、パスワードリセットリンクをユーザーに送信します。パスワードブローカは、指定するフィールド(この場合はメールアドレス)でユーザーを取得し、Laravelの組み込み通知システムを介してユーザーにパスワードリセットリンクを送信します。Before moving on, let's examine this route in more detail. First, the request's email attribute is validated. Next, we will use Laravel's built-in "password broker" (via the Password facade) to send a password reset link to the user. The password broker will take care of retrieving the user by the given field (in this case, the email address) and sending the user a password reset link via Laravel's built-in notification system[/docs/{{version}}/notifications].

sendResetLinkメソッドは、"status"スラッグを返します。このステータスは、Laravelの多言語化ヘルパを使って翻訳でき、リクエストのステータスに関するユーザーフレンドリーなメッセージをユーザーへ表示可能にします。パスワードリセットステータスの翻訳は、アプリケーションのlang/{lang}/passwords.php言語ファイルで決まります。ステータスのスラッグに指定できる各項目は、passwords言語ファイル内にあります。The sendResetLink method returns a "status" slug. This status may be translated using Laravel's localization[/docs/{{version}}/localization] helpers in order to display a user-friendly message to the user regarding the status of their request. The translation of the password reset status is determined by your application's lang/{lang}/passwords.php language file. An entry for each possible value of the status slug is located within the passwords language file.

lightbulb Note: Laravelアプリケーションのスケルトンは、デフォルトではlangディレクトリを含んでいません。Laravelの言語ファイルをカスタマイズしたい場合は、lang:publish Artisanコマンドでリソース公開できます。[!NOTE]
By default, the Laravel application skeleton does not include the lang directory. If you would like to customize Laravel's language files, you may publish them via the lang:publish Artisan command.

PasswordファサードのsendResetLinkメソッドを呼び出すときに、Laravelがアプリケーションのデータベースからユーザーレコードを取得する方法をどのように知っているのか疑問に思われるかもしれません。Laravelパスワードブローカは、認証システムの「ユーザープロバイダ」を利用してデータベースレコードを取得します。パスワードブローカが使用するユーザープロバイダは、config/auth.php設定ファイルのpasswords設定配列内で設定します。カスタムユーザープロバイダの作成の詳細については、認証ドキュメントを参照してください。You may be wondering how Laravel knows how to retrieve the user record from your application's database when calling the Password facade's sendResetLink method. The Laravel password broker utilizes your authentication system's "user providers" to retrieve database records. The user provider used by the password broker is configured within the passwords configuration array of your config/auth.php configuration file. To learn more about writing custom user providers, consult the authentication documentation[/docs/{{version}}/authentication#adding-custom-user-providers].

lightbulb Note: パスワードのリセットを手作業で実装する場合は、ビューの内容とルートを自分で定義する必要があります。必要なすべての認証および検証ロジックを含むスカフォールドが必要な場合は、Laravelアプリケーションスターターキットを確認してください。[!NOTE]
When manually implementing password resets, you are required to define the contents of the views and routes yourself. If you would like scaffolding that includes all necessary authentication and verification logic, check out the Laravel application starter kits[/docs/{{version}}/starter-kits].

パスワードのリセットResetting the Password

パスワードリセットフォームThe Password Reset Form

次に、電子メールで送信されたパスワードリセットリンクをユーザーがクリックして新しいパスワードを入力したときに、実際にパスワードをリセットするために必要なルートを定義します。まず、ユーザーがパスワードのリセットリンクをクリックしたときに表示されるパスワードのリセットフォームを表示するルートを定義しましょう。このルートは、後でパスワードリセットリクエストを確認するために使用するtokenパラメータを受け取ります。Next, we will define the routes necessary to actually reset the password once the user clicks on the password reset link that has been emailed to them and provides a new password. First, let's define the route that will display the reset password form that is displayed when the user clicks the reset password link. This route will receive a token parameter that we will use later to verify the password reset request:

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フィールドを含むフォームを表示します。これにはルートが受け取る秘密の$tokenの値が含まれている必要があります。The view that is returned by this route should display a form containing an email field, a password field, a password_confirmation field, and a hidden token field, which should contain the value of the secret $token received by our route.

フォーム送信処理Handling the Form Submission

もちろん、パスワードリセットフォームの送信を実際に処理するためルートを定義する必要もあります。このルートは、受信リクエストのバリデーションとデータベース内のユーザーのパスワードの更新を担当します。Of course, we need to define a route to actually handle the password reset form submission. This route will be responsible for validating the incoming request and updating the user's password in the database:

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::PASSWORD_RESET
                ? redirect()->route('login')->with('status', __($status))
                : back()->withErrors(['email' => [__($status)]]);
})->middleware('guest')->name('password.update');

先に進む前に、このルートをさらに詳しく調べてみましょう。最初に、リクエストのtoken、email、およびpassword属性がバリデーションされます。次に、Laravelの組み込みの「パスワードブローカ」(Passwordファサードが返す)を使用して、パスワードリセットリクエストの資格情報を検証します。Before moving on, let's examine this route in more detail. First, the request's token, email, and password attributes are validated. Next, we will use Laravel's built-in "password broker" (via the Password facade) to validate the password reset request credentials.

パスワードブローカに与えられたトークン、電子メールアドレス、およびパスワードが有効である場合、resetメソッドに渡されたクロージャが呼び出されます。ユーザーインスタンスとパスワードリセットフォームに提供された平文テキストのパスワードを受け取るこのクロージャ内で、データベース内のユーザーのパスワードを更新します。If the token, email address, and password given to the password broker are valid, the closure passed to the reset method will be invoked. Within this closure, which receives the user instance and the plain-text password provided to the password reset form, we may update the user's password in the database.

resetメソッドは、「ステータス」スラグを返します。このステータスは、リクエストのステータスに関するユーザーフレンドリーなメッセージをユーザーに表示するために、Laravelの 多言語化ヘルパを使用して翻訳できます。パスワードリセットステータスの翻訳は、アプリケーションのlang/{lang}/passwords.php言語ファイルにより行います。passwords言語ファイルの中に、ステータスのスラグがとり得る値のエントリを配置しています。アプリケーションにlang ディレクトリがない場合は、lang:publish Artisan コマンドを使用して作成できます。The reset method returns a "status" slug. This status may be translated using Laravel's localization[/docs/{{version}}/localization] helpers in order to display a user-friendly message to the user regarding the status of their request. The translation of the password reset status is determined by your application's lang/{lang}/passwords.php language file. An entry for each possible value of the status slug is located within the passwords language file. If your application does not contain a lang directory, you may create it using the lang:publish Artisan command.

先に進む前に、Passwordファサードのresetメソッドを呼び出すときに、Laravelがアプリケーションのデータベースからユーザーレコードを取得する方法をどのように知っているのか疑問に思われるかもしれません。Laravelパスワードブローカーは、認証システムの「ユーザープロバイダ」を利用してデータベースレコードを取得します。パスワードブローカが使用するユーザープロバイダは、config/auth.php設定ファイルのpasswords設定配列内で設定しています。カスタムユーザープロバイダの作成の詳細については、認証ドキュメントを参照してください。Before moving on, you may be wondering how Laravel knows how to retrieve the user record from your application's database when calling the Password facade's reset method. The Laravel password broker utilizes your authentication system's "user providers" to retrieve database records. The user provider used by the password broker is configured within the passwords configuration array of your config/auth.php configuration file. To learn more about writing custom user providers, consult the authentication documentation[/docs/{{version}}/authentication#adding-custom-user-providers].

期限切れトークンの削除Deleting Expired Tokens

期限が切れたパスワードリセットトークンは、データベース内にまだ存在します。しかし、これらのレコードは、auth:clear-resets Artisanコマンドで簡単に削除できます。Password reset tokens that have expired will still be present within your database. However, you may easily delete these records using the auth:clear-resets Artisan command:

php artisan auth:clear-resets

この処理を自動化したい場合は、アプリケーションのスケジューラへの、当コマンド追加を検討してください。If you would like to automate this process, consider adding the command to your application's scheduler[/docs/{{version}}/scheduling]:

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

カスタマイズCustomization

リセットリンクのカスタマイズReset Link Customization

ResetPassword通知クラスが提供するcreateUrlUsingメソッドを使用して、パスワードリセットリンクURLをカスタマイズできます。このメソッドは、通知を受信して​​いるユーザーインスタンスとパスワードリセットリンクトークンを受信するクロージャを受け入れます。通常、このメソッドは、App\Providers\AuthServiceProviderサービスプロバイダのbootメソッドから呼び出す必要があります。You may customize the password reset link URL using the createUrlUsing method provided by the ResetPassword notification class. This method accepts a closure which receives the user instance that is receiving the notification as well as the password reset link token. Typically, you should call this method from your App\Providers\AuthServiceProvider service provider's boot method:

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

リセットメールカスタマイズReset Email Customization

パスワードリセットリンクをユーザーに送信するために使用する通知クラスは簡単に変更できます。それには、App\Models\UserモデルのsendPasswordResetNotificationメソッドをオーバーライドします。このメソッド内で、自分で作成した通知クラスを使用して通知を送信できます。パスワードリセット$tokenは、メソッドが受け取る最初の引数です。この$tokenを使用して、パスワードリセットURLを作成し、ユーザーに通知を送信します。You may easily modify the notification class used to send the password reset link to the user. To get started, override the sendPasswordResetNotification method on your App\Models\User model. Within this method, you may send the notification using any notification class[/docs/{{version}}/notifications] of your own creation. The password reset $token is the first argument received by the method. You may use this $token to build the password reset URL of your choice and send your notification to the user:

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