API ავთენტიფიკაცია: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT არის სტანდარტი კლიენტის პროგრამებისა და სერვერის ინტეგრაციისთვის, რთული ავტორიზაციით (scopes/roles/tenants), SSO და მოკლე TTL ნიშნით.
HMAC ხელმოწერები საუკეთესო არჩევანია ვებ-ჰუკებისა და მარტივი პარტნიორობის გამოწვევებისთვის „სერვერი - სერვერი“ დეტერმინისტული შემოწმებით და მკაცრი დაცვით.
გააძლიერეთ უსაფრთხოება: mTLS ან DPoP (sender-constrained tokens), მოკლე TTL (5-15 წთ), კლავიშების როტაცია (JWKS), refresh ნიშნები როტაციით/anti-reuse, მკაცრი თანმიმდევრულია 'aup/isunistauningrede/exexexanexs/nbf/kid' და პოლიტიკური კოდი gateway- ზე.

1) გადაწყვეტილებების რუკა: სად უნდა გამოვიყენოთ

2) OAuth2/OIDC: ნაკადები და მომხმარებლები

2. 1 ნაკადები

Authorization Code + PKCE (Web/Mobile): იცავს ავტორიზაციის კოდს ჩარევისგან.
Client Credentials: სერვერი - სერვერი მომხმარებლის გარეშე; scopes არის მინიმალური საჭირო.
Device Code: მოწყობილობებისთვის ბრაუზერის გარეშე.
Refresh Token: მხოლოდ სანდო მომხმარებლებისთვის; ჩართეთ და ჩართეთ reuse detection.

2. 2 კლიენტის ტიპები

Confidential (სერვერები, BFF): ინახავს საიდუმლოებებს; გამოიყენეთ mTLS.
Public (SPA/მობილური): საიდუმლო არ შეიძლება ინახებოდეს PKCE, DPOP, მოკლე TTL და შეზღუდული სკოპები.

3) JWT: სტრუქტურა, პირობები, გადამოწმება

3. 1 მინდვრები

სავალდებულო: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope '/' permissions', 'tenant' (თუ მულტიარენდი), 'kid'.

3. 2 ცხოვრების დრო

Access token: 5-15 წუთი.
Refresh token: დღეები/კვირა, თითოეული გაცვლით ბრუნავს; როდესაც ძველის ხელახლა წარდგენა - სხდომის დაბლოკვა.
Clock skew: დაშვება 60 წამი.

3. 3 JWKS და გასაღებები

გასაღებების შენახვა KMS/Vault, 'kid' სავალდებულოა.
ორი აქტიური გასაღები (როლინგი), ხელახლა გამოცემა 60-90 დღეში ერთხელ ან ინციდენტის დროს.
Kash JWKS gateway - 5 წუთი, შეზღუდული შესაძლებლობის მქონე მანქანებით.

3. 4 გადამოწმება gateway/სერვისებზე

შეამოწმეთ: ხელმოწერა, 'aud' (დაშვებული სერვისები), 'iss', 'exp/nbf', ბლოკირების სია.
ნუ ენდობით სხეულს მინდვრებს ხელმოწერის შემოწმების გარეშე; უგულებელყავით 'alg = none'.

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

4) ნიშნის დაკავშირება კლიენტთან: mTLS, DPOP

MTLS (TLS კლიენტის სერთიფიკატები): ნიშანი გაიცემა და იხსნება მხოლოდ იმ შემთხვევაში, თუ არსებობს კლიენტის სერტიფიკატი, ნიშანი უსარგებლო იქნება „გასაღები + სერთიფიკატი“.
DPoP (Proof-of-Possession Demonstration): კლიენტი ხელს აწერს თითოეულ თხოვნას ერთჯერადი გასაღებით - დაცვა საზოგადოებრივი კლიენტებში ნიშნის მიღებისა და ქურდობისგან.
კრიტიკული მარშრუტებისთვის (გადახდის მუტაცია) - მოითხოვოს ერთ-ერთი მექანიზმი.

5) საავტორო უფლებები: scopes, roles, ABAC

