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 中引用该提供者。
directory-webGuard 引用directory-users提供者。directory-users的driver为directory,因此会选中前面的回调。- 生成
SessionGuard,并使用生成的UserProvider获取用户。
AuthManager 会在首次解析 Guard 时将其缓存。没有在注册提供者后替换已解析 Guard 的 API,因此要注意服务提供者的启动顺序,以及在测试中使用 Auth::forgetGuards()。如果缓存了 auth 配置,也不要直接从环境变量读取连接信息,而应先解析到配置中再传给回调。
实现 UserProvider 契约
Laravel 13 的 Illuminate\Contracts\Auth\UserProvider 要求以下 6 个方法。
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 等验证以下顺序。
- 加载包的服务提供者。
- 在
auth.providers中设置自定义driver。 - 在
auth.guards中引用该提供者。 - 首次解析 Guard,并确认用户获取被委托给 fake 客户端。
- 在会更改配置或注册的测试中,进入下一个用例前调用
Auth::forgetGuards()。
设计更新时的兼容性
UserProvider 位于认证的边界上,因此在更新包时要确认以下事项。
- 更改
Authenticatable的 ID、密码、remember token 属性名时,确定如何处理现有会话和 remember cookie。 - 更改外部存储的 ID 格式或密码哈希方式时,确认旧用户能否被还原并登录。
- 收窄
retrieveByCredentials的允许键时,确认与使用者传给Auth::attempt的条件是否兼容。 - 将存储故障与认证失败区分开,并确定不会让用户在登录页面误以为密码错误而重新输入的策略。
- 删除 provider 名称、
auth.php的配置键或连接配置之前,确认配置缓存和部署步骤。
相关页面
实现自定义认证 Guard
了解如何扩展 Guard 本身,并从会话或 API 令牌解析用户。
服务提供者
了解注册包的服务提供者并在启动时应用扩展的基础知识。