Control de acceso y límites de seguridad

Desarrolla las claves API, las redes de origen, los ámbitos de permisos, la protección contra ataques de repetición y la protección de registros, y define reglas de autorización con denegación por defecto.

5. Modelo de identidad, API Key y autorización

5.1 Formato de credenciales de API Key

El cliente transmite las credenciales mediante el encabezado de solicitud Authorization y el nombre del esquema de autenticación es ApiKey. La credencial consta de un Key ID público y un Secret aleatorio de 256 bits. El Key ID público sirve para localizar el registro y el Secret para demostrar posesión.

Requisitos de seguridad:

1. El Secret se genera con una fuente aleatoria criptográficamente segura, con una entropía no inferior a 256 bits.
2. El Secret se muestra una sola vez, en la respuesta correcta de creación o rotación.
3. El servidor no conserva Secret en texto claro; calcula un resumen HMAC-SHA-256 del Secret mediante un Pepper protegido por KMS y conserva el resumen junto con pepper_version.
4. La comparación de resúmenes debe utilizar un algoritmo de tiempo constante.
5. El gateway, WAF, APM y los registros de aplicación deben ocultar de forma unificada el encabezado Authorization.
6. Producción y entornos que no son de producción usan Key distintas; la entrada de solicitud, la Key, la ruta y el endpoint de backend deben pertenecer al mismo entorno, y se rechaza cualquier combinación entre entornos.
7. La rotación de Pepper se utiliza únicamente para versiones de Secret de nueva emisión; el Pepper anterior permanece disponible en modo de solo lectura hasta que todas las versiones de Secret correspondientes dejen de ser válidas. Está prohibido recalcular o invalidar masivamente resúmenes existentes durante la rotación.

5.2 Scope de permisos

Los permisos utilizan una identificación explícita de tres niveles: plataforma, recurso y operación. Los ejemplos iniciales son:

La lista real de recursos y operaciones debe publicarse después de que los responsables de cada plataforma la confirmen elemento por elemento. Las reglas de autorización son las siguientes:

1. Toda ruta accesible debe declarar un required scope explícito.
2. La API Key debe poseer ese required scope; no puede depender de coincidencia por prefijo ni de permisos comodín implícitos.
3. Una ruta nueva no puede publicarse si no tiene un required scope vinculado.
4. Los cambios de Scope deben generar una nueva versión de configuración y quedar registrados en auditoría.
5. Una API Key puede poseer explícitamente Scope de varias plataformas.

5.3 Vinculación entre API Key e IP

La granularidad de la vinculación debe ser la API Key, no el comerciante. Una Key puede vincularse a varias direcciones IPv4, direcciones IPv6 o redes CIDR explícitas; una IP solo puede utilizarse con una Key después de estar explícitamente vinculada a ella.

Como ejemplo, un mismo comerciante posee Key A, Key B, IP A e IP B; la matriz de autorización es la siguiente:

Reglas concretas:

1. No se permite aplicar automáticamente una lista de IP de nivel de comerciante a todas las Key de ese comerciante.
2. Una misma IP puede utilizarse con varias Key, pero cada conjunto de vinculaciones debe crearse y auditarse por separado.
3. IPv4, IPv6 y CIDR deben normalizarse al escribirse. La configuración de autoservicio predeterminada solo permite IPv4 /32 e IPv6 /128; IPv4 de /29 a /31 e IPv6 de /64 a /127 requieren una razón de negocio y aprobación de dos personas; IPv4 menor que /29 o IPv6 menor que /64 se rechaza siempre.
4. El plano de datos solo confía en la IP del cliente transmitida por el balanceador de carga perimetral; ningún valor X-Forwarded-For procedente de una solicitud pública puede utilizarse directamente como base de autorización.
5. La capa perimetral debe sobrescribir los encabezados de reenvío proporcionados por el cliente y transmitir la IP original al gateway mediante una red de confianza o PROXY Protocol.
6. Si la IP de origen no puede determinarse con fiabilidad, se rechaza por defecto; no se permite degradar a una validación que solo compruebe la API Key.
7. Cuando un comerciante utiliza IP de salida dinámica o NAT de terceros, debe completar primero una solución de salida fija o red privada; no se puede resolver relajando la política hasta un CIDR a escala de Internet.
8. Está prohibido guardar redes duplicadas o contenidas entre sí bajo la misma Key; cuando una nueva vinculación se solapa con una red existente, el plano de control debe rechazarla y exigir primero el reemplazo atómico del conjunto de vinculaciones.

5.4 Ciclo de vida de la Key

Los estados de API Key incluyen pending, active, suspended, revoked y expired.

1. Creación: tras validar comerciante, entorno, Scope y vinculación IP, se genera la Key y el Secret solo se muestra una vez.
2. Activación: una Key de producción con altos privilegios pasa de pending a active después de la aprobación.
3. Rotación: se crea una nueva versión de Secret para la misma Key lógica; por defecto se permiten en paralelo las versiones nueva y anterior durante 24 horas y luego la versión anterior se invalida automáticamente.
4. Suspensión: se utiliza para la gestión de riesgos a corto plazo y puede ser revertida por un administrador autorizado.
5. Revocación: es irreversible y debe propagarse con rapidez a todas las regiones.
6. Vencimiento: se rechaza automáticamente después de llegar a expires_at.

