Operación, auditoría y límites conocidos

Esta referencia reúne las reglas operativas que deben conservarse al modificar Summit Auth.

Mapa del panel administrativo

Sección	Responsabilidad
Aplicaciones	Clientes OpenIddict, redirect URIs, scopes, PKCE y requisitos de acceso.
Scopes	Scopes OAuth disponibles.
Usuarios	Cuentas Identity, perfil, roles, claims y accesos.
Roles	Roles Identity y permisos asignados.
Autorizaciones	Consentimientos persistentes del usuario.
Tokens	Consulta y revocación de tokens emitidos.
Accesos por producto	Otorgamientos directos de ProductAccess.
Facturación	Productos, aplicaciones asociadas, funcionalidades, planes, suscripciones y organizaciones.
Definiciones de claims	Catálogo y destinos de claims.
Permisos de sistema	Subjects, acciones y definiciones de permisos.
Auditoría	Consulta de eventos administrativos y de seguridad.

La portada usa AdminOnly. Cada sección protegida utiliza permisos granulares de SummitPermissions; el rol Admin funciona como bypass central en el provider de autorización.

Auditoría

AuditLogger escribe eventos estructurados en serilog_logs. Un evento puede contener:

• eventType estable;
• entityType y entityId;
• resumen legible;
• valores anteriores y nuevos estrictamente necesarios.

Toda operación administrativa o privilegiada debe auditarse después de que la escritura haya tenido éxito. Las operaciones idempotentes no deben producir un nuevo evento cuando no hubo cambio efectivo.

Peligro

Nunca incluyas contraseñas, secretos de cliente, access tokens, refresh tokens, códigos de autorización, códigos de recuperación ni credenciales de proveedores en summary, oldValues o newValues.

AuditValueRedactor protege la representación de valores sensibles en la vista de detalle. No modifica la fila almacenada y no corrige un payload inseguro ya registrado.

Formatos de error

Los endpoints OAuth usan la semántica de errores de OAuth/OpenID Connect. Las APIs internas devuelven respuestas JSON propias, normalmente con { "message": "..." }. No mezcles ambos contratos al agregar endpoints.

Los endpoints de organizaciones usan 404 tanto para recursos inexistentes como para recursos fuera del alcance del caller. Esta decisión evita enumerar organizaciones o suscripciones ajenas.

Límites y precauciones actuales

Policies dinámicas

Una constante de SummitPermissions debe corresponder a una definición activa. Verifica catálogo, resource y scope al agregar una policy.

Claims configurables

ClaimDefinitions controla destinos de muchos claims. Cambiar EmitInAccessToken o EmitInIdentityToken modifica un contrato consumido por otras aplicaciones. Los permisos extensos deben permanecer en UserInfo para evitar tokens sobredimensionados.

PKCE

La configuración por cliente y los requisitos registrados en OpenIddict son la fuente de verdad. No asumas que todos los clientes tienen la misma exigencia; verifica el descriptor antes de cambiar un flujo.

Modelo efectivo de acceso

ProductAccess no conserva toda la procedencia. Para decidir si un acceso es personal u organizacional, consulta ProductAccessAssignment. Al modificar la reconciliación, conserva el orden de prioridad entre asignaciones.

Funcionalidades resueltas en vivo

Las funcionalidades no se copian a cada suscripción. Se leen desde BillingPlanFeature; un cambio del plan afecta respuestas posteriores. Evalúa compatibilidad antes de retirar o renombrar una key consumida por aplicaciones.

Superficie interna

El prefijo /api/internal es una convención, no una barrera de red. La seguridad real depende de OpenIddict Validation y de api.billing.sync o api.productaccess.sync. Conserva también validación, idempotencia, rate limits aplicables y auditoría segura.