Configura el inicio de sesión y el registro

Todo lo que decide cómo entra una persona a tu aplicación vive en config/auth.php, y cada opción de ahí lee una variable de entorno, así que la ajustas desde .env sin tocar el archivo. Esta guía recorre cada opción, lo que cambia en pantalla y las combinaciones que funcionan bien juntas.

Las opciones de un vistazo

El archivo conserva además las llaves estándar de Laravel: AUTH_GUARD (web), AUTH_PASSWORD_BROKER (users), AUTH_MODEL (App\Models\User) y AUTH_PASSWORD_RESET_TOKEN_TABLE (password_reset_tokens). Déjalas como están salvo que agregues un segundo guard o un segundo modelo de usuario.

Las pantallas

Todas comparten un mismo diseño: el icono de la aplicación, un título y una tarjeta blanca con el formulario.

• /login — "Bienvenido de nuevo". Un campo etiquetado con la identidad que permites, un campo de contraseña, la casilla "Recuérdame", el enlace "¿Olvidaste tu contraseña?" y el botón "Iniciar sesión". Bajo el título, "O crea una cuenta nueva" lleva al registro.
• /register — "Crear tu cuenta". Nombre, los campos de identidad, contraseña y su confirmación, una casilla para aceptar los términos de /terms, y "Registrarse".
• /password/reset — pide un correo y envía el enlace de restablecimiento.
• /account — el perfil, donde quien ya inició sesión edita esas mismas identidades, cambia la contraseña, define el PIN y ve los dispositivos conectados.

Después de iniciar sesión, la persona llega a config('app.home_route'), que es /app.

AUTH_APPROACH: cuándo un correo sin verificar frena el inicio de sesión

El valor se lee en un solo lugar: el inicio de sesión de un paso, cuando la persona se identifica con un correo que nunca se ha verificado.

Tres cosas acotan cuándo corre esta revisión:

• Sólo corre cuando AUTH_ENABLE_VALIDATION es true.
• Sólo corre cuando la persona se identificó con un correo. Entrar con teléfono o con nombre de usuario nunca pide un código por correo.
• Sólo corre en el inicio de sesión de un paso. El de dos pasos tiene su propia regla: en el paso uno, un correo sin verificar siempre pasa a la pantalla del código, sin importar el approach ni lo que diga AUTH_ENABLE_VALIDATION.

El registro es igual con los tres valores: el correo se verifica con un código dentro del formulario, como se describe en /help/verify-email-and-phone.

AUTH_LOGIN_STEPS: una pantalla o dos

one es el formulario clásico: identidad y contraseña juntas.

two lo divide. El paso uno muestra el campo de identidad y un botón "Continuar". Lo que sigue depende de la cuenta:

1. La identidad no existe. Si el registro está habilitado, la persona es redirigida a /register con el valor precargado; si no, ve "Credenciales incorrectas".
2. La identidad es un correo que nunca se verificó: se envía un código por correo y aparece la pantalla del código. Al confirmarlo, el flujo retoma esta lista.
3. La cuenta todavía no tiene contraseña, porque se creó desde el panel de administración sin una o se importó: el paso tres pide una "Nueva contraseña" con un botón "Crear contraseña", la guarda e inicia la sesión.
4. En cualquier otro caso el paso dos muestra la contraseña, "Recuérdame" y "¿Olvidaste tu contraseña?".

Para eso existe el modo. Tu aplicación puede crear cuentas antes de que la gente llegue, un administrador da de alta a un cliente o una importación trae una lista, y la primera visita verifica el correo y crea la contraseña sin una pantalla de bienvenida aparte. En el modo de dos pasos el enlace "O crea una cuenta nueva" no aparece bajo el título, porque la redirección del paso uno hace ese trabajo.

AUTH_ENABLE_REGISTER

true mantiene /register abierto. false hace que responda 404, oculta el enlace "O crea una cuenta nueva" en la pantalla de inicio de sesión, y hace que el inicio de sesión de dos pasos responda "Credenciales incorrectas" a una identidad desconocida en lugar de redirigir al registro. Las cuentas se crean entonces desde el panel de administración en /admin/users.

