> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción a la autenticación

> Explicamos los conceptos básicos de la autenticación en Laravel. Cubrimos desde la introducción de un sistema de autenticación con un starter kit hasta cómo obtener el usuario autenticado.

## ¿Qué es la autenticación?

La autenticación consiste en verificar "quién es" el usuario que accede.
En una aplicación web, un formulario de login recibe correo y contraseña y, si son correctos, guarda la información del usuario en la sesión.
En las siguientes solicitudes se identifica al usuario consultando esa sesión.

La autenticación en Laravel se compone de dos conceptos: "guards" y "providers".

* **Guard**: define cómo autenticar al usuario en cada solicitud. Por defecto se usa el guard `session`, que gestiona el estado con sesión y cookies.
* **Provider**: define cómo obtener al usuario desde la base de datos. Por defecto usa Eloquent.

<Info>
  El archivo de configuración de autenticación es `config/auth.php`. Con la configuración por defecto es suficiente para la mayoría de aplicaciones web.
</Info>

```mermaid theme={null}
flowchart TD
    A["Solicitud de login"] --> B["Guard<br>(define el método de autenticación)"]
    B --> C["Provider<br>(obtiene el usuario de la BD)"]
    C --> D{"Verificación"}
    D -- "Éxito" --> E["Se guarda la información<br>del usuario en la sesión"]
    E --> F["Redirección a la página<br>autenticada"]
    D -- "Fallo" --> G["Redirección a la<br>pantalla de login"]
```

## Autenticación con starter kit

En Laravel, con solo elegir un starter kit al crear la aplicación con `laravel new`, se generan automáticamente las funciones de login, registro, restablecimiento de contraseña, etc. Es el método más recomendado.

<Steps>
  <Step title="Crear la aplicación">
    Crea la aplicación con el instalador de Laravel. Durante el proceso aparece un prompt para elegir el starter kit.

    ```shell theme={null}
    laravel new my-app
    ```

    Puedes elegir entre **React**, **Vue**, **Livewire** y **Svelte** como starter kits.
    Elige según la pila técnica de tu equipo.
  </Step>

  <Step title="Instalar las dependencias del frontend">
    ```shell theme={null}
    cd my-app
    npm install && npm run build
    ```
  </Step>

  <Step title="Preparar la base de datos">
    Después de comprobar la configuración de base de datos en `.env`, ejecuta las migraciones.

    ```shell theme={null}
    php artisan migrate
    ```

    Se aplica la migración inicial que incluye la tabla `users`.
  </Step>

  <Step title="Iniciar el servidor de desarrollo">
    ```shell theme={null}
    composer run dev
    ```

    Al acceder a `http://localhost:8000` en el navegador verás en la navegación los enlaces "Register" y "Log in".
    Prueba a registrarte accediendo a `/register`.
  </Step>
</Steps>

Al usar un starter kit dispones de las siguientes funciones:

| Funcionalidad                  | URL                 |
| ------------------------------ | ------------------- |
| Registro de usuario            | `/register`         |
| Inicio de sesión               | `/login`            |
| Restablecimiento de contraseña | `/forgot-password`  |
| Verificación de correo         | `/email/verify`     |
| Edición del perfil             | `/settings/profile` |

<Tip>
  Todo el código generado por el starter kit (controladores, rutas, vistas) vive en tu propia aplicación. Puedes modificarlo y personalizarlo libremente.
</Tip>

### Starter kits disponibles

#### React

