Аутентификатсияи API: OAuth2, JWT, HMAC

TL; ДР

OAuth2/OIDC + JWT стандарт барои барномаҳои муштарӣ ва ҳамгироии сервер бо иҷозати мураккаб (миқёс/нақш/иҷорагир), SSO ва аломатҳои кӯтоҳи TTL мебошад.
Имзоҳои HMAC интихоби беҳтарин барои вебҳукҳо ва зангҳои шарики оддӣ "сервер → сервер" бо санҷиши детерминистӣ ва муҳофизати қавӣ аз такрорӣ мебошанд.
Мустаҳкамкунии амният: MTLS ё DP okpp (аломатҳои маҳдудкунандаи ирсолкунанда), TTL кӯтоҳ (5-15 дақиқа), гардиши калидҳо (JWKS), нишонаҳои тароват бо ротатсия/истифодаи такрорӣ, санҷиши қатъии 'aud/iss/exp/nbf/kid' ва сиёсат-ас-код дар дарвоза.

1) Харитаи ҳалли: дар куҷо татбиқ кардан лозим аст

2) OAuth2/OIDC: ҷараёнҳо ва мизоҷон

2. 1 ҷараён

Кодекси авторизатсия + PKCE (Web/Mobile) - Рамзи авторизатсияро аз дахолат муҳофизат мекунад.
Маълумоти муштарӣ: server↔server бе корбар; миқёс - ҳадди аққал лозим аст.
Рамзи дастгоҳ: барои дастгоҳҳои бидуни браузер.
Токенро нав кунед: танҳо барои мизоҷони боэътимод; гардиш кунед ва муайянкунии истифодаи такрорӣ имкон диҳед.

2. 2 Намуди мизоҷ

Махфӣ (серверҳо, BFF): махфӣ нигоҳ доштан; МТЛ-ро истифода баред.
Ҷамъият (SPA/mobile): сирро нигоҳ доштан мумкин нест → PKCE, DP POP, TTL кӯтоҳ ва миқёси маҳдуд.

3) JWT: сохтор, вақт, санҷиш

3. 1 Майдонҳо (даъвоҳо)

Ҳатмӣ: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'доираи '/' иҷозат', 'иҷорагир' (агар иҷора бисёр бошад), 'кӯдак'.

3. 2 Ҳаёт

Аломати дастрасӣ: 5-15 дақиқа.
Аломати нав: рӯзҳо/ҳафтаҳо, бо ҳар мубодила чарх занед; ҳангоми пешниҳоди такрории кӯҳна, мо сессияро бозмедорем.

Нишони соат: таҳаммулпазирӣ ≤ 60 с

3. 3 JWKS ва калидҳо

Нигоҳ доштани калидҳо дар KMS/Vault, 'кӯдак' лозим аст.
Ду калиди фаъол (ғелонда), дар ҳар 60-90 рӯз ё дар ҳодиса як маротиба аз нав чоп карда мешаванд.
Кэши JWKS дар дарвоза ≤ 5 дақиқа, бо маъюбии худкор.

3. 4 Санҷиш дар дарвоза/хидматҳо

Санҷед: имзо, 'aud' (хидматҳои тасдиқшуда), 'iss', 'exp/nbf', рӯйхати қуфлҳо (бекоркунӣ).
Бе тасдиқи имзо ба майдонҳои бадан эътимод накунед; нодида гиред 'alg = ҳеҷ'.

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4) Аломати ҳатмӣ ба муштарӣ: m

MTLS (шаҳодатномаҳои муштарии TLS): токен танҳо дар сурати мавҷуд будани шаҳодатномаи муштарӣ дода мешавад ва тасдиқ карда мешавад.
DP oP (Намоиши исботи моликият): Муштарӣ ҳар як дархостро бо калиди яквақта → муҳофизат аз такрорӣ ва дуздии нишона дар муштариёни давлатӣ имзо мекунад.
Барои масирҳои интиқодӣ (мутацияҳои пардохт) - яке аз механизмҳоро талаб мекунад.

5) Авторизатсия: миқёс, нақшҳо, ABAC

