Интеграционный контракт без явных требований к аутентификации, авторизации и защите данных — это дыра в спецификации, которую закрывают уже в production. Безопасность API (API security) — часть границы между системами: вы фиксируете, кто вызывает интерфейс, что ему разрешено и как защищён канал обмена. Эта статья помогает перевести security из «задачи DevSecOps» в требования, модели и критерии приёмки на проекте.

1. Суть темы

Безопасность API — совокупность принципов, механизмов и организационных мер, которые защищают программные интерфейсы (REST, GraphQL, gRPC, SOAP, webhooks, события) от несанкционированного доступа, утечки и искажения данных и от злоупотребления ресурсами.

Для системного аналитика тема лежит на стыке 03.01.04 Интерфейсы и интеграционные взаимодействия и 08.02 Нефункциональные требования (НФТ) — классификация и стандарты: идентификация клиентов, разграничение прав, защита канала и данных, аудит, лимиты, соответствие регуляторике. Вы не проектируете криптографию и не проводите pentest — вы задаёте ожидаемое поведение на границе API и проверяемые критерии. Детали периметра, WAF, SOC и enterprise IAM — в 08.07 Основы кибербезопасности для системного аналитика.

Граница этой статьи:

В зоне этой статьиВынесено в соседние заметки
AuthN/AuthZ, токены, OAuth/OIDC, mTLS, rate limiting на уровне APIВыбор протокола — 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL)
securitySchemes в контракте, матрица доступа, негативные сценарииФорматы контрактов — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)
Угрозы и требования на границе APIОбщая кибербезопасность, IAM enterprise, WAF — 08.07 Основы кибербезопасности для системного аналитика
Rate limit как защита APIДетали пропускной способности — 03.06.03 Rate Limiting — управление пропускной способностью
PCI, GDPR, 152-ФЗ как ограничения на дизайн APIРегуляторика РФ — 08.06 Юридические и регуляторные требования РФ (PCI-DSS)
Безопасность событий и очередей — минимальный чеклистKafka, ACL, schema registry — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 03.05.06 Event-Driven Architecture

Логическая модель слоёв защиты — ориентир для раздела «Безопасность» в спецификации (не замена threat modeling):

flowchart TB
    subgraph transport [Transport]
        TLS[TLS 1.2+]
    end
    subgraph edge [Edge — требования к gateway]
        GW[API Gateway: политики AuthN/AuthZ, rate limit, TLS termination]
    end
    subgraph app [Application / API]
        AuthN[Authentication]
        AuthZ[Authorization]
        Val[Валидация входа]
    end
    subgraph data [Data]
        Min[Data minimization]
        Enc[Шифрование at rest]
    end
    subgraph ops [Operations]
        Audit[Аудит и логи]
        Mon[Мониторинг аномалий]
    end
    Client --> transport --> edge --> app --> data
    app --> ops

На уровне SA для слоя Edge достаточно зафиксировать: gateway — точка принудительного применения политик (аутентификация, лимиты, маршрутизация), а не детальная конфигурация WAF/DDoS.

2. Ключевые понятия

Аутентификация и авторизация

ТерминСмысл для аналитика
Authentication (аутентификация, AuthN)Доказательство «кто вызывает API» — пользователь, сервис, устройство
Authorization (авторизация, AuthZ)«Что разрешено делать» после успешной аутентификации — роли, scopes, policies
Identity & Access Management (IAM)Управление учётными записями, ролями, выдачей и отзывом доступа к API
Least privilege (минимальные привилегии)Каждый клиент получает минимально необходимые scopes/роли для своего сценария
Step-up / MFAПовышенная assurance для критичных операций (перевод, смена email) — отдельная строка в матрице доступа

Различайте 401 Unauthorized и 403 Forbidden в контракте и критериях приёмки:

  • 401 — клиент не аутентифицирован или credentials недействительны (нет/просрочен token, неверная подпись).
  • 403 — клиент аутентифицирован, но операция или ресурс ему недоступны.

Политика информационной утечки (404 vs 403) — отдельное требование в спецификации, не «по умолчанию»:

