UserProvider. Por ejemplo, puedes usar un directorio externo, un sistema de socios existente o una API dedicada como almacén para la autenticación.
Esto es distinto de crear un guard nuevo. Solo proporcionas la implementación que busca y verifica usuarios para los guards existentes session o token. Si quieres cambiar el método de autenticación del propio guard, consulta Implementación de un guard de autenticación personalizado.
Esta página trata Laravel 13 y toma como referencia la rama
13.x de la documentación oficial y la implementación de Framework v13.43.0. Comprueba los métodos del contrato y el comportamiento del rehash de contraseñas en cada versión de Laravel que soporte tu paquete.Separar las responsabilidades del guard y del UserProvider
El guard que devuelveAuth::guard() obtiene el estado de autenticación de la sesión o de la petición. Cuando el guard necesita un usuario, delega en el provider configurado.
El valor que devuelve un
UserProvider debe ser un objeto que implemente Illuminate\Contracts\Auth\Authenticatable, no un array del almacén ni la respuesta de un SDK.
Registrar Auth::provider desde un paquete
Registrar en el boot del service provider
Laravel invoca el callback registrado con Auth::provider($name, $callback) según el valor de auth.providers.*.driver. El callback recibe la aplicación y la configuración del provider.
En el service provider del paquete, regístralo antes de que se usen los servicios de autenticación.
DirectoryClientManager y DirectoryUserProvider son clases que el paquete registra en el contenedor. $config llega desde el auth.php de la aplicación que usa el paquete, así que puedes leer de ahí el nombre de conexión, el tenant y otros valores necesarios para crear el provider.
Auth::provider registra el nombre de un user provider de autenticación. Es un punto de extensión distinto del driver de guard personalizado que registra Auth::extend. Aunque uses ambos, mantén las responsabilidades del guard y las del almacén de usuarios en clases separadas.
Conectar el provider y el guard en auth.php
Indica el nombre registrado como driver en auth.providers y referencia ese provider desde un guard.
- El guard
directory-webreferencia el providerdirectory-users. - El
driverdedirectory-usersesdirectory, así que se elige el callback anterior. - Se crea un
SessionGuardque obtiene usuarios mediante elUserProvidergenerado.
AuthManager guarda en caché el guard la primera vez que se resuelve. No hay una API que sustituya un guard ya resuelto después de registrar el provider, así que ten en cuenta el orden de arranque de los service providers y el uso de Auth::forgetGuards() en los tests. Si cacheas la configuración auth, no leas los datos de conexión directamente de variables de entorno: resuélvelos en la configuración y pásalos luego al callback.
Implementar el contrato UserProvider
En Laravel 13, Illuminate\Contracts\Auth\UserProvider exige los seis métodos siguientes.
null; un usuario inexistente no se representa con una excepción. El contrato de tu paquete decide si los timeouts y fallos de comunicación del almacén se convierten en null o en una excepción reintentable. Lo importante es no ocultar los fallos del almacén bajo el mismo “credenciales no válidas” que un fallo de autenticación.
Devolver un Authenticatable
Este ejemplo mínimo convierte un registro del almacén externo en un GenericUser en lugar de devolverlo tal cual. Un paquete real puede ofrecer una clase de usuario propia para que los usuarios del paquete accedan con tipos a atributos adicionales.
GenericUser usa por defecto los nombres de atributo id, password y remember_token. Si usas otros nombres, sobrescribe getAuthIdentifierName() y métodos relacionados en una clase propia que implemente Authenticatable.
Obtener por ID y remember token
retrieveById restaura el usuario a partir del ID de autenticación guardado en la sesión. Si admites el inicio de sesión con remember token, compara el identificador y el token en el almacén.
hash_equals a la cadena obtenida del almacén y al token, y no escribas nunca tokens en los logs. Si el almacén externo no admite remember tokens, no dejes updateRememberToken vacío para que parezca que funciona. Indica claramente en la configuración de autenticación del paquete que la función de recordar sesión no está disponible.
Separar la búsqueda de credenciales de la verificación de contraseña
No verificar la contraseña en retrieveByCredentials
Auth::attempt() primero busca el usuario con retrieveByCredentials y después verifica la contraseña con validateCredentials. Si el método de búsqueda también compara contraseñas, rompe el orden de procesamiento que espera el guard y el rehash de contraseñas.
password, sino también claves como password_confirmation. No incluyas contraseñas ni tokens de acceso en consultas a la API de búsqueda, en logs ni en claves de caché. Limitar las claves aceptadas como criterio de búsqueda a una lista permitida como email también evita enviar campos arbitrarios a una API externa.
Comparar el hash en validateCredentials
Usa el Hasher de la aplicación para verificar, y no envíes contraseñas en texto plano al almacén ni las escribas en logs.
false si falta $credentials['password'] o si el usuario no tiene contraseña. Si delegas la verificación en una API de autenticación externa, respeta el mismo contrato y gestiona fallos, timeouts y límites de tasa según la política de excepciones del paquete.
Mantener el rehash de contraseñas
Tras un inicio de sesión correcto, Laravel puede comprobar si hace falta un rehash para el algoritmo de hash configurado. Un provider personalizado implementarehashPasswordIfRequired y actualiza el hash en el almacén solo cuando es necesario.
Hasher usado coincida con el formato de contraseña del almacén.
Probar el service provider y el flujo de autenticación
En los tests del paquete, sustituye el cliente del almacén por un fake y verifica cada responsabilidad delUserProvider por separado. En particular, comprueba por separado estos tres puntos.
retrieveByCredentialsno pasa la contraseña al cliente.- Solo un hash correcto supera
validateCredentials. - La API de actualización solo se llama cuando hace falta un rehash.
expects del ejemplo por la API de la librería de mocks que uses. Si usas un cliente HTTP real, comprueba lo enviado con un HTTP fake y prueba que la contraseña en texto plano nunca aparece en peticiones ni logs.
En los tests de integración que incluyen el registro con Auth::provider, verifica con Testbench u otra herramienta el siguiente orden.
- Cargar el service provider del paquete.
- Configurar el
driverpersonalizado enauth.providers. - Referenciar ese provider desde
auth.guards. - Resolver el guard por primera vez y confirmar que la obtención de usuarios se delega en el cliente fake.
- En tests que cambian la configuración o el registro, llamar a
Auth::forgetGuards()antes de pasar al siguiente caso.
Diseñar la compatibilidad entre actualizaciones
UnUserProvider está en la frontera de la autenticación, así que al actualizar el paquete comprueba lo siguiente.
- Si cambias los nombres de atributo del ID, la contraseña o el remember token del
Authenticatable, decide cómo tratar las sesiones y remember cookies existentes. - Si cambias el formato de ID o el algoritmo de hash de contraseñas del almacén externo, comprueba que los usuarios existentes se pueden restaurar e iniciar sesión.
- Si restringes las claves permitidas en
retrieveByCredentials, comprueba la compatibilidad con las condiciones que los usuarios del paquete pasaban aAuth::attempt. - Distingue los fallos del almacén de los fallos de autenticación y define una política que no obligue a reintroducir una contraseña supuestamente incorrecta en la pantalla de login.
- Antes de eliminar el nombre del provider, las claves de configuración de
auth.phpo la configuración de conexión, revisa la caché de configuración y el procedimiento de despliegue.
Páginas relacionadas
Implementación de un guard de autenticación personalizado
Aprende a extender el propio guard y resolver usuarios a partir de sesiones o tokens de API.
Service providers
Repasa lo básico para registrar el service provider del paquete y aplicar extensiones al arrancar.
Fuentes primarias consultadas
- Documentación oficial de Laravel: Adding Custom User Providers
- Documentación oficial de Laravel: User Provider Contract
- AuthManager: provider() y resolución de guards
- CreatesUserProviders: creación de providers personalizados
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: implementación por defecto
- GenericUser: Authenticatable creado a partir de atributos