Коопсуздук API жана токендер

Кыскача резюме

API коопсуздугу - бул аутентификация, авторизация, криптографиялык коргоо, анти-кыянаттык жана байкоо механизмдеринин жыйындысы, бул суроо-талап күтүлгөн контекстте күтүлгөн ресурска күтүлгөн субъектти аткарат. Негизги артефакт - чакыруу укугун далилдөөчү токен (же өтүнүчтүн кол тамгасы). Жакшы архитектура кыска мөөнөттүү белгилер, так сатып алуулар, минималдуу артыкчылыктар, кайталоодон коргоо, кайра чектөө жана операциялык жол-жоболорго (ротация, аудит, инциденттер) таянат.

API аутентификация моделдери: качан жана эмнени тандоо керек

API-ачкычы (статикалык жашыруун)

B2B интеграциясы жана төмөн тобокелдик сценарийлери үчүн оңой. Контекст алып келбейт, тейлөө тарабында сактоону талап кылат.
IP/ASN allow-list, белгиленген квоталар, кыска TTL жана айлануулар менен гана колдонуңуз.

OAuth 2. 1 / OIDC

Колдонуучу жана өнөктөш интеграциялардын стандарты: access token (кыска мөөнөттүү) + refresh token (айлануу) + сатып алуулар.
Public-кардарлар - PKCE менен; confidential-кардарлар - кардар сыры/mTLS менен.

Client Credentials (m2m)

Machine → Machine: катуу белгиленген skupy жана audience боюнча кызматтар үчүн access token, көп учурда refresh жок (кайра алуу).

mTLS (өз ара TLS)

Каналга идентификацияны байланыштырат. Жогорку тобокелдик же төлөм интеграциясы үчүн идеалдуу (TLS үстүнөн PoP).
OAuth менен айкалыштырылышы мүмкүн (mTLS кардарлары үчүн гана токендер).

Кол суроолор (HMAC/EdDSA)

Сиз транспорт PoP көз карандысыз керек болгондо: кол тамга, timestamp жана nonce. Вебхуктар жана оффлайн текшерүү үчүн ыңгайлуу.

Токендердин форматтары жана түрлөрү

JWT (JWS кол коюлган)

Өзүн-өзү камсыз кылуу, жергиликтүү текшерилет; милдеттүү 'iss', 'sub', 'aud', 'exp', 'iat', 'jti', 'scope'.
Тобокелдик - карап чыгуу кыйыныраак: кыска TTL (5-15 мин) + чакыртып алынган 'jti' тизмесин колдонуу.

JWE (JWT коддолгон)

Payload сезгич болсо, зарыл (PII). Наркы - жогорку татаалдыгы жана кошумча чыгымдар.

Reference tokens

тунук эмес ID, Authorization Server боюнча introspection аркылуу текшерилет - жөнөкөй карап чыгуу/борборлоштуруу.

PoP/DPoP

Токенди кардардын ачкычына же TLS сессиясына байлоо, уурдалган токендин наркын төмөндөтөт.

Токендин мазмуну: минималдуу жетиштүү

Сунушталган белгилер (JWT):

'iss' (issuer), 'sub' (subject), 'aud' (максаттуу система/ресурс), 'exp' (мөөнөт), 'iat', 'nbf' (кошумча), 'jti'.
'scope '/' permissions' (минималдуу зарыл), 'tenant' (көп тенанттуу), 'device _ compliant '/' amr' (аутентификация ыкмасы), 'ip '/' asn' (саясатка тиешелүү болсо).

Эрежелер:

