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. Тоді шлюз стане стійким «краєм» вашої архітектури, а не вузьким горлечком.