Download the PHP package mevisoft/auth-accounts-luisml without Composer

mevisoft/auth-accounts-luisml

Cliente Laravel de Accounts LuisML: «Continuar con LuisML» (OpenID Connect con PKCE) y control central de sesión. La app deja de gestionar contraseñas; Accounts decide quién entra y cuánto dura la sesión.

Requisitos: PHP ^8.2 y Laravel ^11, ^12 o ^13.

Instalación

1. Instala el paquete (publicado en Packagist; hoy solo existe dev-main, de ahí el @dev):

2. Prepara el entorno y las migraciones:

   Añade ACCOUNTS_* a .env y .env.example (sin tocar las que ya existan), ejecuta la migración (accounts_issuer y accounts_sub en users, únicas juntas) e imprime el callback exacto que debes registrar.

3. Registra la app en Accounts (/admin/applications) con ese callback exacto (HTTPS en producción). Copia el client id y el secreto (se muestra una sola vez) a .env:

   ACCOUNTS_HOME es el destino tras entrar cuando no hay otro, y donde aterriza el cierre de sesión.

4. Protege las rutas:

5. Ofrece el acceso: un enlace o botón a route('accounts.login') (/auth/accounts/redirect). Con Wayfinder: import { login } from '@/routes/accounts' y login.url(). No uses accounts.callback como enlace: es el retorno de OAuth y exige code y state.

6. Cierre de sesión: haz POST a route('accounts.logout'). Destruye la sesión local y revoca el acceso en Accounts (si no puede confirmarlo, un job lo reintenta). No afecta a otras apps ni a otros navegadores.

Rutas que registra el paquete

El prefijo se cambia con accounts.routes.prefix.

Middleware

• accounts.access: toda operación protegida pasa por aquí.
  • Una validación sirve como máximo 60 s (acotada por la caducidad del token y de la sesión central). Pasado ese plazo, Accounts debe confirmar el acceso de nuevo.
  • Si Accounts dice que ya no está activo (revocado, caducado, suspendido), la sesión local se cierra y se envía a iniciar sesión.
  • Si Accounts no responde, la operación se bloquea con un 503 recuperable (Retry-After). La sesión local se conserva y nunca se repite una mutación automáticamente.
  • accounts.access:lenient deja pasar a quien entró por otro método (sin sesión de Accounts), para apps que conservan su login propio. Por defecto es estricto.
• accounts.step-up: pide una autenticación más fuerte o más reciente para una operación sensible: accounts.step-up:acr=urn:accounts:acr:phr,max_age=300.
  • Los niveles son urn:accounts:acr:pwd < urn:accounts:acr:mfa < urn:accounts:acr:phr (passkey).
  • Si la sesión no cumple, envía a Accounts (acr_values / max_age) y vuelve a la misma petición. A clientes JSON les responde 401 con code: accounts_step_up_required.
  • Si Accounts no puede elevar el nivel (la cuenta no tiene passkey), un segundo intento para la misma dirección se rechaza con 403 en vez de repetirse sin fin.
  • Para pedirlo en un login concreto: route('accounts.login', ['acr_values' => 'urn:accounts:acr:phr', 'max_age' => 300]). Solo acr_values, max_age y prompt (login o consent) llegan a Accounts.
• accounts.activity: informa a Accounts de actividad real, como mucho cada 15 s. Ignora el polling, el prefetch y las respuestas con error.

Los reportes de actividad pueden prolongar la sesión central, pero no reinician el plazo de introspección. Así, una persona que navega continuamente también recibe los cambios de perfil y roles.

La renovación de tokens requiere una caché persistente compartida por los workers, con soporte de locks. Además del bloqueo, se conserva el resultado cifrado por generación de tokens durante al menos la duración de la sesión local: las peticiones que ya cargaron una copia antigua de la sesión reutilizan ese resultado. Un resultado ambiguo obliga a autorizar de nuevo. La protección depende de que esos registros no se pierdan ni se eliminen de la caché durante ese plazo; array sirve solo para pruebas.

Cierre de sesión central

• Local (por defecto): POST accounts.logout cierra la sesión de esta app y revoca su acceso.
• Global: con ACCOUNTS_GLOBAL_LOGOUT=true el cierre también termina la sesión central en Accounts (RP-initiated logout, con id_token_hint) y vuelve a ACCOUNTS_POST_LOGOUT_REDIRECT_URI, que debe estar registrada para esta app en Accounts. Solo se aplica a sesiones iniciadas con esta versión (necesitan el ID Token guardado).
• Back-channel: registra en Accounts la dirección https://tu-app/auth/accounts/backchannel-logout. Cuando la sesión central termina (cierre en otra app, cierre de todas las sesiones, cambio de contraseña, suspensión), Accounts avisa y la sesión local se cierra en su siguiente petición. Requiere una caché compartida por todos los servidores de la app (no array).