ПолитикаКогда применятьПример для BOLA (GET /orders/{id})
404 Not FoundНе раскрывать факт существования чужого ресурса (partner/public API)Чужой id → 404, как если бы ресурса не было
403 ForbiddenДостаточно сказать «нет доступа»; перечисление id не критично (internal admin)Чужой id → 403

Зафиксируйте политику глобально для API и в examples контракта. Смешение семантики ломает retry, refresh token и тест-кейсы на стороне потребителей.

Зоны доверия: внутренний и внешний API

Тип APIЗона доверияТиповая схемаЧто явно описать в требованиях
Partner / publicИнтернет, zero trustOAuth 2.0 + scopes, иногда mTLSМатрица scopes, rate limits, 404-policy
Internal servicePrivate network / meshmTLS, service account, workload identity (K8s SA, SPIFFE)Service identity, запрет слепого token forwarding
Admin / backofficeVPN + elevated rolesSSO + MFA, step-up на destructive opsBFLA-контроль, audit обязателен
LegacyЗависит от интеграцииAPI Key, WS-Security, BasicОтдельный security-профиль, не «как у REST»

Учётные данные и токены

ТерминСмысл для аналитика
Credential / secretAPI key, client secret, сертификаты — хранение в vault, ротация, исключение из логов
Token-based accessДоступ по ограниченному по времени токену вместо постоянной передачи пароля
JWT (JSON Web Token)Самодостаточный формат токена с claims; риски при слабой подписи, длинном TTL, хранении в localStorage
Opaque tokenНепрозрачный идентификатор сессии; валидация через introspection на authorization server

OAuth 2.0 — фреймворк делегирования доступа, а не полная модель безопасности API. Типовые grant types для спецификации:

Grant typeКогда применятьКлиент
Authorization Code + PKCEПользовательский доступ из browser/mobilePublic client (SPA, native app)
Client CredentialsMachine-to-machine без пользователяConfidential client (backend, микросервис)
Device AuthorizationУстройства с ограниченным вводомSmart TV, IoT

Refresh Token — не отдельный grant type, а механизм продления сессии после Authorization Code + PKCE. В спецификации зафиксируйте: endpoint обмена, TTL, ротацию refresh token, поведение при 401 (re-login vs silent refresh).

Deprecated flows — при ревью legacy-контрактов фиксируйте замену в артефактах, а не устным запретом:

FlowЧто записать в спецификации
Implicit flowNFR: «новые public clients не используют Implicit»; ADR с обоснованием Authorization Code + PKCE (RFC 9700, RFC 10017); критерий приёмки ревью контракта
Resource Owner Password Credentials (ROPC)Исключение только с ADR и сроком вывода; пункт в матрице трассировки «ROPC → migration target»

OpenID Connect (OIDC) — слой идентификации поверх OAuth 2.0: ID Token, стандартизованные claims о пользователе (sub, email, name). OAuth отвечает «можно ли», OIDC — «кто это».

mTLS (mutual TLS) — взаимная аутентификация клиента и сервера сертификатами. Типична для B2B-партнёров и zero-trust между внутренними сервисами.

Хранение токенов в browser SPA: localStorage — риск XSS; альтернативы для спецификации — BFF (Back-End For Front-end) с httpOnly cookie + SameSite, или Authorization Code + PKCE с коротким TTL access token. Детали паттернов — RFC 10017.

JWT: local validation vs introspection — зафиксируйте как NFR в 10.01.12 Шаблон нефункциональных требований (NFR): допустима ли локальная проверка подписи без обращения к authorization server, требования к aud/iss, поведение при недоступности introspection-endpoint.

Сознательно вне scope этой статьи (детали — 08.07 Основы кибербезопасности для системного аналитика):

  • token revocation, blacklist и session invalidation;
  • JWKS rotation и key management;
  • session fixation, supply chain security;
  • enterprise IAM, SSO federation, SOC-процессы.

Legacy: SOAP, API Key, WS-Security

