> ## 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 作为认证的存储位置。

这与新建 Guard 的扩展不同。你只需为现有的 `session` 或 `token` Guard 提供查找和验证用户的实现。如果要更改 Guard 本身的认证方式，请参阅[实现自定义认证 Guard](https://kawax.biz/zh-CN/advanced/custom-auth-guard.md)。

> [!NOTE]
>
> 本页面向 Laravel 13，参考了官方文档的 `13.x` 分支和 Framework `v13.43.0` 的实现。请在包所支持的每个 Laravel 版本中确认契约的方法和密码重新哈希的行为。

## 分离 Guard 与 UserProvider 的职责

`Auth::guard()` 返回的 Guard 从会话或请求中取出认证状态。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` 返回的值必须是实现了 `Illuminate\Contracts\Auth\Authenticatable` 的对象，而不是存储中的数组或 SDK 的响应。

## 从包中注册 `Auth::provider`

### 在服务提供者的 `boot` 中注册

Laravel 会根据 `auth.providers.*.driver` 的值调用通过 `Auth::provider($name, $callback)` 注册的回调。回调会接收应用实例和提供者配置。

在包的服务提供者中，要在认证服务被使用之前完成注册。

```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` 注册的自定义 Guard 驱动是不同的扩展点。即使两者都使用，也要将 Guard 的职责和用户存储的职责保持在不同的类中。

### 在 `auth.php` 中连接提供者与 Guard

将注册的名称指定为 `auth.providers` 的 `driver`，并在 Guard 中引用该提供者。

```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` Guard 引用 `directory-users` 提供者。
2. `directory-users` 的 `driver` 为 `directory`，因此会选中前面的回调。
3. 生成 `SessionGuard`，并使用生成的 `UserProvider` 获取用户。

`AuthManager` 会在首次解析 Guard 时将其缓存。没有在注册提供者后替换已解析 Guard 的 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` 验证密码。如果在查找方法中也进行密码比较，会破坏 Guard 预期的处理顺序和密码重新哈希。

```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` 中比较哈希

验证时使用应用的 `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. 首次解析 Guard，并确认用户获取被委托给 fake 客户端。
5. 在会更改配置或注册的测试中，进入下一个用例前调用 `Auth::forgetGuards()`。

## 设计更新时的兼容性

`UserProvider` 位于认证的边界上，因此在更新包时要确认以下事项。

* 更改 `Authenticatable` 的 ID、密码、remember token 属性名时，确定如何处理现有会话和 remember cookie。
* 更改外部存储的 ID 格式或密码哈希方式时，确认旧用户能否被还原并登录。
* 收窄 `retrieveByCredentials` 的允许键时，确认与使用者传给 `Auth::attempt` 的条件是否兼容。
* 将存储故障与认证失败区分开，并确定不会让用户在登录页面误以为密码错误而重新输入的策略。
* 删除 provider 名称、`auth.php` 的配置键或连接配置之前，确认配置缓存和部署步骤。

包应将“从哪个存储返回什么作为用户”和“用哪种哈希管理密码”视为公开契约，不要把认证信息的处理过多地交给应用。

## 相关页面

> [card] [实现自定义认证 Guard](https://kawax.biz/zh-CN/advanced/custom-auth-guard.md)
>
> 了解如何扩展 Guard 本身，并从会话或 API 令牌解析用户。

> [card] [服务提供者](https://kawax.biz/zh-CN/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() 与 Guard 解析](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/zh-CN/advanced/index.md)
- [包的自定义 Session 驱动](https://kawax.biz/zh-CN/advanced/package-session-drivers.md)
- [实现自定义认证 Guard](https://kawax.biz/zh-CN/advanced/custom-auth-guard.md)
- [包的自定义缓存存储与契约](https://kawax.biz/zh-CN/advanced/package-cache-drivers.md)
- [创建 AI SDK 的自定义 Provider](https://kawax.biz/zh-CN/advanced/ai-sdk-custom-provider.md)


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