احراز هویت API: OAuth2، JWT، HMAC

TL ؛ دکتر متخصص

OAuth2/OIDC + JWT یک استاندارد برای برنامه های کاربردی مشتری و ادغام سرور با مجوز پیچیده (حوزه/نقش/مستاجران)، SSO و کوتاه نشانه TTL است.
امضای HMAC بهترین انتخاب برای وب سایت ها و شرکای ساده «سرور → سرور» با تأیید قطعی و حفاظت قوی در برابر پخش است.
تقویت امنیت: mTLS یا DPoP (نشانه های فرستنده محدود)، TTL کوتاه (5-15 دقیقه)، چرخش کلید (JWKS)، نشانه های تازه سازی با چرخش/ضد استفاده مجدد، اعتبار سنجی دقیق 'aud/iss/exp/nbf/kid' و سیاست به عنوان کد در دروازه.

1) نقشه راه حل: آنچه در آن اعمال می شود

سناریو ها	ما توصیه می کنیم
مشتریان خارجی (وب/iOS/Android)، SSO	OAuth2/OIDC: کد مجوز + PKCE
Server↔server (ادغام دستگاه)	OAuth2 اعتبار مشتری (mTLS/DPoP در صورت امکان)
تماس های شریک ثابت مسیر	OAuth2 یا HMAC (اگر حوزه ها ساده هستند)
وب سایت ها (PSP/ضد تقلب/پرداخت)	امضای HMAC + برچسب زمان + idempotency
ترافیک داخلی شرق و غرب	mTLS + JWT کوتاه (یا مات + خودآزمایی)
معاملات بسیار حساس (پرداخت)	OAuth2 + mTLS/DPoP، در صورت امکان گام به گام (SCA/3DS)

2) OAuth2/OIDC: جریان و مشتریان

2. 1 جریان دارد

کد مجوز + PKCE (وب/موبایل) - کد مجوز را از رهگیری محافظت می کند.
اعتبار مشتری: server↔server بدون کاربر ؛ دامنه - حداقل مورد نیاز است.
کد دستگاه: برای دستگاه های بدون مرورگر.
Refresh Token: فقط برای مشتریان قابل اعتماد چرخش و فعال کردن تشخیص استفاده مجدد.

2. 2 نوع مشتری

محرمانه (سرورها، BFF): حفظ اسرار ؛ استفاده از mTLS

عمومی (SPA/تلفن همراه): راز را نمی توان ذخیره کرد → PKCE، DPoP، TTL کوتاه و دامنه محدود.

3) JWT: ساختار، زمان بندی، تأیید

3. 1 زمینه ها (ادعا)

اجباری: «iss»، «sub»، «aud»، «exp»، «iat»، «nbf»، «jti»، «scope »/« permissions»، «tenant» (اگر چند اجاره نامه)، «kid».

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) نشانه اتصال به مشتری: mTLS، DPoP

mTLS (گواهینامه های مشتری TLS): نشانه صادر شده و معتبر است تنها اگر گواهی مشتری وجود داشته باشد ؛ نشانه خارج از ترکیب کلید + گواهی بی فایده است.
DPoP (تظاهرات اثبات مالکیت): مشتری هر درخواست را با یک کلید یک بار امضا می کند → محافظت در برابر پخش و سرقت توکن در مشتریان عمومی.
برای مسیرهای بحرانی (جهش پرداخت) - نیاز به یکی از مکانیزم.

5) مجوز: حوزه ها، نقش ها، ABAC

دامنه - حداقل اقدامات («پرداخت: نوشتن»، «پرداخت: وضعیت: خواندن»).
نقش ها - واحد برای مدیران ؛ آنها را به طور مستقیم بدون دامنه استفاده نکنید.
ABAC - ویژگی های موجود در نشانه («مستاجر»، «کشور»، «kyc _ level»، «risk _ flags») → سیاست های دروازه/OPA.
سیاست در سطح مسیر/میدان (GraphQL) و در سطح عملیات دامنه (REST/gRPC).

6) امضاهای HMAC: وب سایت ها و شرکا

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: ذخیره «X-Event-Id» در TTL (24h) - تکراری را دور بریزید.

6. 2 بهترین شیوه ها

اسرار در KMS/Vault، چرخش هر 90 روز.

برای مشتریان عمومی، HMAC مناسب نیست (نشت مخفی) ؛ استفاده از OAuth2/DPoP

7) حفاظت در برابر پخش، نیروی بی رحم و نشت

Nonce/' jti 'برای عملیات حساس ؛ لیست سیاه شناسه های مورد استفاده

نرخ/سهمیه: توسط کلید/مشتری/مستاجر/مسیر ؛ عملیات «گران» سهمیه جداگانه است.
IP/ASN/Geo allow-lists برای شرکا و وب سایت ها.
نوع محتوا اجازه می دهد ('application/json')، محدودیت اندازه بدن.
PII ماسک در سیاهههای مربوط ؛ ممنوعیت ورود نشانه/اسرار.

8) خطاها و پاسخ ها (فرمت تک)

ساختار خطا:

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

وضعیت ها:

'401' - هیچ/نشانه نامعتبر (WWW-Authenticate).
403 - حقوق ناکافی (محدوده/ABAC).
'429' - محدودیت/سهمیه.
gRPC: «تأیید نشده »/« اجازه _ رد شده »/« منابع _ خسته شده».

