跳转到主要内容
当包需要从 Laravel 标准的 Eloquent 模型或数据库以外的地方获取用户时,请注册自己的 UserProvider。例如,可以将外部目录、现有会员系统或专用 API 作为认证的存储位置。 这与新建 Guard 的扩展不同。你只需为现有的 session 或 token Guard 提供查找和验证用户的实现。如果要更改 Guard 本身的认证方式,请参阅实现自定义认证 Guard。
本页面向 Laravel 13,参考了官方文档的 13.x 分支和 Framework v13.43.0 的实现。请在包所支持的每个 Laravel 版本中确认契约的方法和密码重新哈希的行为。

分离 Guard 与 UserProvider 的职责

Auth::guard() 返回的 Guard 从会话或请求中取出认证状态。Guard 获取用户时,会将处理委托给已配置的提供者。 UserProvider 返回的值必须是实现了 Illuminate\Contracts\Auth\Authenticatable 的对象,而不是存储中的数组或 SDK 的响应。

从包中注册 Auth::provider

在服务提供者的 boot 中注册

Laravel 会根据 auth.providers.*.driver 的值调用通过 Auth::provider($name, $callback) 注册的回调。回调会接收应用实例和提供者配置。 在包的服务提供者中,要在认证服务被使用之前完成注册。
DirectoryClientManager 和 DirectoryUserProvider 是包注册到容器中的类。$config 来自使用方应用的 auth.php,因此可以从中读取连接名、租户等创建提供者所需的值。 Auth::provider 注册的是认证用户提供者的名称。它与 Auth::extend 注册的自定义 Guard 驱动是不同的扩展点。即使两者都使用,也要将 Guard 的职责和用户存储的职责保持在不同的类中。

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

将注册的名称指定为 auth.providers 的 driver,并在 Guard 中引用该提供者。
该配置的对应关系如下。
  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 个方法。
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 验证密码。如果在查找方法中也进行密码比较,会破坏 Guard 预期的处理顺序和密码重新哈希。
不仅要从存储的查找条件中排除 password,还要排除 password_confirmation 等键。不要把密码或访问令牌放进查找 API 的查询、日志或缓存键中。将可接受的查找键限制在 email 等允许列表内,也能有效避免向外部 API 传递任意字段。

在 validateCredentials 中比较哈希

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

设计更新时的兼容性

UserProvider 位于认证的边界上,因此在更新包时要确认以下事项。
  • 更改 Authenticatable 的 ID、密码、remember token 属性名时,确定如何处理现有会话和 remember cookie。
  • 更改外部存储的 ID 格式或密码哈希方式时,确认旧用户能否被还原并登录。
  • 收窄 retrieveByCredentials 的允许键时,确认与使用者传给 Auth::attempt 的条件是否兼容。
  • 将存储故障与认证失败区分开,并确定不会让用户在登录页面误以为密码错误而重新输入的策略。
  • 删除 provider 名称、auth.php 的配置键或连接配置之前,确认配置缓存和部署步骤。
包应将“从哪个存储返回什么作为用户”和“用哪种哈希管理密码”视为公开契约,不要把认证信息的处理过多地交给应用。

相关页面

实现自定义认证 Guard

了解如何扩展 Guard 本身,并从会话或 API 令牌解析用户。

服务提供者

了解注册包的服务提供者并在启动时应用扩展的基础知识。

参考的一手资料

最后修改于 2026年11月17日