Seguridad - Lerian

Matcher implementa controles de seguridad integrales para proteger los datos de conciliación financiera. Esta guía cubre autenticación, autorización, aislamiento de inquilinos, cifrado y características de cumplimiento.

Descripción general

La arquitectura de seguridad de Matcher está construida en varias capas. Cada solicitud de API pasa por múltiples puntos de control de seguridad antes de llegar a sus datos.

Primero, TLS cifra la conexión.

Luego la autenticación verifica quién es usted:

El aislamiento de inquilinos asegura que solo vea sus propios datos.
RBAC verifica si tiene permiso para realizar la acción.

Finalmente, el sistema registra todo para propósitos de auditoría.

Protección por capas

Capa	Protección
Transporte	Cifrado TLS 1.2+
Autenticación	Tokens JWT vía lib-auth
Aislamiento de inquilinos	PostgreSQL con esquema por inquilino
Autorización	Control de acceso basado en roles
Auditoría	Logs inmutables de solo anexión
Almacenamiento	Cifrado en reposo

Autenticación

Matcher usa la biblioteca compartida lib-auth (v2) para autenticación, soportando control de acceso basado en JWT con firma HMAC.

Configuración

Tres variables de entorno controlan la autenticación:

Variable	Requerida	Descripción
`AUTH_ENABLED`	Sí	Habilitar o deshabilitar la autenticación (`true`/`false`)
`AUTH_SERVICE_ADDRESS`	Cuando auth está habilitado	Dirección del servicio de autorización externo
`AUTH_JWT_SECRET`	Cuando auth está habilitado	Secreto compartido para la verificación de firma de tokens HMAC

Cuando AUTH_ENABLED=false (solo desarrollo), Matcher usa un ID de inquilino predeterminado (11111111-1111-1111-1111-111111111111) y omite las verificaciones de autorización.

Estructura del token JWT

Matcher valida JWTs firmados con algoritmos HMAC (HS256, HS384, HS512). El token debe incluir claims de identificación de inquilino:

{
  "sub": "user_123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "tenant_slug": "acme-corp",
  "iat": 1705749600,
  "exp": 1705753200,
  "nbf": 1705749600
}

Claim	Requerido	Descripción
`tenant_id` o `tenantId`	Sí	UUID del inquilino para aislamiento de esquema
`tenant_slug` o `tenantSlug`	No	Identificador legible del inquilino
`sub`	No	ID de usuario (usado para registro de auditoría)
`exp`	Sí	Tiempo de expiración del token
`nbf`	No	Tiempo not-before (el token es inválido antes de este momento)

Encabezados requeridos

Todas las solicitudes de API deben incluir autenticación:

curl -X GET "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN"

Validación de token

Matcher valida los tokens en cada solicitud:

Verificación de firma: Valida la firma HMAC usando el secreto compartido configurado
Verificación de expiración: Rechaza tokens expirados (claim exp)
Verificación de not-before: Rechaza tokens usados antes de su tiempo nbf
Extracción de inquilino: Extrae tenant_id para aislamiento de esquema

Autorización (RBAC)

El control de acceso basado en roles protege todos los endpoints de API. Matcher delega la autorización a un servicio de auth externo vía lib-auth. Los permisos son granulares y siguen el patrón resource:sub-resource:action.

Estructura de permisos

<resource>:<sub-resource>:<action>

Ejemplos:

configuration:context:create — Crear contextos de conciliación
matching:job:run — Ejecutar trabajos de coincidencia
exception:exception:resolve — Resolver excepciones

Lista completa de permisos

Matcher define seis dominios de recursos. Cada endpoint requiere un permiso específico verificado contra el servicio de autorización externo.

Configuration

Permiso	Descripción
`configuration:context:create`	Crear contextos de conciliación
`configuration:context:read`	Ver contextos
`configuration:context:update`	Actualizar contextos
`configuration:context:delete`	Eliminar contextos
`configuration:source:create`	Crear fuentes de datos
`configuration:source:read`	Ver configuración de fuente
`configuration:source:update`	Modificar configuración de fuente
`configuration:source:delete`	Eliminar fuentes de datos
`configuration:field-map:create`	Crear mapeos de campos
`configuration:field-map:read`	Ver mapeos de campos
`configuration:field-map:update`	Actualizar mapeos de campos
`configuration:field-map:delete`	Eliminar mapeos de campos
`configuration:rule:create`	Crear reglas de coincidencia
`configuration:rule:read`	Ver reglas de coincidencia
`configuration:rule:update`	Actualizar reglas de coincidencia
`configuration:rule:delete`	Eliminar reglas de coincidencia
`configuration:fee-schedule:create`	Crear cronogramas de tarifas
`configuration:fee-schedule:read`	Ver cronogramas de tarifas
`configuration:fee-schedule:update`	Actualizar cronogramas de tarifas
`configuration:fee-schedule:delete`	Eliminar cronogramas de tarifas
`configuration:schedule:create`	Crear programaciones
`configuration:schedule:read`	Ver programaciones
`configuration:schedule:update`	Actualizar programaciones
`configuration:schedule:delete`	Eliminar programaciones

