> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# パッケージのカスタムUserProvider

> Laravelパッケージから認証ユーザーの保存先を拡張し、UserProviderの契約・Auth::providerの登録・セッションとパスワード再ハッシュを安全に実装する方法を解説します。

パッケージがユーザーをLaravelの標準的なEloquentモデルやデータベース以外から取得する場合は、独自の `UserProvider` を登録します。たとえば外部ディレクトリ、既存の会員システム、専用のAPIなどを認証の保存先にできます。

これはガードを新しく作る拡張とは異なります。既存の `session` や `token` ガードに、ユーザーを検索・検証する実装だけを提供します。ガード自体の認証方式を変更する場合は、[カスタム認証ガードの実装](https://kawax.biz/jp/advanced/custom-auth-guard.md)を参照してください。

> [!NOTE]
>
> このページはLaravel 13を対象に、公式ドキュメントの `13.x` ブランチとFramework `v13.43.0` の実装を参照しています。パッケージが対応するLaravelの各バージョンで、契約のメソッドとパスワード再ハッシュの動作を確認してください。

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

`Auth::guard()` が返すガードは、セッションやリクエストから認証状態を取り出します。ガードがユーザーを取得するとき、設定されたプロバイダーへ処理を委譲します。

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as 外部ユーザー保存先
    G->>P: retrieveById / retrieveByCredentials
    P->>S: ユーザーを検索
    S-->>P: 保存データ
    P-->>G: Authenticatable または null
    G->>P: validateCredentials
    P-->>G: true または false
```

| 拡張対象 | 主な責務 | 設定する場所 |
| - | - | - |
| Guard | リクエスト、セッション、トークンから認証状態を管理する | `auth.guards` |
| UserProvider | ユーザーの取得、パスワード検証、remember tokenの更新 | `auth.providers` |
| Authenticatable | 認証ID、パスワード、remember tokenの属性名を公開する | ユーザーオブジェクト |

`UserProvider` が返す値は、保存先の配列やSDKのレスポンスではなく、`Illuminate\Contracts\Auth\Authenticatable` を実装したオブジェクトでなければなりません。

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

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

Laravelは `Auth::provider($name, $callback)` に登録したコールバックを、`auth.providers.*.driver` の値に応じて呼び出します。コールバックにはアプリケーションとプロバイダー設定が渡されます。

パッケージのサービスプロバイダーでは、認証サービスが利用される前に登録します。

```php theme={null}
<?php

namespace Acme\Directory;

use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\ServiceProvider;

final class DirectoryServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Auth::provider('directory', function (
            Application $app,
            array $config,
        ): UserProvider {
            return new DirectoryUserProvider(
                $app->make(DirectoryClientManager::class)
                    ->connection($config['connection'] ?? 'default'),
                $app->make('hash'),
            );
        });
    }
}
```

`DirectoryClientManager` と `DirectoryUserProvider` はパッケージがコンテナへ登録するクラスです。`$config` は利用アプリケーションの `auth.php` から渡されるため、接続名やテナントなど、プロバイダーの生成に必要な値をそこから読み取れます。

`Auth::provider` は認証**ユーザープロバイダー**の名前を登録します。`Auth::extend` が登録するカスタムガードのドライバーとは別の拡張点です。両方を使う場合でも、ガードの責務とユーザー保存先の責務を別クラスに保ちます。

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

登録した名前を `auth.providers` の `driver` に指定し、そのプロバイダーをガードから参照します。

```php theme={null}
// config/auth.php
return [
    'defaults' => [
        'guard' => 'directory-web',
        'passwords' => 'users',
    ],

    'guards' => [
        'directory-web' => [
            'driver' => 'session',
            'provider' => 'directory-users',
        ],
    ],

    'providers' => [
        'directory-users' => [
            'driver' => 'directory',
            'connection' => 'primary-directory',
        ],
    ],
];
```

この設定の対応関係は次のとおりです。

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メソッドを要求します。

```php theme={null}
interface UserProvider
{
    public function retrieveById($identifier);
    public function retrieveByToken($identifier, $token);
    public function updateRememberToken(Authenticatable $user, $token);
    public function retrieveByCredentials(array $credentials);
    public function validateCredentials(Authenticatable $user, array $credentials);
    public function rehashPasswordIfRequired(
        Authenticatable $user,
        array $credentials,
        bool $force = false,
    );
}
```

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

### `Authenticatable` を返す

外部保存先のレコードを、そのまま返さずに `GenericUser` へ変換する最小例です。実際のパッケージでは、利用者が追加属性へ型付きでアクセスできる専用のユーザークラスを用意しても構いません。

```php theme={null}
use Illuminate\Auth\GenericUser;
use Illuminate\Contracts\Auth\Authenticatable;

private function makeUser(?array $record): ?Authenticatable
{
    if ($record === null) {
        return null;
    }

    // id, password, remember_token を含むレコードを想定する。
    return new GenericUser($record);
}
```

`GenericUser` は `id`、`password`、`remember_token` という属性名を既定値として使います。別の名前を使う場合は、`Authenticatable` を実装する専用クラスで `getAuthIdentifierName()` などを上書きします。

### IDとremember tokenで取得する

`retrieveById` はセッションへ保存された認証IDからユーザーを復元します。remember tokenによるログインをサポートする場合は、識別子とトークンを保存先で照合します。

```php theme={null}
public function retrieveById($identifier): ?Authenticatable
{
    return $this->makeUser($this->client->find($identifier));
}