Se recomienda que una Key de producción tenga una vigencia máxima de 180 días y notificar al responsable 30 días, 14 días, 7 días y 1 día antes del vencimiento. Este ciclo es una recomendación de seguridad que debe confirmar el equipo de seguridad y operaciones de comerciantes.

5.5 Protección contra repetición de solicitudes

Una API Key estática es esencialmente una credencial Bearer. TLS y la vinculación IP a nivel de Key pueden reducir el riesgo de filtración y repetición remota, pero no pueden impedir la repetición tras el robo de credenciales en una red de salida confiable, un punto de terminación TLS o una cadena de registros.

El primer corte vertical de solo lectura puede usar TLS, API Key y vinculación IP después de que el equipo de seguridad acepte explícitamente el riesgo. Antes de exponer cualquier ruta de producción de tipo payment.submit, se debe cumplir una de las dos opciones siguientes:

1. El comerciante utiliza mTLS, se crea una vinculación explícita entre el certificado del cliente y la API Key, y se ejecuta la comprobación de revocación del certificado.
2. El comerciante utiliza una clave privada Ed25519 independiente para firmar el método de solicitud, ruta normalizada, SHA-256 del cuerpo de solicitud, marca de tiempo UTC, Nonce aleatorio, Idempotency-Key y API Key ID; el gateway conserva la clave pública, la desviación de reloj permitida es de 5 minutos y un Nonce no puede repetirse en 10 minutos.

La clave privada de firma de solicitudes la conserva el comerciante y el gateway no debe recibirla ni almacenarla. El estado de Nonce se conserva en una caché de seguridad entre las regiones donde se permite la conmutación de escrituras; si ese estado no está disponible y no se ha verificado la capacidad de idempotencia global del backend, las solicitudes de escritura de pagos fallan en modo cerrado. Que TLS termine en WAF o pase al gateway es una decisión de despliegue, pero con cualquiera de las dos opciones todos los puntos de terminación deben ocultar credenciales en los registros y estar sujetos a control de mínimo privilegio.

5.6 Centro de control de acceso

El centro de control de acceso es la unión lógica de "servicio de validación de API Key + ejecución de política de permisos de API Gateway", no un nuevo servicio monolítico. El servicio de validación solo confirma credencial, estado, entorno y vinculación Key-IP, y devuelve identidad y Scope; la política de gateway decide después la visibilidad de la ruta y el required scope. Antes de que se complete la autenticación, puede conservarse temporalmente el resultado de coincidencia de ruta, pero no se puede devolver una respuesta diferente basándose en él.

La instantánea regional no es un módulo de autorización independiente; la produce la cadena de publicación de la sección 10.1 y el servicio de validación y la política del gateway la leen dentro de la región. Una instantánea vencida, una versión que no puede confirmarse o una Key desconocida fallan en modo cerrado. Los elementos de denegación break-glass se unen a la configuración central y solo pueden restringir acceso; no pueden restaurar una Key ni ampliar Scope.

11. Diseño de seguridad

1. Los enlaces externos usan como mínimo TLS 1.2 y preferiblemente TLS 1.3; los servicios internos usan mTLS.
2. El Pepper de KMS y las claves internas de firma se aíslan por entorno, región y propósito. La rotación de Pepper conserva la versión anterior según la sección 5.1 hasta que todos los Secret que la referencian hayan vencido.
3. Los administradores usan tokens de identidad de corta duración y roles de mínimo privilegio; no utilizan API Key de comerciantes para invocar interfaces administrativas.
4. Se auditan creación de Key, elevación de Scope, ampliación de red IP, publicación de ruta y cambios del interruptor de escritura interregional.
5. El gateway sobrescribe identidad de comerciante, permisos, región de origen y encabezados de trazado interno recibidos del exterior para evitar su falsificación.
6. El tamaño de cuerpo de solicitud, número de Header, longitud de ruta, número de conexiones y concurrencia tienen límites explícitos.
7. La limitación de tasa contiene al menos las cuatro dimensiones de IP de origen, API Key, comerciante y plataforma, y admite bloqueo de emergencia.
8. Los registros de acceso no guardan Authorization, Cookie, datos de tarjetas de pago, información de cuenta bancaria ni cuerpo completo de solicitud.
9. La IP de origen de los registros se gobierna como dato sensible: se limita el permiso de consulta y se establece un período de retención.
10. Se realiza una revisión trimestral de permisos de Key, un ejercicio semestral de fallo interregional y un ejercicio semestral de filtración de API Key.

Se recomienda completar un modelo de amenazas STRIDE durante el diseño detallado, con foco en encabezados reenviados falsificados, enumeración de Key, filtración de Secret, envenenamiento de caché, reversión de configuración, ataques de repetición, escritura duplicada entre regiones y falsificación de encabezados internos de identidad.