Scopes - მინიმალური მოქმედებები ('payments: write', 'payouts: status: read').
Roles - განყოფილებები ადმირალებისთვის; ნუ გამოიყენებთ პირდაპირ სკოპების გარეშე.
ABAC - ატრიბუტები ტოკენში ('tenant', 'country', 'kyc _ level', 'risk _ flags') პოლიტიკის შესახებ gateway/OPA.
პოლიტიკა მარშრუტი/ველის დონეზე (GraphQL) და აფეთქების ღუმელის ოპერაციის დონეზე (REST/gRPC).

6) HMAC ხელმოწერები: ვებჰუკი და პარტნიორები

6. 1 კონცეფცია

თითოეულ ინტეგრაციას აქვს საკუთარი საიდუმლო.

ხელმოწერა კანონიკურ ხაზზე: „timestamp + “\n„ + method + “\n „+ path + “\n„ + sha256 (body) “

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

დროის ფანჯარა: 300 წამი; ვადაგადაცილებული/მომავლის მოთხოვნების უარყოფა.
Idempotence: შეინახეთ 'X-Event-Id "TTL- ზე (24 საათი) - გადააგდეთ დუბლიკატები.

6. 2 საუკეთესო პრაქტიკა

საიდუმლოებები KMS/Vault- ში, როტაცია ყოველ 90 დღეში.
HMAC არ არის შესაფერისი საჯარო მომხმარებლებისთვის (საიდუმლო გაჟღენთილია); გამოიყენეთ OAuth2/DPOP.

7) დაცვა replay, brute force და გაჟონვისგან

Nonce/' jti 'მგრძნობიარე ოპერაციებისთვის; გამოყენებული იდენტიფიკატორების შავი სია.
Rate/èttas: გასაღები/კლიენტი/ტენანტი/მარშრუტი; „ძვირადღირებული“ ოპერაციები - ცალკეული კვოტები.
IP/ASN/Geo allow-lists პარტნიორებისა და ვებჰუკებისთვის.
შინაარსის ტიპი allow ('განაცხადი/json'), სხეულის ზომის ლიმიტი.
PII შენიღბვა ლოგებში; ნიშნის/საიდუმლოების გადახედვის აკრძალვა.

8) შეცდომები და პასუხები (ერთი ფორმატი)

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

• '401' - არა/WWW-Authenticate.
• '403' - საკმარისი უფლებები (scope/ABAC).
• '429' - ლიმიტები/კვოტები.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) ვადებისა და სესიების პოლიტიკა

Access - 15 წუთი; Refresh - როტაცია + reuse detection (შეიტანეს ძველი - სესიის მიმოხილვა).
ვებჰუკი HMAC: TTL ხელმოწერები 5 წუთი; განმეორებითი მიწოდება ექსპონენციალური backoff- ით.
სესიის/გასაღების მიმოხილვა - დაუყოვნებლივი დარტყმა რეკონსტრუქციის სიაში (ქეში gateway 1 წუთი).

10) დაკვირვება და აუდიტი

'trace _ id '/' spank _ id' კორელაცია.
მეტრიკა: aut success rate, '401/403/429', ლატენტობა OIDC/JWKS, როტაციის სიხშირე, reuse refresh, DPoP/mTLS ტრაფიკის წილი.
აუდიტის ჟურნალი: „ვინ, როდის, რომელმა“ sub/tenant/scope „გამოიწვია რა“, გასაღებების/საიდუმლოების ცვლილებები, HMAC- ის წარუმატებელი ხელმოწერები.

11) მშენებლობა API Gateway- ში

JWT სავალდებულო (JWKS ქეში) და OPA/ABAC კარიბჭეზე.
mTLS პროფილები სანდო მომხმარებლებისთვის/პარტნიორებისთვის.
ვებჰუკების გადამოწმება edge (შიდა სერვისებამდე).
Rate/Quta პოლიტიკა, circuit-breaker OIDC პროვაიდერზე (JWK ქეშირება).
Feature-flags: კლიენტის/გასაღების სწრაფი გათიშვა, ხელმოწერის ალგორითმის შეცვლა.

12) მინი snippets

ფსევდო: გადამოწმება 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]

ფსევდო: 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)