9) شرایط و سیاست های جلسه

≤ دسترسی 15 دقیقه ؛ تازه کردن - چرخش + تشخیص استفاده مجدد (ارسال فراخوان قدیمی - جلسه).
وب سایت HMAC: امضای TTL ≤ 5 دقیقه ؛ تحویل مکرر با عقب نشینی نمایشی.
لغو جلسه/کلید → ورود فوری به لیست لغو (کش در دروازه ≤ 1 دقیقه).

10) قابلیت مشاهده و حسابرسی

همبستگی با 'trace _ id '/' span _ id'.
معیارها: میزان موفقیت auth، '401/403/429'، تاخیر OIDC/JWKS، فرکانس چرخش، استفاده مجدد از تازه کردن، سهم ترافیک DPoP/mTLS.
ورود به سیستم حسابرسی: «چه کسی، چه زمانی، با» زیر/مستاجر/دامنه «باعث چه،» تغییرات کلیدی/مخفی، امضای HMAC شکست خورده است.

11) جاسازی در API دروازه

اعتبار سنجی JWT (حافظه پنهان JWKS) و OPA/ABAC در دروازه.
پروفایل های mTLS برای مشتریان/شرکای قابل اعتماد.
تأیید HMAC از webhooks در لبه (قبل از خدمات داخلی).
سیاست های نرخ/سهمیه بندی، قطع کننده مدار در ارائه دهنده OIDC (cache 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]

شبه: چک کردن HMAC webhook

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-signer: انتشار مجدد کلید، به روز رسانی JWKS، غیرفعال کردن فوری قدیمی ('بچه' → انکار)، تازه کردن ناتوانی، خروج اجباری.
جایگزینی Webhooks: چرخش اسرار، IP اجازه می دهد لیست، تقویت پنجره «X-Timestamp»، تحویل مکرر رویدادهای از دست رفته.
Replay/brute-force: DPoP/mTLS را در مسیرهای بحرانی، سهمیه های باریک، بلوک های موقت توسط IP/ASN فعال کنید، لیست بلوک jti را فعال کنید.
قطع OIDC: تخریب نشانه های ذخیره شده (grace)، ارائه دهنده مدار شکن، اطلاع رسانی مشتری.

14) چک لیست پیاده سازی

احراز هویت (حداقل):

OAuth2: کد + PKCE (وب/موبایل)، اعتبار مشتری (سرور به سرور)
TTL: ≤ دسترسی 15 دقیقه، تازه کردن با چرخش و تشخیص استفاده مجدد
JWKS: دو کلید فعال، 'بچه'، کش ≤ 5 دقیقه
Webhooks: HMAC v1، 'X-Timestamp'، 'X-Event-Id'، ≤ پنجره 300 ثانیه، idemotency
فرستنده محدود: mTLS/DPoP در مسیرهای بحرانی
ABAC/OPA: حوزه + مستاجر/خطر در سیاست های دروازه
نرخ/سهمیه بندی и 429 ؛ لیستهای مجاز IP/ASN برای شرکا
ممیزی و هشدار (401/403/429، استفاده مجدد، امضای HMAC)

حریم خصوصی/ورود به سیستم:

نشانه ها/اسرار/بدن کامل کارت را وارد نکنید
ماسک PII ؛ پشتیبانی DSAR ؛ عمر مفید سیاهههای مربوط محدود است

15) ضد الگوهای

'alg = none' یا اعتماد به یک توکن بدون تایید امضا/JWKS.
نشانه های دسترسی طولانی مدت (ساعت/روز).
یک راز HMAC مشترک برای همه شرکا.
وب سایت بدون برچسب زمان/idemotency.
تازه کردن نشانه بدون چرخش و بدون تشخیص استفاده مجدد.
فقدان اعتبار سنجی «aud »/« iss» و چرخش «کودک».
ذخیره اسرار در متغیرهای محیطی بدون KMS/Vault.

16) NFT/SLO (نشانه ها)

در دسترس بودن OIDC/JWKS ≥ 99. 95٪ (کش لبه وابستگی را کاهش می دهد).
افزودنی اعتبار سنجی JWT در دروازه ≤ 2-5 ms p95.
خطای احراز هویت ('401') ≤ 0. 5٪ از کل ترافیک (به استثنای رباتها).
Signed webhooks: سهم 99 ≥ با موفقیت تایید شده است. 9٪، میانگین تاخیر تحویل ≤ 3 ثانیه.

خلاصه

مکانیزم های ترکیبی: OAuth2/OIDC + JWT برای کاربران و اسکریپت های سرور غنی، HMAC برای وب سایت ها/شرکای ساده و برای عملیات بحرانی - mTLS/DPoP. TTL های کوتاه، چرخش های کلیدی (JWKS)، سیاست های دقیق ABAC/OPA، محافظت از حلقه ها از پخش و نشت، و خودکار سازی همه چیز در سطح API Gateway. بنابراین احراز هویت قابل پیش بینی، مقیاس پذیر و امن خواهد بود - بدون مصالحه برای UX و کسب درآمد.

احراز هویت API: OAuth2، JWT، HMAC

TL ؛ دکتر متخصص

مثال محدوده سیاست (ایده OPA/Rego)

خلاصه

با ما در تماس باشید

ارتباط سریع

ویدئو به‌زودی به‌روزرسانی می‌شود

ما در حال حاضر بسیار درگیر پروژه‌ها هستیم