Кыска TTL үчүн access (5-15 мин), refresh - 12-48 саат (айлануу менен).
Аудитория ('aud') - катуу белгилүү бир ресурс, болбосо "көп жолу колдонулуучу" токен.
Скупы - аракет жана объект (мисалы, 'payments: withdraw. read`).
Көлөмү - ≤ жана прокси үчүн 2-4 KB; болбосо, гейтвейлерде көйгөйлөр болушу мүмкүн.

Авторизация жана саясат

RBAC + ABAC: ролу + контекст (уюштуруу, гео, тобокелдик, аппараттын абалы).
PEP/PDP: колдонмого чейин API/прокси (Envoy/OPA) боюнча токенди текшерүү жана чечим кабыл алуу.
Декларативдик эрежелер: Git сактоо, CI policy-тесттен өтүү.

Мисал Rego (жөнөкөй):

rego package policy. withdraw

default allow = false

allow {
input. token. aud == "wallet-api"
input. token. scope[_] == "payments:withdraw. create"
input. device. compliant == true input. risk. score < 70
}

Кол суроолор (HMAC) жана анти-replay

Зарыл болгон учурда: Webhook, OAuth жок интеграция, маанилүү иш-эки текшерүү.

Аталыштардын схемасы (мисал):


X-Client-Id: <id>
X-Timestamp: 2025-11-05T13:20:10Z
X-Nonce: 4d1f...a2
X-Signature: base64(HMAC_SHA256(secret, method + "\n" + path + "\n" + sha256(body) + "\n" + timestamp + "\n" + nonce))

Эрежелер:

Убакыттын өтүшү менен суроо-талаптарды четке кагуу> ± 300 с.
Nonce сактоо 5-15 мин жана кайталап кабыл албайт (replay-кэш).
өтүнүч канондоштурулган өкүлчүлүгүн кол коюу (ыкма, жол, query, хэш орган).

Демпотенттик жана транзакциялык коргоо

Idempotency-Key эсептен чыгаруу/төлөө/түзүү операциялары үчүн: бирдей ачкыч → бирдей эффект.
ачкычтын өмүр - ≥ бизнес-убакыт (адатта 24-72 саат).
Сервер тарабындагы логика: суроо параметрлерин бул ачкыч үчүн мурда катталган параметрлери менен салыштыруу.

Браузер жана мобилдик кардарлар

PKCE милдеттүү (коомдук-кардарлар).
браузерде Refresh-токен - качуу; керек болсо - ROTATION + кайталоого жооп (replay-detect).
Сактоо: session storage> local storage; жакшыраак - токендер үчүн backend for frontend (BFF) жооп берет.
SameSite, Secure, HttpOnly для cookie; CORS - ачык allow-lists, аталыштары жана ыкмалары; preflight-кэш коопсуз.

m2m жана жогорку тобокелдик бириктирүү

mTLS + OAuth2 Client Credentials жана 'aud'.
Гейтвейде IP/ASN allow-list.
PoP/DPoP же HMAC кол маанилүү иш үчүн TLS үстүнөн.
Уюштуруу/кардар/ачкыч боюнча квоталар жана rate limits.

Айлануу, кайра чакыртып алуу жана инциденттерге жооп берүү

Сырларды жана кол тамга ачкычтарын айлантуу (JWKS): график боюнча + окуя болгон учурда мажбурлоо.
Dual-key rollout: алдын ала жаңы ачкыч түгөй жарыялоо (kid2), ага белгилерди кол, эски (kid1) TTL бүткөнгө чейин тастыктоо үчүн сактап.
Refresh-rotation: ар бир алмашуу refresh → жаңы токен, эски дароо жараксыз болуп калат; кайталоо - компромисстик белги.
Revocation: JWT үчүн - кыска мөөнөткө "jti" кайра чакыртып алуу тизмеси; шилтемелер үчүн - AS боюнча токтоосуз кулпу.
Break-glass Scripts: минималдуу укуктар жана катуу TTL менен убактылуу статикалык кред, журналда жазылган.

Rate limiting, bot-коргоо жана ашыкча коргоо

Үч катмарлуу лимиттер: per-key/per-IP/per-уюм.
Бурст + sustained: токен бак/жылма терезе.
Татаал текшерүү: device fingerprint, жүрүм-турум сигналдары, geo/ASN аномалиялар, CAPTCHA UI үчүн гана.
Lockout/slowdown кол коюу/НМАС жана ийгиликсиз аутентификация аракеттери.

Логика, метрика жана SLO

Минималдуу логдор топтому: 'request _ id', 'client _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn', 'latency', 'quota _ state'.

Метрикасы:

Токендерди валидациялоонун ийгилиги (%), p95 текшерүү убактысы.
replay-четтөө жыштыгы, кайталанышы Idempotency-Key.
PoP/DPoP/mTLS менен суроо үлүшү.
'aud/scope' каталары, мөөнөтү өткөн 'exp', убакыт жылышы (NTP).

SLO (мисалдар):

Auth/AS ≥ 99. 95 %/ай; p95 introspection ≤ 50 мс.
TTL <60c менен нөл токендер (коопсуздук метрика).
0 кем. 1% күнүмдүк каталар 'aud/scope' (интеграция сапаты).

Конфигурациялык мисалдар

Envoy: JWT жана audience текшерүү

yaml http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
as:
issuer: https://auth. example. com/
audiences: ["wallet-api"]
remote_jwks:
http_uri:
uri: https://auth. example. com/.well-known/jwks. json cluster: jwks_cluster cache_duration: 600s rules:
- match: { prefix: "/v1/withdraw" }
requires:
provider_and_audiences:
provider_name: as audiences: ["wallet-api"]

NGINX: mTLS к backend

nginx proxy_ssl_server_name on;
proxy_ssl_name wallet. internal;
proxy_ssl_certificate   /etc/nginx/mtls/client. crt;
proxy_ssl_certificate_key /etc/nginx/mtls/client. key;
proxy_ssl_trusted_certificate /etc/nginx/mtls/ca. crt;
proxy_ssl_verify on;
proxy_ssl_verify_depth 2;

Кол тамга аталышынын үлгүсү (вебхактар)


X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))