REST-centric модель не покрывает весь ландшафт. Минимальный чеклист для legacy-интеграций (шаблон — 10.01.05 Шаблон спецификации SOAP API):

ЭлементЧто зафиксировать в требованиях
API KeyТолько в header; ротация; привязка к IP/environment; не в URL и логах
WS-Security (SOAP)UsernameToken vs X.509; подпись/шифрование body; timestamp + nonce против replay
TransportTLS 1.2+; для B2B — mTLS на уровне канала
Идempotency / replayУникальный MessageID или nonce в окне допустимого времени
ОшибкиБез stack trace и внутренних кодов в production fault

Не смешивайте legacy-профиль с OAuth REST «в одном абзаце» — отдельная строка в матрице интеграций.

Edge и gateway (уровень требований SA)

МеханизмЧто зафиксировать в спецификации
API GatewayЕдиная точка enforcement: AuthN/AuthZ, rate limit, IP-allowlist, TLS termination
Rate limitingОбязателен на auth-endpoints и expensive operations; ответ 429 + Retry-After в контракте; алгоритмы — 03.06.03 Rate Limiting — управление пропускной способностью

WAF, DDoS-mitigation, сигнатурные правила — зона эксплуатации и 08.07 Основы кибербезопасности для системного аналитика, не детализируйте в API-контракте.

Протокол-специфичные контроли

Детали протоколов — в 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL) и 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf). На границе API зафиксируйте минимум:

ПротоколДополнительные требования SAКритерий приёмки (пример)
REST / OpenAPIsecuritySchemes, CORS-policy для browser-клиентов, pagination AuthZОперация без security в spec → дефект контракта
GraphQLОтключение introspection в production; field-level AuthZ; лимиты глубины/сложности (cost analysis, persisted queries)Introspection в prod → 403/404; запрос сверх лимита complexity → 400
gRPCmTLS / ALPN; per-method auth в Protobuf-контракте; metadata для trace и identityRPC-метод без security в proto → дефект; identity не propagates без явной policy

Асинхронные интерфейсы и события

Для producer/consumer (шаблоны — 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ), 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ)) зафиксируйте:

  • ACL топиков/очередей — кто может publish/consume;
  • Encryption in transit — TLS к брокеру;
  • Подпись сообщений или integrity-check для критичных событий;
  • Schema registry — валидация payload, запрет произвольных полей (аналог mass assignment);
  • Consumer auth — отдельные credentials на consumer group, не shared prod key.

Подробнее — 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 03.05.06 Event-Driven Architecture.

CORS и browser-клиенты

CORS (Cross-Origin Resource Sharing) — политика браузера, не серверный CSRF-токен. CORS не заменяет AuthN/AuthZ на API.

НастройкаРискТребование
Access-Control-Allow-Origin: * + credentials: trueУтечка cookie/credentials сторонним originЗапрещено; explicit whitelist origins
* без credentialsСлабая модель для sensitive APIЯвный список origins; PKCE для public clients
Cookie-based sessionCSRF при отсутствии SameSite/anti-CSRFSameSite=Lax/Strict или BFF-паттерн

CSRF-защита для cookie-сессий — отдельное требование (SameSite, double-submit, BFF); не путайте с CORS.

Угрозы: OWASP API Security Top 10

OWASP API Security Top 10 (2023) — основной чек-лист при ревью требований и sequence-диаграмм. Для формальной threat-модели (STRIDE, DREAD) — 08.05 Управление рисками на этапе анализа и 08.07 Основы кибербезопасности для системного аналитика.

КатегорияСуть для SA
Broken Object Level Authorization (BOLA)Доступ к чужим объектам (/orders/{id}, подмена cursor/page в pagination)
Broken AuthenticationСлабые/deprecated flows, долгоживущие токены без revocation
Broken Object Property Level AuthorizationMass assignment — клиент меняет read-only поля
Unrestricted Resource ConsumptionНет rate limits на login, OTP, expensive queries
Broken Function Level Authorization (BFLA)Admin-операции при user-роли
Unrestricted Access to Sensitive Business FlowsЗлоупотребление регистрацией, OTP, лимитированными товарами
Server Side Request Forgery (SSRF)API fetch'ит URL от клиента: callback URL, import-from-URL, webhook registration
Security MisconfigurationDebug endpoints, дефолтные credentials, открытый GraphQL introspection
Improper Inventory ManagementStaging API без auth, «забытые» deprecated версии
Unsafe Consumption of APIsСлепое доверие ответам third-party API

