Saltar al contenido principal
Si tu paquete obtiene usuarios de algún sitio distinto del modelo Eloquent o la base de datos estándar de Laravel, registra tu propio 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 devuelve Auth::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.
La correspondencia de esta configuración es la siguiente.
  1. El guard directory-web referencia el provider directory-users.
  2. El driver de directory-users es directory, así que se elige el callback anterior.
  3. Se crea un SessionGuard que obtiene usuarios mediante el UserProvider generado.
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.
Los tres métodos de obtención devuelven un usuario o 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.
Limita los argumentos de 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.
Excluye de los criterios de búsqueda del almacén no solo 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.
Devuelve 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 implementa rehashPasswordIfRequired y actualiza el hash en el almacén solo cuando es necesario.
Como esto escribe en el almacén externo, no ignores los fallos del rehash. Si el atributo de contraseña del objeto de usuario sigue desactualizado después de la actualización, el rehash puede repetirse en el siguiente inicio de sesión. Documenta también como requisito del paquete que el 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 del UserProvider por separado. En particular, comprueba por separado estos tres puntos.
  • retrieveByCredentials no 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.
Sustituye 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.
  1. Cargar el service provider del paquete.
  2. Configurar el driver personalizado en auth.providers.
  3. Referenciar ese provider desde auth.guards.
  4. Resolver el guard por primera vez y confirmar que la obtención de usuarios se delega en el cliente fake.
  5. 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

Un UserProvider 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 a Auth::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.php o la configuración de conexión, revisa la caché de configuración y el procedimiento de despliegue.
Trata “de qué almacén y qué se devuelve como usuario” y “con qué hash se gestionan las contraseñas” como contrato público del paquete, y no dejes el manejo de credenciales por completo en manos de la aplicación.

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

Última modificación el 17 de noviembre de 2026