scope პოლიტიკის მაგალითი (OPA/Rego იდეა)

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

13) ინციდენტების ფლეიბუკი

პირადი გასაღების/JWT ხელმოწერის გაჟონვა: კლავიშების ხელახლა გამოშვება, JWKS- ის განახლება, ძველი ('kid' - დენი) დაუყოვნებლივი გათიშვა, რეფრესის ინვალიდობა, იძულებითი ლოგო.
ვებჰუკების შეცვლა: საიდუმლოებების როტაცია, IP ალოუ-სია, ფანჯრის გაძლიერება 'X-Timestamp', გამოტოვებული მოვლენების ხელახალი მიწოდება.
Replay/trutfors: ჩართეთ DpoP/mTLS კრიტიკულ მარშრუტებზე, კვოტების შევიწროვება, დროებითი ბლოკები IP/ASN- ის მიხედვით, ჩართეთ 'jti' ბლოკერი.
Outage OIDC: ქეშირებული ტოქსინების დეგრადაცია (grace), პროვაიდერის ცირკი-ბრეიკერი, მომხმარებელთა შეტყობინება.

14) განხორციელების ჩეკის ფურცლები

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access 15 წუთი, Refresh როტაციით და reuse detection
• JWKS: ორი აქტიური გასაღები, 'kid', ქეში 5 წუთი
• ვებჰუკი: HMAC v1, 'X-Timestamp', 'X-Event-Id', ფანჯარა 300 წამი, idempotence
• Sender-constrained: mTLS/DPoP კრიტიკულ მარშრუტებზე
• ABAC/OPA: scopes + tenant/risk საკეტის პოლიტიკოსებში
• Rate/Quota и 429; პარტნიორებისთვის IP/ASN allow-lists
• აუდიტი და ალერტები (401/403/429, reuse refresh, ხელმოწერები HMAC)

• არ გააკეთოთ ნიშნები/საიდუმლოებები/სრული რუქა
• შენიღბვა PII; DSAR მხარდაჭერა; ლოგების შენახვის ვადა შეზღუდულია

15) ანტი შაბლონები

'alg = none' ან ტენის ნდობა ხელმოწერის შემოწმების გარეშე/JWKS.
გრძელი წვდომის ნიშნები (საათი/დღე).
ერთი საერთო HMAC საიდუმლო ყველა პარტნიორისთვის.
ვებჰუკი ტაიმსტამპის/იდემპოტენტურობის გარეშე.
Refresh ნიშნები როტაციის გარეშე და reuse detection- ის გარეშე.
'aud '/' iss' - ის არარსებობა და 'kid' როტაცია.
საიდუმლოებების შენახვა ცვლადი გარემოში KMS/Vault- ის გარეშე.

16) NFT/SLO (სახელმძღვანელო)

OIDC/JWKS ხელმისაწვდომობა 99. 95% (edge ქეში ამცირებს დამოკიდებულებას).
JWT დანამატი gateway 2-5 ms p95.
ავტორიზაციის შეცდომები ('401') - 0. მთლიანი ტრაფიკის 5% (ბოტების გამოკლებით).
ხელმოწერილი ვებჰუკი: წარმატებით გადამოწმებული წილი 99. 9%, მიწოდების საშუალო შეფერხება 3.

რეზიუმე

დააკავშირეთ მექანიზმები: OAuth2/OIDC + JWT მომხმარებლებისთვის და მდიდარი სერვერის სცენარებისთვის, HMAC ვებჰუკებისთვის/უბრალო პარტნიორებისთვის, ხოლო კრიტიკული ოპერაციებისთვის - mTLS/DPOP. შეინარჩუნეთ მოკლე TTL, კლავიშების როტაცია (JWKS), ABAC/OPA- ს მკაცრი პოლიტიკოსები, დაიცავით კონტურები რეპლიკისა და გაჟონვისგან და ავტომატიზირდით ყველას API Gateway- ის დონეზე. ასე რომ, ავთენტიფიკაცია გახდება პროგნოზირებადი, მასშტაბური და უსაფრთხო - UX კომპრომისის გარეშე და მონეტიზაციისთვის.