SSRF в контракте — примеры полей для валидации: callbackUrl, webhookUrl, importUrl; whitelist схем/хостов; запрет private IP ranges.

Security scheme в контракте: sync vs async

В 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) секция securitySchemes декларативно описывает способ защиты. Для SA важно различать, что фиксируется в machine-readable контракте и что — на уровне инфраструктуры брокера:

АспектOpenAPI (REST/sync)AsyncAPI (events/async)
Где описывается authsecuritySchemes + security per operationsecuritySchemes + security на channel/operation
Типовые schemeshttp+bearer, oauth2, apiKey, mutualTLSuserPassword, X509, httpApiKey, SASL (Kafka)
EnforcementAPI Gateway / serviceACL брокера и auth в контракте события — разные слои
Что SA обязан зафиксироватьScopes, 401/403/404, CORSКто publish/consume, SASL/SCRAM или mTLS к брокеру, подпись payload
Типичная ошибкаAuth только в Confluence, не в specACL настроен, но в AsyncAPI нет security — scope drift при смене брокера

OpenAPI — типы scheme:

Тип schemeПрименение
http + bearerJWT или opaque token в заголовке Authorization
http + basicLegacy; избегать для новых API
oauth2Flows, scopes, authorization/token URLs
apiKeyКлюч в header (query — антипаттерн для sensitive)
mutualTLSСертификат клиента

security на уровне global и override на операциях — часть machine-readable контракта, а не дублирующий текст в Confluence или отдельном документе.

3. Как применяется в работе аналитика

Приоритизация: MVP vs production

Полный чеклист ниже — ориентир для regulated production. Для первой итерации partner API достаточно Must-набора; Should и Could — следующие спринты или отдельный security epic.

ТребованиеPartner / publicInternal serviceAdmin / backoffice
TLS 1.2+MustMustMust
AuthN схема в контракте (securitySchemes)MustMustMust
Матрица scopes / ролейMustMustMust
Политика 404 vs 403 (BOLA)MustShouldShould
Rate limits на auth + expensive opsMustShouldMust
Sequence auth flowMustShouldMust
MFA / step-up на destructive opsShould—Must
mTLSCould (B2B)Must (mesh)Should
Webhook HMAC + SSRF validationMust (если есть)Should—
Негативные тест-кейсы в матрице трассировкиMustShouldMust
Threat modeling OWASP Top 10ShouldCouldMust
Audit log без PII/secretsMustMustMust

В требованиях и моделях

1. Зафиксируйте security NFR до согласования контракта с партнёром.

Минимальный набор вопросов:

  • Кто клиенты API: browser SPA, mobile, B2B-партнёр, internal microservice?
  • Модель доверия: публичный интернет, VPN, private link, service mesh?
  • Нужны SSO, MFA, step-up auth для отдельных операций?
  • Класс данных: PII, платёжные — из 03.03.03 Словарь данных (описание)?
  • Политика 404 vs 403 для BOLA и enumeration?

2. Опишите auth flow в сценариях интеграции.

На 03.02.01 Диаграмма прецедентов (Use Case Diagram), 03.02.02 Диаграмма деятельности (Activity Diagram) и 03.02.03 Диаграмма последовательности (Sequence Diagram) для каждого сценария:

  • шаги аутентификации и обновления token;
  • отказ доступа (401/403/404 по политике) и поведение клиента;
  • service identity и запрет неконтролируемого token forwarding.

Пример user-centric flow для SPA:

sequenceDiagram
    participant User as Пользователь
    participant SPA as SPA (public client)
    participant Auth as Authorization Server
    participant API as Resource API

    User->>SPA: Login
    SPA->>Auth: Authorization Code + PKCE
    Auth-->>SPA: Authorization code
    SPA->>Auth: Code + code_verifier
    Auth-->>SPA: Access token + Refresh token
    SPA->>API: Request + Bearer token
    API->>API: Validate token + AuthZ
    API-->>SPA: 200 / 403 или 404

Пример M2M с service identity:

sequenceDiagram
    participant SvcA as Service A
    participant Auth as Authorization Server
    participant SvcB as Service B

    SvcA->>Auth: Client Credentials (service account)
    Auth-->>SvcA: Access token (aud=SvcB, scoped)
    SvcA->>SvcB: Request + Bearer token
    Note over SvcB: Проверка aud, scope, caller identity — не pass-through user token без policy
    SvcB-->>SvcA: 200 / 403

3. Постройте матрицу доступа.

Роль / система-клиентОперации APIScopesMFA / step-upТипы данных
partner-readGET /orders, GET /orders/{id}orders:read—Без PII покупателя
partner-fulfillmentPATCH /orders/{id}/statusorders:write:status—Статус, tracking
internal-billingPOST /invoicesinvoices:write—Финансовые
user-selfDELETE /accountaccount:deleteMFA обязателенPII владельца

Матрица связывает 10.01.11 Шаблон ролевой модели, контракт и тест-кейсы.

4. Примените data minimization.

  • Какие поля в request/response — явно в схемах контракта.
  • Запрет «отдавать всю сущность» в list/get без business need.
  • Read-only поля (статус, роль, audit timestamps) — в schema как readOnly; не принимаются от клиента на update.

Mass assignment: для partner/public API предпочтительна явная ошибка 400 Bad Request при попытке записи read-only поля. Тихий игнор допустим только для internal API с явной политикой в контракте — один выбор на весь API, не «400 или игнор» без решения.

5. Опишите ошибки без утечки деталей.

Здесь — только security-специфичные пункты. Полный чеклист полей error body, headers и кодов — в 10.01.04 Шаблон спецификации REST API и 10.01.12 Шаблон нефункциональных требований (NFR):

  • Production: без stack trace, внутренних ID, SQL-фрагментов.
  • Correlation ID — в header, не рядом с sensitive data в теле.

6. Логирование и audit — NFR без секретов и PII.

Зафиксируйте явный запрет в 10.01.12 Шаблон нефункциональных требований (NFR):

7. Idempotency и replay для write API.

  • Idempotency-Key header для POST (создание) — обязателен для payment/order flows;
  • окно идемпотентности и поведение при повторе;
  • для webhooks — timestamp + nonce (см. ниже).