Соҳаҳо - амалҳои ҳадди аққал ('пардохтҳо: навиштан', 'пардохтҳо: ҳолат: хондан').
Ролҳо - воҳидҳо барои маъмурон; онҳоро мустақиман бе миқёс истифода набаред.
ABAC - хусусиятҳо дар аломати ('иҷорагир', 'кишвар', 'kyc _ level', 'risk _ flags') → сиёсати дарвоза/OPA.
Сиёсат дар сатҳи масир/майдонча (GraphL) ва дар сатҳи амалиёти домейн (REST/GRPC).

6) Имзои HMAC: webhooks ва шарикон

6. 1 Консепсия

Ҳар як ҳамгироӣ сирри худро дорад.

Сарлавҳа дар болои хати каноникӣ: 'timestamp + '\n "+ method + "\n" + path + "\n "+ sha256 (бадан)'

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

Тирезаи вақт: ≤ 300 сония; Дархостҳоро бо мӯҳлати/ояндаи 'X-Timestamp' рад кунед.
Idempotence: Store 'X-Event-Id' -ро дар TTL (24h) нигоҳ доред - нусхаҳои партофташударо партоед.

6. 2 Таҷрибаи беҳтарин

Асрҳо дар KMS/Vault, ҳар 90 рӯз чарх мезананд.
Барои муштариёни давлатӣ, HMAC мувофиқ нест (ихроҷи махфӣ); OAuth2/DPoP истифода баред.

7) Муҳофизат аз такрорӣ, қувваи бераҳмона ва ихроҷ

Nonce/' jti 'барои амалиёти ҳассос; рӯйхати сиёҳи идентификаторҳои истифодашуда.
Меъёр/квота: аз рӯи калид/мизоҷ/иҷорагир/масир; амалиёти "гарон" квотаҳои алоҳида мебошанд.
Рӯйхати иҷозатномаҳои IP/ASN/Geo барои шарикон ва вебҳукҳо.
Иҷозат барои навъи мундариҷа ('ариза/json'), маҳдудияти андозаи бадан.
Ниқоби PII дар гузоришҳо; манъ кардани сабти нишонаҳо/асрҳо.

8) Хатогиҳо ва ҷавобҳо (формати ягона)

json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}

• '401' - аломати беэътибор (WWW-Authenticate).
• '403' - ҳуқуқҳои нокифоя (миқёс/ABAC).
• '429' - маҳдудиятҳо/квотаҳо.
• GRPC: 'UNAUTHENTICATED '/' ИҶОЗАТ _ РАД '/' RESOURCE _ EXHAUSTED'.

9) Сиёсати мӯҳлат ва сессия

Дастрасӣ ≤ 15 дақиқа; Бозсозӣ - гардиш + муайянкунии такрорӣ (пештара - хотиррасонии сеанс пешниҳод шудааст).
Webhooks HMAC: Имзои TTL ≤ 5 дақиқа; таҳвили такрорӣ бо пуштибонии экспоненсиалӣ.
Сессия/бекоркунии калидҳо → воридшавии фаврӣ ба рӯйхати бекоркунӣ (кэш дар дарвоза ≤ 1 дақиқа).

10) Мушоҳида ва аудит

Таносуб аз ҷониби 'trace _ id '/' span _ id'.
Нишондиҳандаҳо: суръати муваффақияти auth, '401/403/429', таъхири OIDC/JWKS, басомади гардиш, аз нав истифода бурдани тароват, ҳиссаи трафики DP MP/M TLS.
Сабти аудит: "кӣ, вақте ки" зер/иҷорагир/миқёс "боиси он шуд, ки" тағироти калидӣ/махфӣ имзоҳои HMAC-ро ноком карданд.

11) Ҷойгиркунӣ дар дарвозаи API

Тасдиқи JWT (кэши JWKS) ва OPA/ABAC дар дарвоза.
Профилҳои MTLS барои мизоҷон/шарикони боэътимод.
Тафтиши HMAC дар канор (пеш аз хидматҳои дохилӣ).
Сиёсати нархгузорӣ/квота, схема дар провайдери OIDC (кэш JWK).
Парчамҳои хусусият: зуд пайваст кардани мизоҷ/калид, тағир додани алгоритми имзо.