Los reintentos de revocación necesitan una cola persistente y un worker. Con sync no hay reintentos durables. Una caída de la cola no impide cerrar la sesión local; el mensaje indica cuando no se pudo programar el reintento.

Roles

Accounts asigna a cada cuenta roles gruesos por aplicación (por ejemplo admin). Se copian al iniciar sesión y se mantienen al día con la misma sincronización del perfil (en ≤60 s). En el modelo de usuario:

Los roles compartidos de Accounts están en LuisML\AccountsClient\Roles (OWNER, ADMIN y MEMBER). Cada app puede ofrecer además roles propios, que se leen como cadenas.

Si Accounts no manda roles, la persona queda sin roles (falla cerrado). Los permisos finos siguen siendo de cada app.

Entrada y login

El paquete registra GET /login (nombre login, desactivable con accounts.routes.login = false): lleva al invitado directo a Accounts. Si vuelve a /login en menos de 30 s (el callback falló y la página protegida lo rebotó), muestra un botón manual en lugar de redirigir de nuevo, así que una caída de Accounts nunca provoca un bucle.

Perfil central

El nombre, el correo y la contraseña se editan solo en Accounts. Las apps no deben ofrecer su propio formulario para esos datos: enlaza a accounts_account_url() (por defecto {ACCOUNTS_ISSUER}/account, configurable con ACCOUNTS_ACCOUNT_URL).

Los cambios llegan a la copia local sin que la persona vuelva a iniciar sesión: la introspección que accounts.access hace cada ≤60 s devuelve una huella del perfil (accounts_profile_version); si cambia, el paquete lee UserInfo y actualiza el usuario con tu user_resolver. Si UserInfo falla, la petición sigue y se reintenta en la siguiente validación.

Usuarios

La identidad se vincula por (issuer, sub), nunca por correo: un usuario local con el mismo correo no se toma ni se enlaza. Un usuario nuevo se crea al primer login, con el correo ya verificado por Accounts.

Para hacer algo más al crear o vincular (p. ej. un equipo personal), indica tu propio resolver en config/accounts.php:

Es una clase invocable que recibe LuisML\AccountsClient\Identity y devuelve un Authenticatable (o null para rechazar):

Los roles y permisos siguen siendo locales a cada app: entrar con Accounts no concede ningún rol de negocio.

Quitar el login propio

Para que Accounts sea el único acceso (como «Iniciar sesión con Google»):

• Usa accounts.access en modo estricto.
• Vacía las funciones de Fortify ('features' => []), haz que el login con contraseña falle siempre (Fortify::authenticateUsing(fn () => null)) y deja /login como página con solo el botón de Accounts.
• Elimina registro, recuperación de contraseña, verificación de correo, 2FA, passkeys y la página de seguridad: todo eso vive en Accounts.
• Los usuarios locales existentes no se enlazan solos; solo entran cuentas vinculadas por (issuer, sub).

php artisan accounts:install detecta estos restos de autenticación local y los lista (no borra nada por defecto). Con --remove-auth borra las páginas, componentes, controlador, requests y tests de registro, recuperación de contraseña, verificación de correo, 2FA, passkeys y seguridad, y vacía features en config/fortify.php; pide confirmación (--force la omite). Un archivo que otro código todavía usa (p. ej. SecurityController desde routes/settings.php) no se borra: se avisa de quién lo usa para que lo edites antes. Lo demás (el FortifyServiceProvider, las rutas de seguridad, enlaces de registro, el menú de usuario) se imprime como pasos manuales porque depende de cada app.

Opciones de accounts:install

Orden recomendado: accounts:install --migrate --protect-routes --test-helper --remove-auth, completar a mano lo que imprime (login, FortifyServiceProvider, menú), rellenar .env con los datos de la app registrada y terminar con accounts:install --check.

Pruebas en la app

Con el modo estricto, todo actingAs necesita una sesión de Accounts validada. Una forma de hacerlo en tests/TestCase.php:

Configuración

php artisan vendor:publish --tag=accounts-config publica config/accounts.php. Valores principales:

Seguridad

• Los tokens se guardan cifrados en la sesión del servidor y nunca llegan a props, JavaScript ni logs.
• El issuer es fijo y se compara literalmente con el iss de cada ID Token y con el documento de descubrimiento.
• El secreto del cliente vive solo en la configuración del backend.

Desarrollo del paquete