Ingestion

Permiso	Descripción
`ingestion:import:create`	Cargar archivos de transacciones
`ingestion:job:read`	Ver trabajos de importación y detalles de transacciones
`ingestion:transaction:ignore`	Marcar transacciones como ignoradas
`ingestion:transaction:search`	Buscar transacciones

Matching

Permiso	Descripción
`matching:job:run`	Ejecutar ejecuciones de coincidencia
`matching:job:read`	Ver resultados de ejecuciones de coincidencia y grupos
`matching:job:delete`	Eliminar grupos de coincidencia (deshacer coincidencia)
`matching:adjustment:create`	Crear entradas de ajuste

Exception

Permiso	Descripción
`exception:exception:read`	Ver excepciones e historial
`exception:exception:resolve`	Forzar coincidencia o ajustar entradas
`exception:exception:dispatch`	Despachar excepciones a sistemas externos
`exception:callback:process`	Procesar callbacks de webhooks externos
`exception:dispute:read`	Ver disputas
`exception:dispute:write`	Crear disputas, cerrar disputas, enviar evidencia
`exception:comment:write`	Agregar o eliminar comentarios en excepciones

Governance

Permiso	Descripción
`governance:audit:read`	Ver logs de auditoría
`governance:archive:read`	Ver y descargar archivos
`governance:actor-mapping:read`	Ver mapeos de actores
`governance:actor-mapping:write`	Crear o actualizar mapeos de actores
`governance:actor-mapping:delete`	Eliminar mapeos de actores

Reporting

Permiso	Descripción
`reporting:dashboard:read`	Acceder a analíticas y métricas del dashboard
`reporting:export:read`	Ver y exportar reportes (coincidentes, no coincidentes, resumen, varianza)
`reporting:export-job:write`	Crear y cancelar trabajos de exportación
`reporting:export-job:read`	Ver estado de trabajos de exportación y descargar exportaciones

Gestión de roles

El servicio de autorización externo gestiona los roles, no Matcher en sí. Configure los roles y sus permisos asociados en su proveedor de identidad o servicio de auth. Matcher verifica los permisos en cada solicitud llamando al servicio de auth con el recurso y la acción requeridos.

Aislamiento de inquilinos

Matcher usa aislamiento de esquema por inquilino en PostgreSQL, proporcionando una fuerte separación de datos entre inquilinos.

Cómo funciona

Cuando llega una solicitud, Matcher extrae el ID del inquilino del token JWT (nunca de parámetros de consulta o encabezados que usted controla). Luego establece la conexión de base de datos para usar el esquema de ese inquilino vía SET LOCAL search_path, por lo que cada consulta se ejecuta en completo aislamiento.

Incluso si existiera un bug en la capa de aplicación, la base de datos impone la separación. El aislamiento de esquema se aplica por transacción para prevenir contaminación del pool de conexiones.

Detalles de implementación

ID de inquilino solo desde JWT: Nunca aceptado desde parámetros de solicitud
Selección automática de esquema: Aplicado vía auth.ApplyTenantSchema()
Aislamiento por transacción: Usa SET LOCAL search_path para delimitar cada transacción de base de datos
Sin acceso entre inquilinos: La base de datos impone el aislamiento

Garantías de aislamiento

Garantía	Implementación
Aislamiento de datos	Esquemas PostgreSQL separados
Alcance de consultas	`SET LOCAL search_path` por transacción
Sin suplantación de inquilino	Inquilino solo desde JWT
Separación de auditoría	Tablas de auditoría por inquilino

Pista de auditoría

Matcher registra todas las acciones en un log de auditoría inmutable de solo anexión para cumplimiento y análisis forense.

Eventos auditados

Categoría	Eventos
Acceso a datos	Ver coincidencias, ver excepciones, exportar datos
Modificación de datos	Crear coincidencia, resolver excepción, actualizar reglas
Configuración	Crear contexto, modificar fuente, cambiar configuración

Consultar logs de auditoría

Use los endpoints de logs de auditoría de gobernanza para recuperar registros de auditoría:

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs" \
 -H "Authorization: Bearer $TOKEN"

Referencia de API: Listar logs de auditoría

Mapeos de actores y privacidad

Los mapeos de actores asocian identificadores del sistema (como los claims sub de JWT) con nombres legibles y direcciones de correo electrónico. Esto mejora la legibilidad de los logs de auditoría sin almacenar datos personales en cada entrada de log.

Gestionar mapeos de actores

cURL

curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "display_name": "John Doe",
   "email": "john.doe@company.com"
 }'

Referencia de API: Upsert de mapeo de actor | Obtener mapeo de actor | Eliminar mapeo de actor

Para cumplir con las solicitudes de derecho al olvido, pseudonimice un actor para reemplazar sus datos personales con [REDACTED]. Esta acción es irreversible.

cURL

curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123/pseudonymize" \
 -H "Authorization: Bearer $TOKEN"

Referencia de API: Pseudonimizar actor

Archivos de logs de auditoría