12) порчаҳои мини

Псевдо: Санҷиши JWT

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

Псевдо: санҷиши webhook HMAC

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

Намунаи сиёсати миқёс (идеяи OPA/Rego)

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13) Китобҳои бозии ҳодиса

Ихроҷи калидҳои хусусӣ/JWT-имзокунанда: азнавсозии калидӣ, навсозии JWKS, фавран хомӯш кардани кӯҳна ('кӯдак' → инкор), таровати маъюбӣ, вуруди маҷбурӣ.
Иваз намудани вебхукҳо: гардиши асрҳо, рӯйхати иҷозатдиҳии IP, тақвияти равзанаи 'X-Timestamp', таҳвили такрории рӯйдодҳои партофташуда.
Такрори/brute-force: имкон диҳед DP jo/P/MTLS дар хатсайрҳои интиқодӣ, квотаҳои танг, блокҳои муваққатӣ аз ҷониби IP/ASN, рӯйхати 'jti' -ро фаъол созед.
OIDC-и барҳамдиҳӣ: таназзули нишонаҳои кэшшуда (файз), провайдери схема, огоҳиномаи муштариён.

14) Рӯйхати санҷишҳои татбиқ

• OAuth2: Code + PKCE (Web/Mobile), Маълумоти муштарӣ (сервер-ба-сервер)
• TTL: Дастрасӣ ≤ 15 дақиқа, Тароват бо гардиш ва муайянкунии дубора
• JWKS: ду калиди фаъол, 'кӯдак', кэш ≤ 5 дақиқа
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', тиреза ≤ 300 сония, idempotency
• Маҳдудияти интиқолдиҳанда: MTLS/DP OP дар хатсайрҳои интиқодӣ
• ABAC/OPA: миқёс + иҷорагир/хатар дар сиёсати дарвоза
• Меъёри/Квота и 429; Рӯйхати иҷозатномаҳои IP/ASN барои шарикон
• Аудит ва огоҳиҳо (401/403/429, аз нав истифода баред, имзоҳои HMAC)

• Нишонаҳо/асрори/мақомоти пурраи кортро сабт накунед
• ниқоби PII; Дастгирии DSAR; мӯҳлати нигаҳдории журналҳо маҳдуд аст

15) Анти-намунаҳо

'alg = none' ё ба аломати бидуни санҷиши имзо/JWKS эътимод кунед.
Нишонаҳои дастрасии дарозмуддат (соат/рӯз).
Як сирри умумии HMAC барои ҳамаи шарикон.
Webhooks бе timestamp/idempotency.
Азнавсозии нишонаҳо бе гардиш ва бе муайянкунии такрорӣ.
Набудани тасдиқи 'aud '/' iss' ва гардиши 'кӯдакон'.
Нигоҳ доштани асрори тағирёбандаҳои муҳити зист бидуни KMS/Vault.

16) NFT/SLO (нишонаҳо)

Мавҷудияти OIDC/JWKS ≥ 99. 95% (кэши канорӣ вобастагиро коҳиш медиҳад).
Иловаи тасдиқи JWT дар дарвоза ≤ 2-5 ms p95.
Хатогиҳои аутентификатсия ('401') ≤ 0. 5% трафики умумӣ (ба истиснои ботҳо).
Веб-китобҳои имзошуда: ҳиссаи бомуваффақият санҷидашуда ≥ 99. 9%, таъхири миёнаи интиқол ≤ 3 с.

Хулоса

Механизмҳоро якҷоя кунед: OAuth2/OIDC + JWT барои корбарон ва скриптҳои сервери бой, HMAC барои webhooks/шарикони оддӣ ва барои амалиётҳои муҳим - m TTL-ҳои кӯтоҳ, гардиши калидӣ (JWKS), сиёсати қатъии ABAC/OPA, ҳалқаҳоро аз такрорӣ ва ихроҷ муҳофизат кунед ва ҳама чизро дар сатҳи API Gateway автоматӣ кунед. Ҳамин тавр, аутентификатсия пешгӯишаванда, миқёспазир ва бехатар хоҳад буд - бидуни созиш барои UX ва монетизатсия.