AUTH_ENABLE_VALIDATION

true, el valor por omisión: corre la revisión del inicio de sesión descrita en AUTH_APPROACH, y el campo de teléfono del registro muestra un enlace "Verificar ahora" que envía el código.

false: la revisión del inicio de sesión se omite y el campo de teléfono del registro pierde su enlace "Verificar ahora". El campo de correo no cambia: al registrarse, un correo siempre tiene que verificarse con un código, porque el formulario sólo recibe la dirección cuando el código se confirma.

Cuidado con false junto con phone en LOGIN_IDENTITIES. El campo de teléfono, igual que el de correo, entrega su valor al formulario sólo después de una verificación, así que sin el enlace un registro por teléfono no se puede completar. Deja la validación encendida siempre que el teléfono sea una identidad de registro.

AUTH_ENABLE_PIN

true agrega un PIN de cuatro dígitos a cada cuenta: aparece una tarjeta "PIN de seguridad" en el perfil, un aviso pide a quien no lo tenga que lo configure, y el PIN sustituye a la contraseña en el diálogo de confirmación que tu propio código puede abrir antes de una acción sensible. Apagado por omisión. El PIN tiene su propia guía: /help/the-security-pin.

AUTH_VALIDATION_PROVIDER

Quién lleva los códigos al teléfono: aws envía un SMS por Amazon SNS, telnyx envía un SMS o hace una llamada por Telnyx Verify. Los códigos por correo siempre viajan por tu mailer. Las credenciales y los detalles están en /help/verify-email-and-phone.

LOGIN_IDENTITIES: con qué inicia sesión una persona

Una lista separada por comas de email, phone y username. Cualquier otra cosa en la lista se ignora, y una lista vacía vuelve a email.

LOGIN_IDENTITIES=email
LOGIN_IDENTITIES=email,phone
LOGIN_IDENTITIES=email,phone,username

En la pantalla de inicio de sesión

Siempre hay un solo campo de identidad. Su etiqueta dice qué acepta: "Correo electrónico", "Teléfono" o "Nombre de usuario" cuando hay una identidad, "Identidad (Correo electrónico, Teléfono)" cuando hay varias. El valor se clasifica antes de la búsqueda, en este orden:

1. Si phone está permitido y el valor se interpreta como número telefónico, es un teléfono. El número se normaliza a formato internacional antes de consultar, así que 55 1234 5678 y +52 55 1234 5678 encuentran la misma cuenta. Un número escrito sin + se completa con el país de la cuenta que tiene sesión, del país detectado del visitante, o de COUNTRY_CODE_FALLBACK, que es US por omisión.
2. Si email está permitido y el valor es un correo válido, es un correo.
3. Si username está permitido y el valor no es un correo, es un nombre de usuario.

Con una sola identidad el campo también se valida como tal: un correo debe parecer correo, un teléfono debe ser teléfono. Con varias, el valor debe encajar en al menos una o el formulario responde que la identidad debe ser un correo o teléfono válido.

En la pantalla de registro

Con una identidad el formulario abre directo en ese campo. Con varias, la tarjeta pregunta primero "¿Cómo quieres registrarte?" y muestra un botón por identidad: Correo electrónico, Teléfono, Nombre de usuario. Elegir correo o teléfono abre el formulario con ese campo; elegir el otro lo reemplaza, así que una cuenta se crea con un canal, no con los dos. El nombre de usuario es un complemento: elegido solo, la pregunta cambia a "Selecciona un método adicional para iniciar sesión" y el formulario espera hasta que también se elija correo o teléfono. Sobre el formulario hay una leyenda como "Registrándose con Correo electrónico y Nombre de usuario" y una flecha para volver.

Los campos son Nombre, Nombre de usuario (letras, dígitos, guiones y guiones bajos; único), el campo de correo con su verificación, el campo de teléfono etiquetado "Teléfono (Incluye código de país)", Contraseña y Confirmar contraseña (al menos ocho caracteres), y la casilla de términos. Cada cuenta creada aquí recibe el rol client, que el seeder garantiza que exista.