Server 't' 300 c жогору болсо четке кагат, 'n' буга чейин жолугушту, же 's' согот.

Маалыматтарды коргоо жана купуялык

Маркаларды (өзгөчө PII) жана жашоо мөөнөтүн минималдаштыруу.
Үчүнчү тараптын интеграциясы үчүн сезгич маркаларды (JWE) шифрлөө.
Маск/DLP логтордо: PAN/PII менен денени коддоо эмес, токендер - бир гана 'kid '/желектер, жашыруун эмес.

Типтүү каталар

узун жетүү токендер жана "түбөлүк" refresh.
Жок 'aud '/' scope' → токендер көп максаттуу.
'timestamp '/' nonce' жок вебхуктардын кол тамгасы.
JWT текшерүү гана колдонмодо эмес, Gateway (PEP).
Rotation жана эки-негизги rollout жок.
CORS "" жана баш контролдоо жок коопсуз ыкмаларды чечилет.
BFF жок 'localStorage' токендерин сактоо.

Жол картасы ишке ашыруу

1. API инвентаризациясы жана классификация (ачык/өнөктөш/ички, сезгичтик).
2. AuthN моделин тандоо: OAuth2/OIDC, mTLS + Client Credentials/m2m үчүн HMAC.
3. Токендер: кыска TTL, катуу 'aud', сатып алуу, DPoP/PoP үчүн оор иш.
4. PEP Gateway боюнча: JWT validation, кол тамгалар жана колдонмого чейин rate limits.
5. Анти-реплика жана демпотенттик: timestamp/nonce/Idempotency-Key.
6. Айлануу жана JWKS: эки-негизги, автоматташтыруу жана алертинг.
7. Байкоо: метриктер/SLO, кирүү журналдары, UEBA сигналдары.
8. көнүгүүлөр: кол ачкычын алып салуу, агып refresh, ашыкча квота.

iGaming/Fintech үчүн өзгөчөлүктөрү

Төлөмдөр/төлөмдөр: mTLS + PoP/HMAC гана, катуу сатып алуу ('withdraw. create '), idempotency милдеттүү.
Өнөктөштөр (PSP/мазмун провайдерлери): per-partner ачкычтары/сертификаттары, IP/ASN allow-list, өзүнчө квоталар жана дашборддор.
GDPR/PCI DSS: маркаларды минималдаштыруу, үчүнчү тараптын токендеринде PII тыюу, сезимтал ресурстарга жетүү логин, үзгүлтүксүз access review.
Anti-abuse: жүрүм-турум чектөөлөрү, гео-көзөмөл, API деъгээлинде бонустук кыянаттык коргоо.

FAQ

JWT же reference token?
JWT - аткаруу жана автономия; reference - борборлоштурулган жооп жана жөнөкөй окуя-жооп. Көбүнчө гибрид: тышкы - JWT, ички - шилтеме.

JWE керек?
Payload гана PII/сырларды камтыйт. Болбосо - минималдуу маркалар менен JWS.

API ачкычтарында жашоого болобу?
Ооба, бирок бир гана кыска TTL, катуу квоталар, IP-тизмеси жана суроо-кол коюу менен. Колдонуучулар үчүн - жакшы OAuth/OIDC.

DPoP/PoP сөзсүз?
Дайыма эле эмес. Бирок жогорку тобокелдик операциялары үчүн (төлөмдөр, корутундулар) - өтө зарыл.

Жыйынтык

Ишенимдүү API коопсуздугу кыска мөөнөттүү токендерге, так сатып алууларга жана аудиторияга, корголгон каналдарга (TLS/mTLS), суроо-талаптардын кол тамгаларына жана чектер жана байкоо менен күчөтүлгөн катуу анти-реплик коргоого негизделген. Автоматташтырылган ротацияларды, эки баскычтуу роллорду жана гейтвейлердеги саясий көзөмөлдү кошуңуз - ошондо сиздин API жогорку өндүрүмдүүлүктү жана башкаруучулукту сактап, агып чыгууларга, кайталоолорго жана кыянатчылыктарга туруктуу болот.