API Gateway: архитектура и безопасность

TL;DR

API-шлюз — это единственная точка политики (authz, rate, трансформации, аудит) и граница доверия между внешним миром и сервисами. Успех дают: Zero-Trust (mTLS/JWT), policy-as-code, SLO-ориентированное управление трафиком и ортогональная наблюдаемость. Стройте: edge gateway → BFF → service mesh; держите версионирование и фича-флаги; автоматизируйте защиту вебхуков и ключей; тестируйте канареечные релизы.

1) Роли и паттерны размещения

Edge/API Gateway (north-south): внешняя граница. Termination TLS, WAF, DDoS, authN/Z, rate/quotas, CORS, трансформации, кэш, webhooks.
BFF (Backend-for-Frontend): слой адаптации под конкретные клиенты (web/mobile/partners). Схемы, агрегации, лимиты, кеширование ответов.
Internal Gateway (east-west) / Service Mesh Ingress: внутренняя авторизация сервис-к-сервису, mTLS, политик-роутинг.
gRPC/REST/GraphQL шлюз: единая точка протокольного транслятора и схем-валидатора.

Анти-паттерны: «все через один монолитный шлюз без изоляции сред», «скрытая бизнес-логика в плагинах», «ручное правление правилами».

2) Модель доверия и аутентификация

TLS 1.2+/1.3 на периметре, HSTS на публичных доменах; внутри — mTLS между шлюзом и сервисами.
OAuth2/OIDC: Authorization Code (PKCE) для клиентов; client-credentials для серверных интеграций; JWT с коротким TTL и ротацией ключей (JWKS).
HMAC-подписи для партнерских интеграций и вебхуков (ключ на клиента, SHA-256/512, проверка таймштампа и анти-replay).
API-ключи — только как доп. фактор/для трекинга; ограничивать scope, IP, срок.

• Разделяйте authN (кто) и authZ (что можно). Используйте атрибуты (scopes, roles, tenant, risk flags).
• Все токены — с aud/iss/exp/nbf; clock-skew ≤ 60s; обязательный kid и JWKS-кэш ≤ 5 мин.

3) Авторизация и политики (Zero-Trust)

ABAC/RBAC на шлюзе: правила поверх claims + контекст запроса (IP/ASN/geo/tenant).
Policy-as-Code (например, OPA/Rego): хранение правил в Git, CI-валидация, канареечные выкладки.
Мульти-арендность: изоляция по `X-Tenant-Id`, SSO на tenant-границе; квоты/лимиты на арендатора.

4) Управление трафиком и надежность

Rate limiting: leaky/token bucket, гранулярность: ключ/tenant/route/BIN/страна (для платежных API).
Quotas: дневные/месячные, отдельные на тяжелые операции (например, отчеты).
Burst control и dynamic throttling на основе нагрузки и SLO.
Circuit breaker: открытие при ошибках/латентности; outlier detection по апстримам.
Retry with backoff+jitter; идемпотентность: ключ `Idempotency-Key` + окно TTL + хранение результата.
Timeouts: клиент < шлюз < апстрим; разумные p95-ориентиры (напр., 1.5s/3s/5s).
Failover/Canary: %-роутинг (weighted), session-affinity опционально, blue/green.

5) Трансформации и валидаторы

Схемы: OpenAPI/JSON Schema для REST; Protobuf для gRPC; SDL для GraphQL. Валидация request/response на шлюзе.
gRPC↔REST транспиляция, GraphQL federation (для BFF).
Header нормализация (trace-ids, security headers), response filtering (PII-редакция).
CORS: whitelists, `Vary` корректный, запрет `` на `Authorization` запросах.
Compression и response caching (ETag/Cache-Control) для safe-GET.

6) Безопасность периметра

WAF: OWASP Top-10 правила, позитивная модель для критичных роутов, виртуальные патчи.
Bot-защита: rate-based сигнатуры, device fingerprint, защищенные капчи для публичных эндпоинтов.
DDoS-щит: upstream (cloud) + локальные лимиты; гео/ASN блок-листы.
CSP/Referrer-Policy/X-Frame-Options — если шлюз обслуживает статику/виджеты.
WebSockets/SSE/WebTransport: отдельные профили лимитов и тайм-аутов; auth-пролонгация по токену.

7) Вебхуки: безопасность и доставка

У каждого получателя — собственный секрет; подпись `HMAC(signature, timestamp|path|body)`; окно допустимого времени (например, 5 мин).
Идемпотентность на приеме: дедуп по `event_id`.
Ретраи: экспоненциальные, максимум N; статус-эндпоинт для hand-shake.
mTLS/Allow-list IP; возможность replay по запросу с ограничениями.

8) Наблюдаемость и аудит

Логи: не логировать секреты/PAN/PII; кореллировать по `trace_id`/`span_id`; маскирование.
Метрики: RPS, error rate по классу, latency p50/p95/p99, open circuits, retry rate, 4xx vs 5xx, saturation.
Трейсы: W3C Trace Context; прокидывать `traceparent`/`tracestate` в апстримы.
Аудит: отдельный поток «кто и что вызвал/изменил», неизменяемое хранилище; события политики (access-denied, quota-hit).

