メインコンテンツへスキップ
パッケージがユーザーをLaravelの標準的なEloquentモデルやデータベース以外から取得する場合は、独自の UserProvider を登録します。たとえば外部ディレクトリ、既存の会員システム、専用のAPIなどを認証の保存先にできます。 これはガードを新しく作る拡張とは異なります。既存の session や token ガードに、ユーザーを検索・検証する実装だけを提供します。ガード自体の認証方式を変更する場合は、カスタム認証ガードの実装を参照してください。
このページはLaravel 13を対象に、公式ドキュメントの 13.x ブランチとFramework v13.43.0 の実装を参照しています。パッケージが対応するLaravelの各バージョンで、契約のメソッドとパスワード再ハッシュの動作を確認してください。

ガードとUserProviderの責務を分ける

Auth::guard() が返すガードは、セッションやリクエストから認証状態を取り出します。ガードがユーザーを取得するとき、設定されたプロバイダーへ処理を委譲します。 UserProvider が返す値は、保存先の配列やSDKのレスポンスではなく、Illuminate\Contracts\Auth\Authenticatable を実装したオブジェクトでなければなりません。

Auth::provider をパッケージから登録する

サービスプロバイダーの boot で登録する

Laravelは Auth::provider($name, $callback) に登録したコールバックを、auth.providers.*.driver の値に応じて呼び出します。コールバックにはアプリケーションとプロバイダー設定が渡されます。 パッケージのサービスプロバイダーでは、認証サービスが利用される前に登録します。
DirectoryClientManager と DirectoryUserProvider はパッケージがコンテナへ登録するクラスです。$config は利用アプリケーションの auth.php から渡されるため、接続名やテナントなど、プロバイダーの生成に必要な値をそこから読み取れます。 Auth::provider は認証ユーザープロバイダーの名前を登録します。Auth::extend が登録するカスタムガードのドライバーとは別の拡張点です。両方を使う場合でも、ガードの責務とユーザー保存先の責務を別クラスに保ちます。

auth.php でプロバイダーとガードを接続する

登録した名前を auth.providers の driver に指定し、そのプロバイダーをガードから参照します。
この設定の対応関係は次のとおりです。
  1. directory-web ガードが directory-users プロバイダーを参照する。
  2. directory-users の driver が directory なので、先ほどのコールバックが選ばれる。
  3. SessionGuard が生成され、生成された UserProvider を使ってユーザーを取得する。
AuthManager はガードを最初の解決時にキャッシュします。プロバイダー登録後にすでに解決済みのガードを置き換えるAPIではないため、サービスプロバイダーの起動順と、テストでの Auth::forgetGuards() の利用を意識します。auth 設定をキャッシュして利用する場合も、接続情報を環境変数から直接読むのではなく、設定へ解決してからコールバックへ渡してください。

UserProvider の契約を実装する

Laravel 13の Illuminate\Contracts\Auth\UserProvider は、次の6メソッドを要求します。
取得系の3メソッドはユーザーまたは null を返し、見つからないユーザーを例外で表すものではありません。保存先のタイムアウトや通信障害を null に変換するか、再試行可能な例外として扱うかはパッケージの契約として決めます。認証失敗と保存先障害を同じ「資格情報が不正」として隠さないことが重要です。

Authenticatable を返す

外部保存先のレコードを、そのまま返さずに GenericUser へ変換する最小例です。実際のパッケージでは、利用者が追加属性へ型付きでアクセスできる専用のユーザークラスを用意しても構いません。
GenericUser は id、password、remember_token という属性名を既定値として使います。別の名前を使う場合は、Authenticatable を実装する専用クラスで getAuthIdentifierName() などを上書きします。

IDとremember tokenで取得する

retrieveById はセッションへ保存された認証IDからユーザーを復元します。remember tokenによるログインをサポートする場合は、識別子とトークンを保存先で照合します。
hash_equals の引数を保存先から取得した文字列とトークンに限定し、トークンをログへ出力しないようにします。外部保存先がremember tokenに対応しない場合は、updateRememberToken を空実装にして成功したように見せるのではなく、パッケージの認証設定でremember機能を使えないことを明示してください。