public function retrieveByToken(
    $identifier,
    #[\SensitiveParameter] $token,
): ?Authenticatable {
    $record = $this->client->find($identifier);
    $rememberToken = $record['remember_token'] ?? null;

    if (! is_string($rememberToken) || ! hash_equals($rememberToken, $token)) {
        return null;
    }

    return $this->makeUser($record);
}

public function updateRememberToken(
    Authenticatable $user,
    #[\SensitiveParameter] $token,
): void {
    $this->client->updateRememberToken(
        $user->getAuthIdentifier(),
        $token,
    );
}
```

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

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

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

`Auth::attempt()` は、まず `retrieveByCredentials` でユーザーを探し、その後 `validateCredentials` でパスワードを検証します。検索メソッドでパスワード比較まで行うと、ガードが想定する処理順序やパスワード再ハッシュを壊します。

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;

public function retrieveByCredentials(
    #[\SensitiveParameter] array $credentials,
): ?Authenticatable {
    $criteria = array_filter(
        $credentials,
        fn (string $key): bool => ! str_contains($key, 'password'),
        ARRAY_FILTER_USE_KEY,
    );

    if ($criteria === []) {
        return null;
    }

    return $this->makeUser($this->client->findBy($criteria));
}
```

`password` だけでなく `password_confirmation` などのキーも保存先の検索条件から除外します。パスワードやアクセストークンを、検索APIのクエリ・ログ・キャッシュキーへ含めないようにしてください。検索条件として受け付けるキーを `email` などの許可リストで制限する設計も、外部APIへ任意のフィールドを渡さないために有効です。

### `validateCredentials` でHashを比較する

検証にはアプリケーションの `Hasher` を使い、平文パスワードを保存先へ送信したりログへ出力したりしません。

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Hashing\Hasher;

public function validateCredentials(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
): bool {
    $plain = $credentials['password'] ?? null;
    $hashed = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($hashed)) {
        return false;
    }

    return $this->hasher->check($plain, $hashed);
}
```

`$credentials['password']` がない場合や、ユーザーがパスワードを持たない場合は `false` を返します。外部の認証APIへ検証を委譲する設計では、同じ契約を守りつつ、失敗・タイムアウト・レート制限をパッケージの例外方針に従って扱います。

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

Laravelはログイン成功後、設定されたハッシュ方式に対して再ハッシュが必要かを確認できます。カスタムプロバイダーは `rehashPasswordIfRequired` を実装し、必要なときだけ保存先のハッシュを更新します。

```php theme={null}
public function rehashPasswordIfRequired(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
    bool $force = false,
): void {
    $plain = $credentials['password'] ?? null;
    $currentHash = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($currentHash)) {
        return;
    }

    if (! $force && ! $this->hasher->needsRehash($currentHash)) {
        return;
    }

    $this->client->updatePassword(
        $user->getAuthIdentifier(),
        $this->hasher->make($plain),
    );
}
```

外部保存先へ更新を行うため、再ハッシュの失敗を無視しないでください。更新後に返すユーザーオブジェクトのパスワード属性が古いままでも、次の認証で再ハッシュが繰り返される可能性があります。利用する `Hasher` と保存先のパスワード形式が一致することも、パッケージの要件として明記します。

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

パッケージのテストでは、保存先クライアントをfakeに差し替え、`UserProvider` の各責務を個別に検証します。特に次の3点を分けて確認します。

* `retrieveByCredentials` がパスワードをクライアントへ渡さない。
* 正しいハッシュだけが `validateCredentials` を通過する。
* 再ハッシュが必要な場合だけ更新APIを呼び出す。

```php theme={null}
public function test_credentials_lookup_does_not_send_password(): void
{
    $this->client->expects('findBy')
        ->with(['email' => 'user@example.com'])
        ->andReturn([
            'id' => 'user-1',
            'password' => $this->hasher->make('secret'),
            'remember_token' => null,
        ]);

    $user = $this->provider->retrieveByCredentials([
        'email' => 'user@example.com',
        'password' => 'secret',
    ]);

    $this->assertSame('user-1', $user?->getAuthIdentifier());
}
```

上の `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` の設定キー、接続設定を削除する前に、設定キャッシュとデプロイ手順を確認する。

パッケージは「どの保存先から何をユーザーとして返すか」と「パスワードをどのハッシュで管理するか」を公開契約として扱い、認証情報の取り扱いをアプリケーション任せにしすぎないようにします。

## 関連ページ

> [card] [カスタム認証ガード](https://kawax.biz/jp/advanced/custom-auth-guard.md)
>
> ガード自体を拡張し、セッションやAPIトークンからユーザーを解決する方法を確認します。

> [card] [サービスプロバイダー](https://kawax.biz/jp/service-providers.md)
>
> パッケージのサービスプロバイダーを登録し、起動時に拡張を適用する基本を確認します。

## 参照した一次情報

* [Laravel公式ドキュメント: Adding Custom User Providers](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Laravel公式ドキュメント: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider() とガード解決](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: カスタムプロバイダー生成](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/CreatesUserProviders.php)
* [UserProvider contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/UserProvider.php)
* [Authenticatable contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/Authenticatable.php)
* [EloquentUserProvider: 既定実装](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: 属性から作るAuthenticatable](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [応用トピック](https://kawax.biz/jp/advanced/index.md)
- [パッケージのカスタムセッションドライバー](https://kawax.biz/jp/advanced/package-session-drivers.md)
- [パッケージのカスタムキャッシュストアと契約](https://kawax.biz/jp/advanced/package-cache-drivers.md)
- [パッケージのカスタム通知チャネルと配信検証](https://kawax.biz/jp/advanced/package-notification-channels.md)
- [Boostのカスタムエージェントを作る](https://kawax.biz/jp/advanced/boost-custom-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.