API უსაფრთხოება და ნიშნები

მოკლე რეზიუმე

API- ს უსაფრთხოება არის ავტორიზაციის, ავტორიზაციის, კრიპტოგრაფიული დაცვის მექანიზმების ერთობლიობა, ანტი-ბოროტად გამოყენება და დაკვირვება, რაც ითვალისწინებს, რომ მოთხოვნა ითვალისწინებს მოსალოდნელ რესურსს მოსალოდნელ კონტექსტში. საკვანძო არტეფაქტი არის ნიშანი (ან მოთხოვნის ხელმოწერა), რომელიც ამტკიცებს ზარის უფლებას. კარგი არქიტექტურა ეყრდნობა მოკლევადიან ნიშანს, მკაფიო ნაგავს, მინიმალურ შეღავათებს, გამეორებისგან დაცვას, გამეორებას და ოპერაციულ პროცედურებს (როტაცია, აუდიტი, ინციდენტები).

API ავთენტიფიკაციის მოდელები: როდის და რა უნდა აირჩიოთ

API გასაღები (სტატიკური საიდუმლო)

მარტივი B2B ინტეგრაციისა და დაბალი კორექციის სცენარებისთვის. იგი არ ახდენს კონტექსტს, მოითხოვს შენახვას მომსახურების მხარეს.
გამოიყენეთ მხოლოდ IP/ASN ალოუ-ლისტიდან, ფიქსირებული კვოტებით, მოკლე TTL და როტაციებით.

OAuth 2. 1 / OIDC

მომხმარებლის და პარტნიორობის სტანდარტი: შეჯახება ტოკენი (ხანმოკლე) + refresh token (როტაცია) + ნაკრები.
საზოგადოებრივი კლიენტები - PKCE- ით; Confidential კლიენტები - კლიენტის საიდუმლოებით/mTLS.

Client Credentials (m2m)

მანქანა არის მანქანა: ტოკენის წვდომა მომსახურებისთვის მკაცრად განსაზღვრული აპარატებისა და აუდიტორიისთვის, ხშირად რეფრესის გარეშე (ხელახლა მიღება).

mTLS (ურთიერთგამომრიცხავი TLS)

აკავშირებს პირადობას არხთან. იდეალურია მაღალი რისკის ან გადახდის ინტეგრაციისთვის (POP TLS თავზე).
იგი შეიძლება გაერთიანდეს 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

გაუმჭვირვალე იდენტიფიკატორები შემოწმებულია introspection საშუალებით Authorization Server- ში - გააზრება/ცენტრალიზაცია უფრო ადვილია.

PoP/DPoP

ნიშნის დაკავშირება კლიენტის ღილაკზე ან TLS სესიაზე, ამცირებს მოპარული ნიშნის ღირებულებას.

ნიშნის შინაარსი: მინიმალური საკმარისი

რეკომენდებული სტიგმები (JWT):

'iss' (issuer), 'sub' (subect), 'aud' (სამიზნე სისტემა/რესურსი), 'exp' (ვადა), 'iat', 'nbf' (სურვილისამებრ), 'jti'.
'scope '/' permissions' (მინიმალური აუცილებელი), 'tenant' (მრავალმხრივი), 'device _ compliant '/' amr' (ავთენტიფიკაციის მეთოდი), 'ip '/' asn' (თუ იგი გამოიყენება პოლიტიკასთან).

წესები:

მოკლე TTL წვდომისთვის (5-15 წუთი), რეფრესი - 12-48 საათი (მბრუნავი როტაციით).
აუდიტორია ('aud') მკაცრად სპეციფიკური რესურსია, წინააღმდეგ შემთხვევაში ნიშანი „მეორადი“.
Scoops - მოქმედება და ობიექტი (მაგალითად, 'payments: withdraw). read`).
ზომა - 2-4 KB ევრო სათაურებისა და მარიონეტებისთვის; წინააღმდეგ შემთხვევაში, გეითვეებთან დაკავშირებული პრობლემები შესაძლებელია.

ავტორიზაცია და პოლიტიკა

RBAC + ABAC: როლი + კონტექსტი (ორგანიზაცია, გეო, რისკი, მოწყობილობის მდგომარეობა).
PEP/PDP: ნიშნის შემოწმება და გადაწყვეტილების მიღება API კარიბჭეზე/მარიონეტულ (Envoy/OPA) განაცხადამდე.
დეკლარაციული წესები: შეინახეთ Git- ში, გაიარეთ პოლიტიკა-tests CI- ში.

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

საჭიროების შემთხვევაში: ვებჰუკი, ინტეგრაცია 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 წუთი და არ მიიღოთ გამეორება (გამეორება).
ხელი მოაწერეთ მოთხოვნის კანონიზებულ პრეზენტაციას (მეთოდი, გზა, დედოფალი, სხეულის ჰაში).

Idempotence და გარიგების დაცვა

Idempotence-Key ჩამოწერის/გადახდის/შექმნის ოპერაციებისთვის: იგივე გასაღები იგივე ეფექტი.
გასაღების სიცოცხლის ხანგრძლივობა არის ბიზნეს ტაიმუტის დრო (ჩვეულებრივ, 24-72 საათი).
ლოგიკა სერვერის მხარეს: შეადარეთ მოთხოვნის პარამეტრები ადრე დაფიქსირებულ გასაღებთან.

ბრაუზერი და მობილური მომხმარებლები

PKCE აუცილებლად (საჯარო კლიენტები).
ბრაუზერში Refresh ნიშნის თავიდან აცილება; საჭიროების შემთხვევაში - ROTATION + რეაგირება გამეორებაზე.
შენახვა: სესიის სცენა> ადგილობრივი სცენა; უკეთესია - backend for frontend (BFF) პასუხისმგებელია ნიშნებზე.
SameSite, Secure, HttpOnly для cookie; CORS - აშკარა ალოუ-ლისტები, სათაურები და მეთოდები; preflight kashing უსაფრთხოა.

m2m და მაღალი რისკის ინტეგრაცია

mTLS + OAuth2 Client Credentials ერთად ნაკრები და 'aud'.
IP/ASN ალოუ სია გეითვეიზე.
PoP/DPOP ან HMAC ხელმოწერები TLS- ზე კრიტიკული ოპერაციებისთვის.
კვოტები და ორგანიზაციის/კლიენტის/გასაღები ლიმიტები.

როტაცია, მოხსნა და რეაგირება ინციდენტებზე

ხელმოწერის საიდუმლოებებისა და გასაღებების როტაცია (JWKS): ინციდენტის დროს + გრაფიკის მიხედვით.
Dual-key rollout: გამოაქვეყნეთ ახალი საკვანძო წყვილი წინასწარ (kid2), გააფორმეთ მისი ნიშნები, შეინარჩუნეთ ძველი (kid1) TTL- ის ამოწურვამდე.
Refresh-rotation: თითოეული გაცვლა refresh არის ახალი ნიშანი, ძველი დაუყოვნებლივ ხდება არასწორი; გამეორება - კომპრომისული სიგნალი.
Revocation: JWT- სთვის - მოკლე დროში ამოღებული „jti“ სიები; ტოქსინების გამოსწორებისთვის - დაუყოვნებლივი დაბლოკვა AS- ზე.
სკრიპტები break-glass: დროებითი სტატიკური კრედიტები მინიმალური უფლებებით და მკაცრი TTL, ჩაწერეთ ჟურნალში.

Rate limiting, bott დაცვა და დაცვა

სამსაფეხურიანი ლიმიტები: per-key/per-IP/per ორგანიზაცია.
Burst + sustained: docken სატანკო/მოცურების ფანჯარა.
რთული შემოწმებები: მოწყობილობა fingerprint, ქცევითი სიგნალები, geo/ASN ანომალიები, CAPTCHA მხოლოდ UI- სთვის.
Lockout/slowdown ხელმოწერის/NMAS და ავთენტიფიკაციის წარუმატებელი მცდელობებით.

ლოჯისტიკა, მეტრიკა და SLO

ლოგოების მინიმალური ნაკრები: 'request _ id', 'client _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn', 'latency', '@ ta _ statatate'.

მეტრიკა:

ტოქსინების ვალიდაციის წარმატება (%), გადამოწმების დრო p95.
Replay გადახრების სიხშირე, Idempotency-Key დუბლიკატები.
მოთხოვნის წილი PoP/DpoP/mTLS- ით.
'aud/scope' შეცდომები, ამოიწურა 'exp', დროის ცვლა (NTP).

SLO (მაგალითები):

Auth/AS-99 ხელმისაწვდომობა. 95 %/თვე; p95 introspection ≤ 50 мс.
TTL <60 c ტოქსინების ნული გაყიდვაში (უსაფრთხოების მეტრი).
0-ზე ნაკლები. 1% შეცდომები 'aud/scope' დღეში (ინტეგრაციის ხარისხი).

კონფიგურაციის მაგალითები

Envoy: JWT და აუდიტი

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..."))

სერვერი უარყოფს, თუ 300 გ-ზე მეტი არ არის, 'n' უკვე შეხვდა ან 's' არ სცემს.

მონაცემთა დაცვა და კონფიდენციალურობა

მინიმუმამდე დაიყვანეთ სტიგმები (განსაკუთრებით PII) და სიცოცხლის ხანგრძლივობა.
დაშიფრეთ მგრძნობიარე სტიგმები (JWE) მესამე მხარის ინტეგრაციისთვის.
Mask/DLP ლოგოებში: არ მოაწყოთ სხეულები PAN/PII, ნიშნები - მხოლოდ 'kid '/დროშები, არა თავად საიდუმლო.

ტიპიური შეცდომები

გრძელი წვდომის ნიშნები და „მარადიული“ რეფრესი.
'aud '/' scope' - ის არარსებობა მრავალფუნქციურია.
ვებჰუკების ხელმოწერა 'timestamp '/' nonce' გარეშე.
JWT შემოწმება მხოლოდ განაცხადში და არა გეითვეიზე (PEP).
როტაციების არარსებობა და ორმაგი კეი rollout.
CORS „“ და ნებადართული დაუცველი მეთოდები სათაურების კონტროლის გარეშე.
ტოქსინების შენახვა 'localStorage- ში' BFF- ის გარეშე.

გზის განხორციელების რუკა

1. API- ს ინვენტარიზაცია და კლასიფიკაცია (საჯარო/პარტნიორი/შიდა, მგრძნობელობა).
2. AuthN მოდელის არჩევანი: OAuth2/OIDC მომხმარებლებისთვის, mTLS + Client Credentials/HMAC m2m.
3. ნიშნები: მოკლე TTL, მკაცრი 'aud', ნაკრები, DPOP/PoP კრიტიკული ოპერაციებისთვის.
4. PEP gateway- ზე: JWT შესაბამისობა, ხელმოწერები და დაბალანსებული ლიმიტები განაცხადამდე.
5. Anti replay და idempotence: timestamp/nonce/Idempotency-Key.
6. როტაცია და JWKS: ორმაგი კეი, ავტომატიზაცია და ალერტინგი.
7. დაკვირვება: მეტრიკა/SLO, წვდომის ჟურნალები, UEBA სიგნალები.
8. სავარჯიშოები: ხელმოწერის გასაღების ამოღება, რეფრესის გაჟონვა, კვოტების გადატვირთვა.

სპეციფიკა iGaming/fintech

გადახდა/გადახდა: მხოლოდ mTLS + PoP/HMAC, მკაცრი პაკეტები ('withdraw. create '), idempotence სავალდებულოა.
პარტნიორები (PSP/შინაარსის პროვაიდერები): per-partner გასაღებები/სერთიფიკატები, IP/ASN allow-list, ინდივიდუალური კვოტები და დაშბორდები.
GDPR/PCI DSS: სტიგმების შემცირება, მესამე მხარის ტენდენციებში PII- ს აკრძალვა, მგრძნობიარე რესურსებზე წვდომის გაუმჯობესება, რეგულარული წვდომის მიმოხილვა.
Anti-abuse: ქცევითი ლიმიტები, გეო კონტროლი, დაცვა ბონუს აბუზისგან API დონეზე.

FAQ

JWT თუ რეფერენციული ტოკენი?
JWT - პროდუქტიულობა და ავტონომია; reference არის ცენტრალიზებული მიმოხილვა და ინციდენტის რეაქციის სიმარტივე. ხშირად ჰიბრიდი: გარეგანი - JWT, შიდა - რეფერაცია.

სჭირდება JWE?
მხოლოდ იმ შემთხვევაში, თუ payload შეიცავს PII/საიდუმლოებებს. წინააღმდეგ შემთხვევაში - JWS მინიმალური სტიგმებით.

შესაძლებელია API კლავიშებზე ცხოვრება?
დიახ, მაგრამ მხოლოდ მოკლე TTL, მკაცრი კვოტებით, IP-allow-list და მოთხოვნის ხელმოწერა. მომხმარებლებისთვის - სასურველია OAuth/OIDC.

DPOP/PoP ნამდვილად?
ყოველთვის არა. მაგრამ მაღალი დონის ოპერაციებისთვის (გადახდები, დასკვნები) - უკიდურესად სასურველია.

შედეგი

API- ს საიმედო უსაფრთხოება ემყარება მოკლევადიან ნიშნებს, ზუსტი პასაჟებსა და აუდიტორიას, რომლებიც დაცულია არხებით (TLS/mTLS), მოთხოვნების ხელმოწერებსა და მკაცრ ანტირელიგიურ დაცვას, რომლებიც გაძლიერებულია ლიმიტებით და დაკვირვებით. დაამატეთ ავტომატიზირებული როტაციები, ორმაგი კეი როლოტი და პოლიტიკური კონტროლი გეითვეებზე - და თქვენი API გახდება გამძლე გაჟონვის, გამეორებისა და ბოროტად გამოყენების მიმართ, ხოლო შეინარჩუნებს მაღალ პროდუქტიულობას და მართვას.