Saltar a contenido

0048. Autorización con dos tokens para la administración global de empresas

Estado: Aceptado Fecha: 2026-10-21 Módulos afectados: app/api/deps.py, app/domains/catalogos/, app/domains/empresas/, app/domains/usuarios/, app/main.py

Contexto

La aplicación React utiliza un token de acceso tenant con empresa_id y necesita GET /api/v1/auth/empresas para listar las empresas relacionadas con el usuario autenticado. El panel administrativo Vue opera globalmente y no debe seleccionar ni inventar una empresa para autenticarse. Por lo tanto, su token tiene scope=admin, tipo_usuario=root y no contiene empresa_id.

El recurso global /api/v1/empresas no debe convertirse en una forma alternativa para que un usuario normal enumere empresas o evite el endpoint de relaciones. Las cuatro listas de catálogos globales son datos de referencia que necesitan ambos frontends.

Decisión

El servicio conserva dos dependencias de autorización explícitas:

Token Claims requeridos Superficie permitida
Normal/tenant Claims de identidad válidos y empresa_id CRUD tenant y GET /api/v1/auth/empresas; este último obtiene la identidad desde el token y devuelve las empresas relacionadas activas (todas las empresas activas para root en el flujo normal)
Admin/global Identidad válida, tipo_usuario=root, scope=admin; empresa_id está ausente Listado, detalle, creación, actualización y eliminación lógica global de empresas para el panel Vue

get_current_user permanece sin cambios para el flujo React. get_admin_user es reutilizable y devuelve 401 cuando faltan credenciales o son inválidas, y 403 cuando un token válido no es un token administrativo de root. Las rutas globales de empresas utilizan la dependencia administrativa y una sesión sin RLS tenant. Las rutas anidadas de aplicaciones de una empresa conservan explícitamente la autenticación normal.

El cliente no puede elegir la identidad de autorización mediante una ruta, parámetro de consulta o cuerpo de la solicitud. La identidad root proviene únicamente del token administrativo verificado.

Los demás servicios deben validar, para cada referencia a una empresa, que la empresa exista, esté activa y sea accesible para el solicitante o según la política del servicio. Esta unidad de trabajo documenta ese contrato y proporciona la protección reutilizable del token; no reescribe esos servicios.

Las lecturas de catálogos globales (paises, provincias, ciudades y tipos-identificacion) utilizan una dependencia de lectura reutilizable separada. Esta acepta un token normal válido o un token válido con scope=admin, tipo_usuario=root, y utiliza una sesión de base de datos sin ámbito tenant porque estas listas son datos de referencia globales. Las escrituras de catálogos y los endpoints de catálogos con ámbito tenant permanecen protegidos por la autenticación normal.

Matriz de permisos

Operación Token normal Token admin/root Sin token o token inválido
GET /api/v1/auth/empresas Permitido por la relación del usuario Permitido por el flujo normal de root 401
GET /api/v1/empresas y GET /{empresa_id} 403 Permitido 401
POST, PUT, DELETE /api/v1/empresas 403 Permitido 401
Rutas de aplicaciones de empresa Permitidas únicamente mediante el contexto autenticado normal No sustituye al contexto tenant 401

Consecuencias

Las dos superficies de autorización no pueden mezclarse accidentalmente: un token administrativo es rechazado por get_current_user, mientras que un token normal es rechazado por la protección del CRUD global de empresas. El listado de relaciones de empresas continúa disponible para React sin exponer el CRUD global como sustituto.