資格情報の検索とパスワード検証を分離する

retrieveByCredentials ではパスワードを検証しない

Auth::attempt() は、まず retrieveByCredentials でユーザーを探し、その後 validateCredentials でパスワードを検証します。検索メソッドでパスワード比較まで行うと、ガードが想定する処理順序やパスワード再ハッシュを壊します。
password だけでなく password_confirmation などのキーも保存先の検索条件から除外します。パスワードやアクセストークンを、検索APIのクエリ・ログ・キャッシュキーへ含めないようにしてください。検索条件として受け付けるキーを email などの許可リストで制限する設計も、外部APIへ任意のフィールドを渡さないために有効です。

validateCredentials でHashを比較する

検証にはアプリケーションの Hasher を使い、平文パスワードを保存先へ送信したりログへ出力したりしません。
$credentials['password'] がない場合や、ユーザーがパスワードを持たない場合は false を返します。外部の認証APIへ検証を委譲する設計では、同じ契約を守りつつ、失敗・タイムアウト・レート制限をパッケージの例外方針に従って扱います。

パスワード再ハッシュを維持する

Laravelはログイン成功後、設定されたハッシュ方式に対して再ハッシュが必要かを確認できます。カスタムプロバイダーは rehashPasswordIfRequired を実装し、必要なときだけ保存先のハッシュを更新します。
外部保存先へ更新を行うため、再ハッシュの失敗を無視しないでください。更新後に返すユーザーオブジェクトのパスワード属性が古いままでも、次の認証で再ハッシュが繰り返される可能性があります。利用する Hasher と保存先のパスワード形式が一致することも、パッケージの要件として明記します。

サービスプロバイダーと認証フローをテストする

パッケージのテストでは、保存先クライアントをfakeに差し替え、UserProvider の各責務を個別に検証します。特に次の3点を分けて確認します。
  • retrieveByCredentials がパスワードをクライアントへ渡さない。
  • 正しいハッシュだけが validateCredentials を通過する。
  • 再ハッシュが必要な場合だけ更新APIを呼び出す。
上の expects は、利用するmockライブラリのAPIに合わせて置き換えてください。実際のHTTPクライアントを使う場合は、HTTP fakeで送信内容を確認し、平文パスワードがリクエストやログへ現れないことをテストします。 Auth::provider の登録を含めた統合テストでは、Testbenchなどで次の順序を検証します。
  1. パッケージのサービスプロバイダーを読み込む。
  2. auth.providers にカスタム driver を設定する。
  3. auth.guards からそのプロバイダーを参照する。
  4. ガードを初めて解決し、ユーザー取得がfakeクライアントへ委譲されることを確認する。
  5. 設定や登録を変更するテストでは、次のケースへ進む前に Auth::forgetGuards() を呼ぶ。

更新時の互換性を設計する

UserProvider は認証の境界にあるため、パッケージの更新では次を確認します。
  • Authenticatable のID・パスワード・remember tokenの属性名を変える場合、既存セッションとremember cookieの扱いを決める。
  • 外部保存先のID形式やパスワードハッシュ方式を変える場合、旧ユーザーを復元してログインできるか確認する。
  • retrieveByCredentials の許可キーを狭める場合、利用者が Auth::attempt へ渡していた条件との互換性を確認する。
  • 保存先の障害を認証失敗と区別し、ログイン画面へ誤ったパスワードを再入力させない方針を決める。
  • providerの名前、auth.php の設定キー、接続設定を削除する前に、設定キャッシュとデプロイ手順を確認する。
パッケージは「どの保存先から何をユーザーとして返すか」と「パスワードをどのハッシュで管理するか」を公開契約として扱い、認証情報の取り扱いをアプリケーション任せにしすぎないようにします。

関連ページ

カスタム認証ガード

ガード自体を拡張し、セッションやAPIトークンからユーザーを解決する方法を確認します。

サービスプロバイダー

パッケージのサービスプロバイダーを登録し、起動時に拡張を適用する基本を確認します。

参照した一次情報

最終更新日 2026年11月17日