8. Webhooks и callbacks.

  • подпись payload (HMAC-SHA256 с shared secret);
  • replay protection (timestamp + nonce, окно допустимого времени);
  • whitelist URL партнёра; валидация против SSRF (private IP, file://);
  • retry policy без бесконечных повторов на 401.

9. Third-party API consumption.

10. Compliance как ограничения на дизайн.

РегуляторикаВлияние на APIКуда углубиться
GDPR / 152-ФЗ (персональные данные)Минимизация PII в ответах, согласия, локализация, право на удаление08.06 Юридические и регуляторные требования РФ (PCI-DSS), 03.03.03 Словарь данных (описание)
PCI DSSНе передавать PAN в логах; tokenization; сегментация платёжных API08.06 Юридические и регуляторные требования РФ (PCI-DSS)
Отраслевые стандартыДополнительные поля audit, retention логов08.05 Управление рисками на этапе анализа

11. Версионирование и security.

Согласуйте с 03.05.07 Управление версионированием API и жизненным циклом:

  • deprecated версия API сохраняет тот же security — «открытый» /v1 без auth при sunset запрещён;
  • при смене auth-модели (OAuth client, scopes) — dual-running ключей на период миграции с датой cutoff;
  • в OpenAPI каждая версия явно наследует или переопределяет securitySchemes; расхождение v1/v2 = дефект spec;
  • sunset deprecated версии включает отзыв credentials, а не только 410/404 на endpoints.

12. Критерии приёмки — негативные сценарии.

В 02.04.02 Критерии приёмки (Acceptance Criteria), 02.04.01 Верификация и валидация (V&V) и 08.03 Тестирование требований (статическое тестирование). Детальный перечень тест-кейсов — в 10.01.04 Шаблон спецификации REST API; здесь — security-минимум:

  • просроченный или подделанный token → 401;
  • чужой objectId при валидном token → 404 или 403 по зафиксированной политике (BOLA);
  • подмена page/cursor для чужих данных → та же политика (pagination BOLA);
  • escalation scope (write при read-only scope) → 403;
  • превышение rate limit → 429 с Retry-After;
  • mass assignment read-only поля → 400 (или явно документированный игнор для internal);
  • SSRF: callback на 169.254.x.x → 400;
  • реализация проверяет scopes из spec (scope drift = дефект) — трассировка в 02.03.04 Трассировка требований (концепция) и 10.01.15 Шаблон матрицы трассировки.

13. Упрощённый threat modeling.

На 03.04.02 Диаграмма потоков данных (DFD) или 03.01.02 Моделирование контекста системы (Context Diagram) пройдите категории OWASP API Top 10 — таблица «угроза → контроль → требование → тест-кейс». Для полноценного STRIDE/DFD-анализа — 08.05 Управление рисками на этапе анализа.

Артефакты аналитика

АртефактСодержание
Раздел «Безопасность» в спецификации APIМодель доверия, flows, матрица доступа, политика 404/403, политика секретов и логов
Таблица секретов и ответственныхИмена secret, владелец, срок ротации — без значений в документации
Sequence diagramsAuthorization Code + PKCE; Client Credentials для M2M
10.01.15 Шаблон матрицы трассировкиТребование безопасности → операция API → негативный тест-кейс
OpenAPI / AsyncAPI specsecuritySchemes, security per operation/channel, без незащищённых «скрытых» endpoints
10.01.13 Шаблон архитектурного решения (ADR)Решения по deprecated flows, introspection vs local JWT, mTLS

4. Типовые ошибки и ограничения

Ограничения

Типичные ошибки

ОшибкаПоследствиеЧто делать
Путаница 401 и 403Неверный retry/refreshЯвная семантика в контракте и examples
BOLA без политики 404/403Enumeration, утечка факта существованияЗафиксировать политику глобально для API
AuthZ только «есть token»BOLA, pagination leakПроверка владельца на каждой операции и в list/cursor
API keys в URL, логахУтечка credentialsHeader only; secret management
Excessive data exposureУтечка PIIData minimization; отдельные DTO list/detail
Mass assignment без политикиКлиент меняет role/status400 для partner API; readOnly в schema
CORS * + credentialsУтечка session cross-originExplicit origins; PKCE; BFF для cookie
Путаница CORS и CSRFНеверные критерии приёмкиCORS — browser policy; CSRF — отдельный контроль для cookies
Implicit flow / ROPC в новых SPADeprecated, уязвимый authNFR + ADR: Authorization Code + PKCE (RFC 9700/10017)
JWT в localStorage без альтернативыXSS → компрометация tokenBFF + httpOnly cookie или короткий TTL
Token forwarding без policyEscalation в microservicesService identity; явная policy pass-through
Нет rate limits на login/OTPBrute force, DoSЛимиты на auth endpoints; 03.06.03 Rate Limiting — управление пропускной способностью
Логирование Authorization и PIICompliance-инцидентNFR «не логировать» в спецификации
POST без Idempotency-KeyDuplicate charges/ordersIdempotency-Key для write flows
Security после sign-off контрактаДорогие переделкиSecurity NFR до contract sign-off
Enterprise IAM в API-статьеРазмытая ответственностьГраница API здесь; enterprise — 08.07 Основы кибербезопасности для системного аналитика
Async: ACL брокера без specScope drift при миграцииsecuritySchemes в AsyncAPI + ACL в runbook

Связи с другими разделами базы

Источники и дополнительные материалы

Стандарты и спецификации

Статьи и cheat sheets