Toda cuenta tiene nombre de usuario aunque username no esté en la lista: cuando no se da uno, se genera con la forma user0001 a partir del siguiente id. Sólo se muestra, y sólo se edita, cuando username está configurado.

En el perfil y en el panel de administración

El perfil en /account muestra los campos de identidad configurados y deja cambiarlos; un correo o teléfono nuevo pasa por el mismo código de verificación. El formulario de usuario en /admin/users muestra el mismo subconjunto. Ambos se niegan a guardar una cuenta que se quede sin ninguna identidad: "Proporciona al menos una identidad válida".

Por qué el nombre de usuario nunca va solo

Cuando hay varias identidades configuradas, el registro se niega a crear una cuenta cuya única identidad sea el nombre de usuario, y el perfil se niega a guardarla; el mensaje dice que debes proporcionar al menos uno de: correo electrónico, teléfono. La razón es que un nombre de usuario no tiene un canal detrás. Los códigos de verificación van a un correo o a un teléfono, y el formulario de restablecer contraseña sólo acepta un correo, así que una cuenta conocida sólo por su nombre de usuario jamás podría probar quién es ni volver a entrar tras perder su contraseña.

Nada te impide escribir LOGIN_IDENTITIES=username a solas. El formulario muestra entonces un solo campo de nombre de usuario y la revisión anterior se omite, porque no hay nada más que exigir, pero heredas la consecuencia: sin verificación y sin recuperación de contraseña por cuenta propia para nadie. Acompáñalo de email o phone.

Configuraciones comunes

Recuperar la contraseña

"¿Olvidaste tu contraseña?" lleva a /password/reset, que pide el correo de la cuenta y envía el enlace de restablecimiento de Laravel. El enlace vale 60 minutos y se puede pedir uno nuevo cada 60 segundos (passwords.users.expire y throttle en config/auth.php). El enlace abre /password/reset/{token}, que pide la nueva contraseña dos veces, la guarda, invalida los tokens de "Recuérdame" e inicia la sesión. Las contraseñas deben tener al menos ocho caracteres.

La recuperación sólo funciona con un correo. Una cuenta registrada sólo por teléfono recibe una contraseña nueva de un administrador, que la escribe en el formulario de usuario del panel de administración.

Con sesión iniciada, la persona cambia la contraseña desde el perfil, descrito en /help/your-account-area.

Sesiones y dispositivos

"Recuérdame" al iniciar sesión mantiene la sesión entre reinicios del navegador por medio del token de recordar. Cada inicio de sesión se vuelve además una fila de la tabla sessions, que necesita SESSION_DRIVER=database, ya puesto en .env.example, y que el perfil lista como "Dispositivos conectados" para que la persona cierre una sesión que no reconoce sin cambiar la contraseña. Esa pantalla, con el resto del perfil, se describe en /help/your-account-area.

Cuentas creadas por un administrador

Cuando un administrador crea un usuario con contraseña en /admin/users, la persona recibe un correo de bienvenida con el correo, la contraseña y un botón "Iniciar sesión" que abre /login?fromEmail=1. Entrar desde ese enlace marca el correo como verificado. La cuenta queda además marcada para un cambio de contraseña forzado: la primera petición tras iniciar sesión redirige a /password/request, "Cambia tu contraseña", que pide la contraseña actual y luego una nueva que debe ser distinta. Tu propio código puede marcar cualquier cuenta con $user->requestForNewPassword().

Un administrador también puede bloquear una cuenta con la acción "Bloquear usuario". La persona bloqueada pierde la sesión en la siguiente petición y lee "Estás bloqueado, por favor contacta a soporte." en la pantalla de inicio de sesión.

Opciones que existen pero todavía no hacen nada

• AUTH_PASSWORD_TIMEOUT y la pantalla /password/confirm son la confirmación de contraseña de Laravel. Ninguna ruta del kit usa el middleware password.confirm, así que el valor está disponible pero ninguna función del kit lo usa. El inicio de sesión sí registra la hora de confirmación, de modo que una ruta tuya protegida con ese middleware funciona.
• /email/verify y su enlace firmado son la verificación por enlace de Laravel. El kit verifica con códigos y nada envía ese enlace; la pantalla existe pero ningún flujo lleva a ella.