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.Analíticas: sesiones, logins y actividad
• 6.Roles, permisos y roles por app
• 7.Idioma (español / inglés / catalán)
• 8.Cómo conectar tu app (Angular, NestJS, Flutter, etc.)
• 9.API REST completa: construí tu propio panel admin
• 10.Documentación interactiva (Swagger)
• 11.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).

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.

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.

Analíticas (solo admins)

/admin/analytics — ver sección 5.

5. 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 y de los ú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.
• 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).

6. 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 8): 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.

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

8. 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"

9. 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).

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

11. 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)