9) Секреты и криптография

Хранение ключей: KMS/Vault, ротация каждые 90 дней (или чаще), отдельные роли на чтение.
Сертификаты: автоматическая выдача/обновление (ACME), pinning для мобильных (TOFU/HPKP-like осторожно).
JWKS-ротация: два активных ключа (старый/новый), четкие окна переката.
Криптопрофили TLS: предпочтение ECDHE, запрет уязвимых шифров/протоколов.

10) Комплаенс и данные

PCI DSS: PAN-safe потоки, токенизация; никогда не проксируйте raw-PAN через плагины.
GDPR/DSAR: маршрутизация по региону/тенанту, data residency, удаление/анонимизация.
Лимит экспозиции PII: фильтрация полей на шлюзе, шифрование чувствительных заголовков.

11) Топологии и многорегиональность

Self-managed vs Managed (Envoy/Kong/NGINX vs облачный API-шлюз). Для строгого контроля/PCl — чаще self-managed.
Multi-AZ/Multi-Region Active-Active: глобальный DNS/GSLB, health-based и гео-роутинг, пер-региональные secret-stores.
DR-план: RPO/RTO, холодный/теплый standby шлюз с синком политик.

12) Версионирование и эволюция API

Стратегии: URI vN, header-versioning, content-negotiation. Для публичных — четкая deprecation policy (≥6–12 мес).
Backward-compat: расширять схемы добавлением опциональных полей; контракты в Git, линтеры OpenAPI.
Canary/Shadow: прогон трафика в «тень» новой версии, сравнение ответов.

13) Производительность и кэш

Кэш на edge для GET/идемпотентных запросов; условия: корректные ETag/Cache-Control.
Connection pooling к апстримам; HTTP/2 держать включенным; для gRPC — максимальная выгода.
Payload budgets: ограничение размеров тел; gzip/br.
Pre-compute ответов BFF для высокочастотных панелей/каталогов.

14) Управление конфигурацией

GitOps: декларативные манифесты маршрутов/политик; review/CI (lint, security scan); CD с канареечными партиями.
Фича-флаги на шлюзе: быстрый выключатель маршрутов/правил без деплоя.
Темплейты для повторяющихся политик (OIDC, rate, CORS).

15) Мини-сниппеты (псевдо)

yaml plugins:
- name: idempotency config:
header: Idempotency-Key ttl: 24h storage: redis

yaml
- name: rate-limiting config: {policy: local, minute: 600, key: consumer_id}
- name: response-ratelimiting config: {limits: {"heavy": {minute: 60}}, key: route_id}

yaml
- name: oauth2-introspection config:
jwks_uri: https://idp/.well-known/jwks. json required_scopes: ["payments:write","payments:read"]

yaml
- name: waf config:
mode: block ruleset: owasp_crs exclusions: ["/health", "/metrics"]

pseudo sig = HMAC_SHA256(secret, timestamp + "\n" + method + "\n" + path + "\n" + sha256(body))
assert     now - timestamp     < 300s

16) НФТ (NFR) и SLO для шлюза

Uptime (месяц): ≥ 99.95% (edge), ≥ 99.9% (internal).
Latency p95: ≤ 50–100 ms добавки к апстриму.
Error budget: ≤ 0.05% 5xx от шлюза (исключая апстрим).
Политики безопасности: 100% запросов с TLS; 0 инцидентов утечки секретов; MTTR уязвимости WAF-правил ≤ 24h.

17) Чек-лист внедрения

• Архитектурная карта: edge → BFF → mesh, список доменов/роутов.
• TLS/mTLS, JWKS-ротация, секреты в KMS/Vault.
• OAuth2/OIDC, scopes/claims, ABAC/OPA.
• Rate/quotas, circuit-breaker, retry/backoff, идемпотентность.
• OpenAPI/JSON Schema валидаторы, трансформации gRPC/REST/GraphQL.
• WAF/DDoS/бот-профиль, CORS/CSP.
• Webhook безопасность: HMAC, anti-replay, allow-list.
• Логи/метрики/трейсы; аудит доступа/изменений.
• GitOps/policy-as-code; канареечные выкладки; DR-план.
• PCI/GDPR контроль: маскирование, ретенции, DSAR-процедуры.

18) Частые ошибки

Хранение секретов в конфигурации шлюза/логах.
Глобальный `` в CORS/доверие всем `Origin`.
Отсутствие идемпотентности и честных тайм-аутов → дубли и лавины.
Смешение authN и бизнес-логики в плагинах шлюза.
Нет JWKS-ротации и kid → «застрявшие» ключи.
Наблюдаемость без trace-корреляции → слепые RCA.

Резюме

API Gateway — не просто реверс-прокси, а платформа политики и безопасности, на которой держатся производительность, комплаенс и монетизация. Стройте Zero-Trust, фиксируйте контракты схемами, управляйте трафиком через SLO, автоматизируйте конфигурации через GitOps и policy-as-code. Тогда шлюз станет устойчивым «краем» вашей архитектуры, а не узким горлышком.