Los logs de auditoría históricos se comprimen periódicamente y se mueven a almacenamiento a largo plazo. Use los endpoints de archivos para listar y descargar datos archivados para revisiones de cumplimiento.

cURL

curl -X GET "https://api.matcher.example.com/v1/governance/archives" \
 -H "Authorization: Bearer $TOKEN"

Referencia de API: Listar archivos | Descargar archivo

Cifrado de datos

Cifrado en tránsito

TLS cifra todos los datos transmitidos hacia y desde Matcher.

Requisito	Configuración
Protocolo	TLS 1.2 o superior
Suites de cifrado	Solo cifrados fuertes
Certificado	Certificado válido firmado por CA
HSTS	Habilitado con max-age de 1 año

Cifrado en reposo

Tipo de datos	Método de cifrado
Base de datos	PostgreSQL TDE (Transparent Data Encryption)
Almacenamiento de archivos	Cifrado AES-256
Respaldos	Cifrados antes de almacenamiento
Secretos	Vault con cifrado de sobre

Cumplimiento SOX

Matcher mantiene registros para los requisitos de auditoría SOX (Sarbanes-Oxley).

Características de control SOX

Control	Característica de Matcher
Segregación de funciones	RBAC con permisos granulares
Gestión de cambios	Pista de auditoría para todos los cambios de configuración
Control de acceso	Autenticación JWT con aplicación de roles
Pista de auditoría	Logs inmutables de solo anexión
Integridad de datos	Checksums y validación de transacciones

Seguridad de API

Limitación de tasa

Algunos endpoints incluyen limitación de tasa adicional para proteger contra abuso:

Tipo de endpoint	Limitación de tasa
Despacho de excepciones	Sí
Endpoints de exportación	Sí
Procesamiento de callbacks	Sí

Protección SSRF

Matcher bloquea las solicitudes HTTP salientes a rangos de IP privados al despachar excepciones a sistemas externos. Esto previene ataques de Server-Side Request Forgery (SSRF). Los rangos bloqueados incluyen 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 y equivalentes IPv6.

Verificación de firma de webhooks

Matcher firma los payloads de webhooks salientes con HMAC-SHA256 usando un secreto compartido. La firma aparece en el encabezado X-Signature-256, permitiendo a los receptores verificar la autenticidad.

Mejores prácticas

Use acceso de mínimo privilegio

Otorgue a los usuarios solo los permisos que necesitan. Comience con acceso mínimo y agregue permisos según sea necesario.

Rote credenciales regularmente

Implemente rotación automática para credenciales de servicio y secretos JWT. Use tokens de corta duración cuando sea posible.

Habilite el registro de auditoría

Mantenga los logs de auditoría habilitados y revíselos regularmente. Configure alertas para actividad sospechosa.

Use limitación de tasa

Mantenga los límites de tasa predeterminados habilitados para proteger contra abuso. Ajuste los umbrales según los patrones de tráfico esperados.

Revise el acceso regularmente

Realice revisiones periódicas de acceso. Elimine el acceso rápidamente cuando los usuarios cambien de rol o se vayan.

Verifique firmas de webhooks

Siempre valide las firmas HMAC-SHA256 en los payloads de webhooks para confirmar que se originan de Matcher.

Monitoree eventos de seguridad

Configure monitoreo y alertas en tiempo real para eventos de seguridad. Investigue anomalías de inmediato.

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

​Descripción general

​Protección por capas

​Autenticación

​Configuración

​Estructura del token JWT

​Encabezados requeridos

​Validación de token

​Autorización (RBAC)

​Estructura de permisos

​Lista completa de permisos

​Configuration

​Ingestion

​Matching

​Exception

​Governance

​Reporting

​Gestión de roles

​Aislamiento de inquilinos

​Cómo funciona

​Garantías de aislamiento

​Pista de auditoría

​Eventos auditados

​Consultar logs de auditoría

​Mapeos de actores y privacidad

​Gestionar mapeos de actores

​Pseudonimización GDPR

​Archivos de logs de auditoría

​Cifrado de datos

​Cifrado en tránsito

​Cifrado en reposo

​Cumplimiento SOX

​Características de control SOX

​Seguridad de API

​Limitación de tasa

​Protección SSRF

​Verificación de firma de webhooks

​Mejores prácticas

​Próximos pasos

Reglas de coincidencia

Enrutamiento de excepciones

Descripción general

Protección por capas

Autenticación

Configuración

Estructura del token JWT

Encabezados requeridos

Validación de token

Autorización (RBAC)

Estructura de permisos

Lista completa de permisos

Configuration

Ingestion

Matching

Exception

Governance

Reporting

Gestión de roles

Aislamiento de inquilinos

Cómo funciona

Garantías de aislamiento

Pista de auditoría

Eventos auditados

Consultar logs de auditoría

Mapeos de actores y privacidad

Gestionar mapeos de actores

Pseudonimización GDPR

Archivos de logs de auditoría

Cifrado de datos

Cifrado en tránsito

Cifrado en reposo

Cumplimiento SOX

Características de control SOX

Seguridad de API

Limitación de tasa

Protección SSRF

Verificación de firma de webhooks

Mejores prácticas

Próximos pasos