API қауіпсіздігі және токендер
Қысқаша түйіндеме
API қауіпсіздігі - бұл аутентификация, авторизация, криптографиялық қорғау, теріс пайдалануға қарсы және бақылау тетіктерінің жиынтығы, ол сұрау салуды күтілетін мәнмәтінде күтілетін ресурсқа күтілетін субъектінің орындауын қамтамасыз етеді. Шешуші артефакт - шақыру құқығын дәлелдейтін токен (немесе сұрау салудың қолы). Жақсы сәулет қысқа өмір сүретін белгілерге, нақты сатып алуларға, ең аз артықшылықтарға, қайталанулардан қорғауға, rate limiting және операциялық рәсімдерге (ротациялар, аудит, инциденттер) сүйенеді.
API аутентификация модельдері: қашан және не таңдау керек
API-кілті (статикалық құпия)
B2B интеграциялары мен төмен тәуекелді сценарийлер үшін оңай. Контексті жоқ, сервис жағында сақтауды талап етеді.
Тек IP/ASN allow-list, тіркелген квоталар, қысқа TTL және ротациялармен пайдаланыңыз.
OAuth 2. 1 / OIDC
Пайдаланушылық және серіктестік интеграцияларға арналған стандарт: access token (қысқа мерзімді) + refresh token (ротация) + сатып алу.
Public-клиенттер - PKCE; confidential-клиенттер - клиенттік құпиясы/mTLS.
Client Credentials (m2m)
Машина → машина: қатаң белгіленген сатып алу және 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
Мөлдір емес идентификаторлар Authorization Server-де introspection арқылы тексеріледі - кері қайтару/орталықтандыру оңай.
PoP/DPoP
Токенді клиент кілтіне немесе TLS сессиясына байланыстыру ұрланған токеннің құндылығын төмендетеді.
Токеннің мазмұны: ең аз жеткілікті
Ұсынылатын таңбалар (JWT):- 'iss' (issuer), 'sub' (subject), 'aud' (мақсатты жүйе/ресурс), 'exp' (мерзім), 'iat', 'nbf' (қосымша), 'jti'.
- 'scope '/' permissions' (ең аз қажет), 'tenant' (көпотенанттар үшін), 'device _ compliant '/' amr' (аутентификация әдісі), 'ip '/' asn' (егер саясатқа қолданылса).
- access үшін қысқа TTL (5-15 мин), refresh - 12-48 сағ (айналмалы ротациямен).
- Аудитория ('aud') - қатаң нақты ресурс, әйтпесе «көп пайдаланылатын» токен.
- Сатып алу - әрекет және нысан (мысалы, 'payments: withdraw. read`).
- Өлшемі - тақырыптар мен прокси үшін 2-4 KB ≤; әйтпесе гейтвейлермен проблемалар болуы мүмкін.
Авторизация және саясат
RBAC + ABAC: рөл + контекст (ұйымдастыру, гео, тәуекел, құрылғының жай-күйі).
PEP/PDP: токенді тексеру және API-шлюзде/проксиде (Envoy/OPA) қосымшаға дейін шешім қабылдау.
Декларативтік ережелер: Git-те сақтау, CI-де policy-tests-тен өту.
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) және anti-replay
Қажет болған кезде: вебхактар, 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))- Nonce 5-15 минут сақтаңыз және қайталауды қабылдамаңыз (replay-кэш).
- Сұраудың канондалған көрінісіне (әдіс, жол, query, хэш) қол қою.
Теңсіздік және транзакциялық қорғау
Есептен шығару/төлеу/жасау операциялары үшін Idempotency-Key: бірдей кілт → бірдей әсер.
Кілттің өмір сүру мерзімі - бизнес-таймауттың ≥ уақыты (әдетте 24-72 сағат).
Сервер жағындағы логика: сұрау параметрлерін осы үшін бұрын бекітілген кілтпен салыстыру.
Браузерлік және мобильді клиенттер
PKCE міндетті түрде (public-клиенттер).
Браузердегі 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 гейтвейде.
Критикалық операциялар үшін TLS үстінен PoP/DPoP немесе HMAC-қолтаңбалар.
Ұйым/клиент/кілтке арналған квоталар мен rate limits.
Ротациялар, кері қайтарулар және тосын оқиғаларға ден қою
Құпияларды және қолтаңба кілттерін ротациялау (JWKS): кесте бойынша + оқиға кезінде мәжбүрлі түрде.
Dual-key rollout: жаңа кілт жұбын алдын ала жариялаңыз (kid2), оның белгілеріне қол қойыңыз, ескісін (kid1) TTL аяқталғанға дейін валидациялау үшін ұстаңыз.
Refresh-rotation: әрбір айырбас refresh → жаңа токен, ескі дереу жарамсыз болады; қайталау - компромат белгісі.
Revocation: JWT үшін - қысқа мерзімге кері қайтарылған 'jti' тізімдері; reference токендер үшін - AS дереу бұғаттау.
Break-glass сценарийлері: минималды құқықтары мен қатты TTL бар уақытша статикалық кредтер, журналға жазыңыз.
Rate limiting, bot-қорғаныс және шектен тыс қорғаныс
Үш қабатты лимиттер: per-key/per-IP/per-ұйым.
Burst + 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) қателері.
- Auth/AS қол жетімділігі ≥ 99. 95 %/ай; p95 introspection ≤ 50 мс.
- Өнімде TTL <60 с бар нөл токендер (қорғау метрикасы).
- 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..."))Егер 't' 300 c, 'n' бұрыннан кездескен болса немесе 's' соғылмаса, сервер қабылдамайды.
Деректерді қорғау және құпиялылық
Таңбаларды (әсіресе PII) және өмір сүру мерзімін барынша азайтыңыз.
Сыртқы интеграциялар үшін сезімтал таңбаларды (JWE) шифрлаңыз.
Логдарда Mask/DLP: PAN/PII бар денелерді логиндемеңіз, белгілер - тек 'kid '/жалаушалар, құпияның өзі емес.
Типтік қателер
Ұзын көбейтетін access-токендер және «мәңгілік» refresh.
'aud '/' scope' → жоқ.
'timestamp '/' nonce' жоқ вебхоктардың қолтаңбасы.
JWT бағдарламасын гейтвейде (PEP) емес, тек бағдарламада тексеру.
Ротациялардың болмауы және dual-key rollout.
CORS «» және тақырыптарды бақылаусыз рұқсат етілген қауіпсіз емес әдістер.
BFF жоқ 'localStorage' ішінде токендерді сақтау.
Енгізу жол картасы
1. API түгендеу және жіктеу (жария/әріптестік/ішкі, сезімталдық).
2. AuthN моделін таңдау: пайдаланушылар үшін OAuth2/OIDC, mTLS + Клиенттік кредиттер/m2m үшін HMAC.
3. Токендер: қысқа TTL, қатаң 'aud', сатып алулар, сындарлы операцияларға арналған DPoP/PoP.
4. PEP гейтвейде: JWT валидациясы, қолтаңбалар және rate limits бағдарламасына дейін.
5. Anti-replay және ұқсамаушылық: timestamp/nonce/Idempotency-Key.
6. Ротация және JWKS: dual-key, автоматтандыру және алертинг.
7. Бақылау қабілеті: метриктер/SLO, қол жеткізу журналдары, UEBA-сигналдар.
8. Оқу-жаттығулар: қол қою кілтін кері қайтару, refresh ағуы, квоталарды қайта жүктеу.
iGaming/финтех ерекшелігі
Төлемдер/төлемдер: тек 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, ішкі - reference.
JWE қажет пе?
Егер payload құрамында PII/құпиялар болса ғана. Басқаша - JWS ең аз таңбалармен.
API кілттерінде өмір сүруге бола ма?
Иә, бірақ тек қысқа TTL, қатаң квоталар, IP-allow-list және сұрау қолтаңбасы бар. Пайдаланушылар үшін - OAuth/OIDC.
DPoP/PoP міндетті бе?
Әрдайым емес. Бірақ high-risk операциялары үшін (төлемдер, қорытындылар) - өте қажет.
Жиынтығы
API-ның сенімді қауіпсіздігі қысқа өмір сүретін токендерге, дәл сатып алуларға және аудиторияға, қорғалған арналарға (TLS/mTLS), сұрау салулардың қолтаңбаларына және қатаң анти-replay қорғанысына, лимиттермен және бақылаушылықпен күшейтіледі. Автоматтандырылған ротацияларды, dual-key rollout және гейтвейлердегі саяси бақылауды қосыңыз - және сіздің API жоғары өнімділікті және басқаруды сақтай отырып, ағындарға, қайталануларға және теріс пайдалануларға төзімді болады.