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.