OAuth2 Identity Server

Índice

• 1.Qué es esta app
• 2.Puesta en marcha
• 3.Usuarios por defecto (seed)
• 4.Uso de la interfaz web (panel de administración)
• 5.Verificación en dos pasos (2FA)
• 6.Analíticas: sesiones, logins y actividad
• 7.Audit log: quién cambió qué
• 8.Roles, permisos y roles por app
• 9.Idioma (español / inglés / catalán)
• 10.Cómo conectar tu app (Angular, NestJS, Flutter, etc.)
• 11.API REST completa: construí tu propio panel admin
• 12.Webhooks: enterate sin hacer polling
• 13.Documentación interactiva (Swagger)
• 14.Referencia rápida de rutas

1. Qué es esta app

Es un servidor de identidad / OAuth2 (Laravel Passport) pensado para ser el centro único de usuarios, autenticación y permisos de un conjunto de aplicaciones propias. No es una app de negocio con datos propios: su único "recurso" son los usuarios y sus roles.

Provee tres piezas:

• Servidor de autorización OAuth2 — login, pantalla de consentimiento, y emisión de tokens con los cuatro flujos estándar: Authorization Code + PKCE, Client Credentials, Password Grant y Personal Access Tokens.
• Panel de administración en Vue 3 + TypeScript — la UI que trae la app "de fábrica", servida por el propio Laravel, autenticada por sesión. Estilos en SCSS con nomenclatura BEM (resources/scss/), sin frameworks de utility-classes.
• API REST completa (/api/*) — el mismo conjunto de funciones del panel Vue (usuarios, roles por app, clientes OAuth, personal access tokens, apps autorizadas), pero autenticada 100% por token OAuth2 (sin sesión ni cookies). Con esto se puede construir otro admin entero en Angular, Flutter, o cualquier otro cliente — no hace falta usar la SPA Vue.

2. Puesta en marcha

Requisitos

• PHP 8.4+, Composer
• Node.js + npm
• SQLite (por defecto, cero configuración — se puede cambiar en .env)

Instalación (primera vez)

composer install
npm install
php artisan migrate --seed
npm run build

Levantar todo en desarrollo

composer run dev

Este comando levanta en paralelo: el servidor PHP (php artisan serve), Vite en modo watch, la cola de trabajos y los logs. La app queda disponible en http://localhost:8000.

3. Usuarios por defecto (seed)

El seeder (database/seeders/DatabaseSeeder.php) crea una cuenta admin y algunos usuarios de ejemplo para poder probar la app de inmediato:

Clientes OAuth (apps) de ejemplo

El seeder también registra apps de prueba, una por cada flujo soportado. El client_id es fijo por ejecución (UUID nuevo cada migrate:fresh); el client_secret solo se muestra por consola al sembrar — si lo perdiste, hay que crear un cliente nuevo desde el panel (sección 4) o volver a sembrar.

4. Uso de la interfaz web (panel de administración)

Todo se maneja desde http://localhost:8000 (Vue Router, sin recargar página).

Login / Registro

/login y /register. El registro crea la cuenta con rol global user automáticamente, pero no loguea al usuario: queda pendiente de aprobación. La pantalla muestra un mensaje de "Cuenta creada" y el login devuelve error hasta que un admin la aprueba desde el panel de usuarios (sección 4). Excepción: si la base de usuarios está vacía, esa primera cuenta se crea como admin y queda logueada de una (ver sección 3).

Recuperación de contraseña

Desde /login → "¿Olvidaste tu contraseña?" (/forgot-password), cualquiera puede pedir un enlace de restablecimiento con solo su email. La respuesta es siempre la misma, exista o no una cuenta con ese email — lo contrario permitiría enumerar qué emails están registrados probando uno por uno. Si la cuenta existe, se manda un email (ver la nota sobre MAIL_MAILER en la sección 2) con un enlace a /reset-password?token=...&email=..., válido durante 60 minutos y de un solo uso.

Dashboard

/ — accesos rápidos a Clientes OAuth, Personal Access Tokens, Apps autorizadas y (si sos admin) Usuarios.

Clientes OAuth

/clients — cada usuario ve y gestiona sus propios clientes (apps que registró). Al crear uno se elige:

• Authorization Code + PKCE: hay que indicar redirect URIs; opcionalmente "confidencial" (con secret) o público (solo PKCE, sin secret).
• Client Credentials: siempre confidencial, sin redirect URI.
• Password Grant: para apps propias de confianza.

Cada cliente tiene, además, un botón "Webhooks" para registrar endpoints que reciben avisos cuando pasa algo relevante para esa app (ver sección 12) — sin tener que hacer polling.

Personal Access Tokens

/tokens — tokens tipo "API key" para el propio usuario, sin pasar por el flujo de consentimiento. Se elige nombre y scopes. El token completo también se muestra una única vez.

Apps autorizadas

/authorized-apps — lista de apps de terceros a las que el usuario le dio acceso a su cuenta vía /oauth/authorize, con opción de revocar el acceso en cualquier momento.

Usuarios (solo admins)

/admin/users — alta, edición (nombre, email, contraseña, rol global, activo/desactivado) y baja de cualquier usuario del sistema. Protecciones incluidas: no podés borrarte a vos mismo, no podés quitarte el rol admin a vos mismo, no se puede borrar al último administrador. Un usuario desactivado no puede iniciar sesión.

Seguridad: verificación en dos pasos

/security — cualquier usuario (no solo admins) puede activar 2FA acá. Ver sección 5.

Analíticas (solo admins)

/admin/analytics — ver sección 6.

Audit log (solo admins)

/admin/audit-log — ver sección 7.

5. Verificación en dos pasos (2FA)

Cualquier usuario (no hace falta ser admin) puede activar 2FA con TOTP desde /security — compatible con Google Authenticator, Authy, 1Password, o cualquier app que hable el estándar TOTP (RFC 6238). Es una capa extra sobre la contraseña: una vez activo, el login pide además un código de 6 dígitos.

Activación

1. El servidor genera un secreto (todavía no activo) y un código QR para escanear.
2. El usuario escanea el QR con su app autenticadora (o copia el secreto a mano si no puede escanear).
3. Confirma con un código real generado por la app — recién en ese momento queda activo de verdad. Un secreto generado pero nunca confirmado no habilita nada.
4. El servidor muestra 8 códigos de recuperación, una sola vez. Cada uno sirve para un único login — son la salida de emergencia si se pierde el teléfono con la app autenticadora.

Login con 2FA activo

El login pasa a ser de dos pasos: primero email + contraseña (esto no crea sesión todavía); si el usuario tiene 2FA activo, el servidor responde pidiendo el código en vez de loguear directo. Recién con un código válido (TOTP o de recuperación) se crea la sesión. Un código de recuperación usado se invalida al instante — no sirve una segunda vez.

curl -X POST /oauth/token -d grant_type=password \
  -d client_id=... -d client_secret=... \
  -d username=ana@example.com -d password=... \
  -d otp=123456 -d scope="users:read"

Cada activación, desactivación y regeneración de códigos queda registrada en el audit log (sección 7).

6. Analíticas: sesiones, logins y actividad

Pantalla de monitoreo para el admin: cada vez que Passport emite un access token (cualquier grant type) o alguien inicia sesión en el panel, queda un registro en login_events. Con eso se arman:

• KPIs: usuarios totales, sesiones activas (tokens OAuth vigentes, no revocados ni expirados), logins de hoy, logins de los últimos 7 días, tasa de fallos de login y tasa de aprobación OAuth (últimos 7 días).
• Logins por día (últimos 7/30/90 días, elegible arriba a la derecha): barras apiladas — logins de apps (OAuth) vs. logins al panel admin (sesión) — con tooltip al pasar el mouse sobre cada día.
• Logins por app: qué apps se usan más.
• Usuarios más activos: ranking por cantidad de logins en el período.
• Funnel de autorización OAuth: por cada cliente, cuántas veces se mostró la pantalla de consentimiento (/oauth/authorize), cuántas se aprobaron y cuántas se denegaron, con la tasa de aprobación resultante.
• Tokens activos por cliente: snapshot en vivo de tokens OAuth vigentes (no revocados, no expirados), agrupados por app.
• Uso de scopes: qué scopes (users:read, account:write, etc.) aparecen más entre los tokens emitidos en el período.
• Actividad reciente: tabla con los últimos eventos (usuario, app, tipo, IP, cuándo).

Misma info disponible por API: GET /api/analytics/summary?days=30 (scope users:read, requiere el permiso users.view — igual que el resto del panel admin).

7. Audit log: quién cambió qué

Pantalla de auditoría para el admin (/admin/audit-log): registra automáticamente los cambios que importan desde el punto de vista de seguridad/gobernanza — no hace falta activar nada, queda un renglón cada vez que ocurre alguno de estos eventos:

Cada evento guarda además quién lo hizo (o "(sistema)" si no hay actor), IP, y cuándo. Es filtrable por sujeto (Usuarios / Clientes OAuth) y por acción, y está paginado.

Requiere el permiso audit.view (nuevo — separado de users.* porque también cubre clientes OAuth, no solo usuarios). Se lo asigna automáticamente al rol admin. Misma info por API: GET /api/audit-log (scope users:read).

8. Roles, permisos y roles por app

Roles globales

Gobiernan el panel de administración de esta app (spatie/laravel-permission):

Roles por app

Independientes del rol global: un admin le puede asignar a cualquier usuario un rol (admin o user) específico de una app registrada, desde el panel de edición de usuario ("Roles por app"). Sirve para que, por ejemplo, un usuario sea admin dentro de la app Angular pero solo user dentro de la app NestJS — sin tocar su rol global.

Esa información viaja en la respuesta de la API (app_roles, ver sección 11): cada app ve únicamente el rol que ese usuario tiene en ella, resuelto automáticamente según el client_id del token usado en la request.

9. Idioma (español / inglés / catalán)

El selector está arriba a la derecha en la barra de navegación (ES / EN / CA). Cambiarlo hace un POST a /web-api/locale, guarda el idioma en la sesión y recarga la página — el servidor decide el idioma con el que renderiza esa carga (mensajes de validación/autenticación vía laravel-lang, más los textos propios de la app en lang/{es,en,ca}/messages.php).

La interfaz usa vue-i18n con diccionarios en resources/js/i18n/{es,en,ca}.js (168 claves cada uno). El locale de arranque del frontend se inyecta desde el servidor (window.__LOCALE__ en app.blade.php), así que la SPA nace ya en el idioma correcto sin parpadeo.

10. Cómo conectar tu app (Angular, NestJS, Flutter, etc.)

Paso 1 — Registrar la app

Desde /clients, crear un cliente OAuth eligiendo el grant type según el tipo de app:

Paso 2 — Login del usuario (Authorization Code + PKCE, ej. Angular)

Redirigir el navegador a:

GET /oauth/authorize
    ?client_id={client_id}
    &redirect_uri={tu_callback}
    &response_type=code
    &scope=users:read users:write
    &state={valor_random}
    &code_challenge={challenge_pkce}
    &code_challenge_method=S256

El usuario loguea (o ya tiene sesión) y aprueba el acceso. Passport redirige a redirect_uri con ?code=...&state=....

Paso 3 — Canjear el código por un token

curl -X POST http://localhost:8000/oauth/token \
  -d grant_type=authorization_code \
  -d client_id={client_id} \
  -d code={code} \
  -d redirect_uri={tu_callback} \
  -d code_verifier={verifier_pkce}

Alternativa — Client Credentials (ej. NestJS backend-a-backend)

curl -X POST http://localhost:8000/oauth/token \
  -d grant_type=client_credentials \
  -d client_id={client_id} \
  -d client_secret={client_secret} \
  -d scope="users:read"

11. API REST completa: construí tu propio panel admin

Todo lo que hace la SPA Vue por sesión también está disponible por token OAuth2. Esto significa que un cliente Angular, Flutter, o lo que sea, puede ser un admin completo — no solo consultar usuarios — sin depender de la sesión de Laravel. Todos los endpoints requieren Authorization: Bearer {access_token}.

Usuarios y roles (scopes users:read / users:write)

Ejemplo de respuesta de usuario

{
  "id": 2,
  "name": "Carla Gómez",
  "email": "carla@example.com",
  "is_active": true,
  "roles": ["user"],
  "app_roles": ["admin"],
  "created_at": "2026-07-25T08:52:39.000000Z"
}

roles es el rol global; app_roles es el rol de ese usuario específicamente en la app dueña del token usado para la request (útil para que cada app decida qué mostrar/permitir sin tener su propio sistema de permisos). El campo deleted_at solo aparece (no-null) en las respuestas de /api/users/trashed.

Cuenta propia: clientes, tokens y apps autorizadas (scopes account:read / account:write)

Equivalente por token a /web-api/clients, /personal-access-tokens y /authorized-apps de la sección 4 — siempre sobre el usuario dueño del token (no aplica a client_credentials, que no tiene usuario asociado):

Scopes disponibles

No hay scope por defecto: cada app debe pedir explícitamente los que necesita al iniciar el flujo OAuth (ej. scope=users:read users:write account:read account:write para un admin completo).

12. Webhooks: enterate sin hacer polling

Cada cliente OAuth puede registrar uno o más endpoints webhook desde /clients → botón "Webhooks" (o por API, sección 11). Cuando pasa algo relevante para ese cliente, este servidor le manda un POST con el evento — no hace falta consultar la API cada tanto para enterarse.

Eventos disponibles

Con token.revoked tu app se entera al instante de que ya no tiene acceso a la cuenta de ese usuario (por ejemplo, para cerrarle la sesión local), en vez de esperar a que el token expire solo.

URLs permitidas

Verificar la firma

Cada entrega incluye el header X-Webhook-Signature: sha256={firma}, un HMAC-SHA256 del body crudo (JSON) usando el secret que se te mostró al crear el webhook (una sola vez, igual que un client_secret — si lo perdiste, borrá el webhook y creá uno nuevo). Verificalo antes de confiar en el payload:

// Node.js
import crypto from 'crypto';

function isValid(rawBody: string, signatureHeader: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

El body tiene forma {"event": "token.revoked", "data": {...}}. El header X-Webhook-Event repite el nombre del evento, por si preferís ramificar por header sin parsear el body.

Reintentos

Historial de entregas y reintento manual

El botón "Ver historial" de cada webhook (junto a Pausar/Borrar) abre el listado paginado de todas las entregas — no solo la última. Cada fila muestra el código de respuesta (o "pendiente" si nunca respondió), el evento, cuándo se creó y cuántos intentos acumula. Las entregas que no llegaron a un 2xx tienen un botón "Reintentar": vuelve a encolar el mismo registro (no crea uno nuevo — el contador de intentos sigue acumulando sobre esa entrega) para forzar un envío inmediato sin esperar al backoff automático. Útil después de arreglar algo en tu endpoint y no querer esperar los 5 minutos del backoff.

Cada alta y baja de un webhook queda en el audit log (sección 7): client.webhook_created / client.webhook_deleted.

13. Documentación interactiva (Swagger)

Disponible en http://localhost:8000/api/documentation. Incluye el botón Authorize para probar los tres flujos (Authorization Code, Client Credentials, Password) directamente desde el navegador, usando el cliente de ejemplo "Swagger UI" sembrado (sección 3).

El JSON crudo de la especificación OpenAPI está en /docs.

14. Referencia rápida de rutas

Interfaz web (sesión, uso interno de esta app)

OAuth2 (Passport)

API REST (Bearer token, para apps externas — Angular, Flutter, lo que sea)