> ## 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 personalizado en paquetes

> Cómo extender desde un paquete de Laravel el lugar donde se guardan los usuarios autenticados e implementar de forma segura el contrato UserProvider, el registro con Auth::provider, las sesiones y el rehash de contraseñas.

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](https://kawax.biz/es/advanced/custom-auth-guard.md).

> [!NOTE]
>
> 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.

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as Almacén externo de usuarios
    G->>P: retrieveById / retrieveByCredentials
    P->>S: Buscar usuario
    S-->>P: Datos almacenados
    P-->>G: Authenticatable o null
    G->>P: validateCredentials
    P-->>G: true o false
```

| Punto de extensión | Responsabilidad principal | Dónde se configura |
| - | - | - |
| Guard | Gestiona el estado de autenticación a partir de la petición, la sesión o el token | `auth.guards` |
| UserProvider | Obtiene usuarios, verifica contraseñas y actualiza el remember token | `auth.providers` |
| Authenticatable | Expone los nombres de atributo del ID de autenticación, la contraseña y el remember token | Objeto de usuario |

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.

```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` 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.

```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',
        ],
    ],
];
```

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.

```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,
    );
}
```

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.

```php theme={null}
use Illuminate\Auth\GenericUser;
use Illuminate\Contracts\Auth\Authenticatable;

private function makeUser(?array $record): ?Authenticatable
{
    if ($record === null) {
        return null;
    }

    // Se asume un registro que contiene id, password y remember_token.
    return new GenericUser($record);
}
```

`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.

```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,
    );
}
```

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.

```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));
}
```

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.

```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);
}
```

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.

```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),
    );
}
```

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.

```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());
}
```

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

> [card] [Implementación de un guard de autenticación personalizado](https://kawax.biz/es/advanced/custom-auth-guard.md)
>
> Aprende a extender el propio guard y resolver usuarios a partir de sesiones o tokens de API.

> [card] [Service providers](https://kawax.biz/es/service-providers.md)
>
> 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](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Documentación oficial de Laravel: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider() y resolución de guards](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: creación de providers personalizados](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: implementación por defecto](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: Authenticatable creado a partir de atributos](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [Temas avanzados](https://kawax.biz/es/advanced/index.md)
- [Implementación de un guard de autenticación personalizado](https://kawax.biz/es/advanced/custom-auth-guard.md)
- [Stores de caché personalizados y contratos en paquetes](https://kawax.biz/es/advanced/package-cache-drivers.md)
- [Drivers de sesión personalizados en paquetes](https://kawax.biz/es/advanced/package-session-drivers.md)
- [Proveedores personalizados](https://kawax.biz/es/packages/laravel-copilot-sdk/custom-providers.md)


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