Con React 19, TypeScript, Tailwind y [shadcn/ui](https://ui.shadcn.com) puedes crear una SPA moderna.
Gracias a [Inertia](https://inertiajs.com) puedes usar React en el frontend manteniendo el enrutamiento del lado del servidor.

#### Vue

Adopta la Composition API de Vue, TypeScript, Tailwind y [shadcn-vue](https://www.shadcn-vue.com/).
Igual que React, se integra con el servidor mediante Inertia.

#### Livewire

Utiliza [Livewire](https://livewire.laravel.com), que permite construir UIs dinámicas solo con PHP.
Ideal para equipos centrados en plantillas Blade o que no quieran usar un framework JavaScript.
Incluye la librería de componentes [Flux UI](https://fluxui.dev).

#### Svelte

Utiliza Svelte 5, TypeScript, Tailwind y [shadcn-svelte](https://www.shadcn-svelte.com/).
Combinado con Inertia permite construir una SPA moderna.

## Fachada Auth

Con la fachada `Auth` puedes obtener la información del usuario autenticado y comprobar el estado de autenticación.

### Obtener el usuario autenticado

```php theme={null}
use Illuminate\Support\Facades\Auth;

// Obtiene el usuario actual
$user = Auth::user();

// Obtiene solo el ID
$id = Auth::id();
```

En los controladores también puedes obtenerlo desde el objeto `Request`.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class DashboardController extends Controller
{
    public function index(Request $request)
    {
        $user = $request->user();

        return view('dashboard', ['user' => $user]);
    }
}
```

### Comprobar el estado de autenticación

`Auth::check()` devuelve `true` o `false` según si el usuario ha iniciado sesión.

```php theme={null}
use Illuminate\Support\Facades\Auth;

if (Auth::check()) {
    // Sesión iniciada
} else {
    // Sin sesión
}
```

En plantillas Blade son cómodas las directivas `@auth` y `@guest`.

```blade theme={null}
@auth
    <p>Hola, {{ Auth::user()->name }}</p>
    <a href="/logout">Cerrar sesión</a>
@endauth

@guest
    <a href="/login">Iniciar sesión</a>
    <a href="/register">Registrarse</a>
@endguest
```

## Protección de rutas

Para crear rutas accesibles solo a usuarios autenticados, usa el middleware `auth`.

```php theme={null}
// routes/web.php

// Solo accesible por usuarios autenticados
Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware('auth');
```

Si un usuario no autenticado intenta acceder, se le redirige automáticamente a `/login`.

Para proteger varias rutas de una vez, usa un grupo.

```php theme={null}
Route::middleware('auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::get('/profile', [ProfileController::class, 'show']);
    Route::get('/settings', [SettingsController::class, 'index']);
});
```

<Warning>
  Si olvidas aplicar el middleware `auth`, los usuarios sin sesión podrán acceder. Asegúrate de aplicarlo en todas las rutas que deban protegerse.
</Warning>

### Rutas solo para invitados

Para redirigir a los usuarios autenticados usa el middleware `guest`.
Aplicándolo a las páginas de login y registro, los usuarios que ya han iniciado sesión se envían al dashboard.

```php theme={null}
Route::middleware('guest')->group(function () {
    Route::get('/login', [AuthController::class, 'showLogin']);
    Route::get('/register', [AuthController::class, 'showRegister']);
});
```

## Autenticación manual

Para implementar el login manualmente sin usar un starter kit, usa `Auth::attempt()`.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
    public function login(Request $request): RedirectResponse
    {
        $credentials = $request->validate([
            'email' => ['required', 'email'],
            'password' => ['required'],
        ]);

        if (Auth::attempt($credentials)) {
            // Éxito — regenera la sesión para prevenir ataques CSRF
            $request->session()->regenerate();

            return redirect()->intended('/dashboard');
        }

        // Fallo de autenticación
        return back()->withErrors([
            'email' => 'El correo o la contraseña no son correctos.',
        ])->onlyInput('email');
    }
}
```

Pasa un array de credenciales como primer argumento a `Auth::attempt()`.
La contraseña se compara automáticamente con el hash guardado, así que pásala en texto plano.

Para implementar la función "recordarme", pasa `true` como segundo argumento.

```php theme={null}
// Usa el valor del checkbox "Recordarme"
Auth::attempt($credentials, $request->boolean('remember'));
```

<Info>
  Aunque implementes la autenticación manualmente, es recomendable inspirarse en el código del starter kit como referencia para una implementación segura.
</Info>

## Cierre de sesión

Para cerrar la sesión del usuario, llama a `Auth::logout()`.
La buena práctica es invalidar la sesión y regenerar el token CSRF al mismo tiempo.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;

class LogoutController extends Controller
{
    public function logout(Request $request): RedirectResponse
    {
        Auth::logout();

        // Invalida la sesión
        $request->session()->invalidate();

        // Regenera el token CSRF
        $request->session()->regenerateToken();

        return redirect('/');
    }
}
```

Usa el método POST en la ruta.

```php theme={null}
Route::post('/logout', [LogoutController::class, 'logout'])->middleware('auth');
```

En la plantilla Blade, envía la solicitud POST con un formulario.

```blade theme={null}
<form method="POST" action="/logout">
    @csrf
    <button type="submit">Cerrar sesión</button>
</form>
```

## Resumen

| Objetivo                         | Método                              |
| -------------------------------- | ----------------------------------- |
| Añadir autenticación rápidamente | Starter kit (`laravel new`)         |
| Obtener el usuario actual        | `Auth::user()` / `$request->user()` |
| Comprobar si hay sesión iniciada | `Auth::check()`                     |
| Proteger una ruta                | `->middleware('auth')`              |
| Iniciar sesión manualmente       | `Auth::attempt($credentials)`       |
| Cerrar sesión                    | `Auth::logout()`                    |

## Próximos pasos

<Card title="Middleware" icon="shield-halved" href="/es/middleware">
  Aprende en detalle el funcionamiento del middleware `auth` y cómo crear middlewares propios.
</Card>


## Related topics

- [Starter kits](/es/starter-kits.md)
- [Introducción a las pruebas](/es/testing.md)
- [Hashing (hasheo)](/es/hashing.md)
- [Introducción a React — Fundamentos para usarlo con Inertia × Laravel](/es/blog/react-introduction.md)
- [¿Qué es Laravel?](/es/introduction.md)