مصادقة API: OAuth2، JWT، HMAC

TL; د

OAuth2/OIDC + JWT هو معيار لتطبيقات العملاء وتكامل الخادم مع الترخيص المعقد (النطاقات/الأدوار/المستأجرين)، SSO ورموز TTL القصيرة.
توقيعات HMAC هي الخيار الأفضل لخطابات الويب ومكالمات الشريك البسيطة «server→server» مع التحقق الحتمي والحماية القوية من إعادة التشغيل.
تعزيز الأمان: mTLS أو DPoP (رموز مقيدة بالمرسل)، TTL قصيرة (5-15 دقيقة)، دوران المفتاح (JWKS)، تحديث الرموز المميزة بالتناوب/منع إعادة الاستخدام، التحقق الصارم 'aud'/iss/exp/nbf/kid' والسياسة كرمز على البوابة.

1) خريطة الحل: ما الذي يجب تطبيقه حيث

2) OAuth2/OIDC: التدفقات والعملاء

2. 1 التدفقات

رمز الترخيص + PKCE (Web/Mobile) - يحمي رمز الترخيص من الاعتراض.
وثائق تفويض العملاء: server↔server بدون مستخدم ؛ النطاقات - الحد الأدنى المطلوب.
رمز الجهاز: للأجهزة بدون متصفح.
Refresh Token: للعملاء الموثوق بهم فقط ؛ الدوران وتمكين الكشف عن إعادة الاستخدام.

2. 2 أنواع العملاء

السرية (الخوادم، BFF): الاحتفاظ بالأسرار ؛ استخدام mTLS.
Public (SPA/mobile): لا يمكن تخزين السر → PKCE و DPoP و TTL قصير ونطاقات محدودة.

3) JWT: الهيكل والتوقيت والتحقق

3. 1 حقول (مطالبات)

إلزامي: "iss'،" sub "،" aud'، "exp"، "iat'،" nbf "،" jti "،" scope "/" الأذونات "،" المستأجر "(إذا كان متعدد الإيجارات)،" طفل ".

3. 2 العمر

رمز الوصول: 5-15 دقيقة.
رمز التحديث: أيام/أسابيع، تناوب مع كل تبادل ؛ عند إعادة تقديم القديم، نقوم بعرقلة الجلسة.

انحراف الساعة: التسامح ≤ 60 ثانية

3. 3 JWKS والمفاتيح

تخزين المفاتيح في KMS/Vault، «طفل» مطلوب.
مفتاحان نشطان (متدحرجان)، يعاد إصدارهما مرة كل 60-90 يومًا أو في حادث.
مخبأ JWKS على البوابة ≤ 5 دقائق، مع إعاقة تلقائية.

3. 4 التحقق من البوابة/الخدمات

تحقق: التوقيع، 'aud' (الخدمات المعتمدة)،' is '،' exp/nbf '، قائمة الأقفال (الإلغاء).
لا تثق في ميادين من الهيئة دون التحقق من التوقيع ؛ تجاهل «alg = لا شيء».

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

4) رمز ملزم للعميل: mTLS و DPoP

mTLS (شهادات عميل TLS): يتم إصدار الرمز المميز والتحقق من صحته فقط إذا كانت هناك شهادة عميل → الرمز المميز عديم الفائدة خارج مجموعة شهادات المفتاح +.
DPoP (إثبات إثبات الحيازة): يوقع العميل على كل طلب بمفتاح حماية → لمرة واحدة ضد إعادة التشغيل وسرقة الرموز في العملاء العامين.
بالنسبة للطرق الحرجة (طفرات الدفع) - يتطلب إحدى الآليات.

5) الإذن: النطاقات والأدوار، ABAC

النطاقات - الحد الأدنى من الإجراءات («المدفوعات: الكتابة»، «المدفوعات: الحالة: قراءة»).
الأدوار - وحدات الإداريين ؛ لا تستخدمها مباشرة بدون نطاقات.
ABAC - سمات في الرمز ("المستأجر"، "البلد"، "kyc _ level'،" المخاطر _ الأعلام ") → السياسات على البوابة/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» المنتهية الصلاحية/المستقبلية.
الخصوصية: قم بتخزين "X-Event-Id' على TTL (24 ساعة) - تم التخلص من النسخ المكررة.

6. 2 أفضل الممارسات

أسرار في KMS/Vault، تدور كل 90 يومًا.
بالنسبة للعملاء العموميين، HMAC غير مناسبة (التسريبات السرية) ؛ استخدام OAuth2/DPoP.

7) الحماية من الإعادة والقوة الغاشمة والتسريبات

Nonce/' jti 'للعمليات الحساسة ؛ القائمة السوداء لمعرفات الهوية المستعملة.
المعدل/الحصص: حسب المفتاح/العميل/المستأجر/المسار ؛ العمليات «باهظة الثمن» هي حصص منفصلة.
قوائم السماح للشركاء والشبكات الشبكية.
يسمح نوع المحتوى («تطبيق/جسون»)، حد حجم الجسم.
إخفاء PII في جذوع الأشجار ؛ حظر تسجيل الرموز/الأسرار.

8) الأخطاء والإجابات (تنسيق واحد)

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

• «401» - لا يوجد رمز مميز/غير صالح (WWW-Authenticate).
• «403» - حقوق غير كافية (النطاق/ABAC).
• «429» - حدود/حصص.
• gRPC: 'UNAUTHENTICATED '/' PERMISSION _ DENCED '/' RESOURCE _ EXCOUSTED'.

9) سياسات المدة والدورات

الوصول ≤ 15 دقيقة ؛ التحديث - الدوران + الكشف عن إعادة الاستخدام (تم استدعاء الجلسة القديمة).
HMAC: توقيعات TTL ≤ 5 دقائق ؛ التسليم المتكرر مع التراجع الأسي.
الجلسة/الإلغاء الرئيسي → الدخول الفوري إلى قائمة الإلغاء (مخبأ على البوابة ≤ 1 دقيقة).

10) قابلية الملاحظة ومراجعة الحسابات

الترابط بواسطة 'trace _ id '/' span _ id'.
المقاييس: معدل نجاح auth، '401/403/429'، زمن انتقال OIDC/JWKS، تردد الدوران، إعادة استخدام التحديث، حصة حركة مرور DPoP/mTLS.
سجل التدقيق: «من، عندما تسبب» المستأجر الفرعي/النطاق «في ماذا»، تغييرات المفتاح/السرية، توقيعات HMAC الفاشلة.

11) تضمين واجهة برمجة التطبيقات في البوابة

التحقق من صحة JWT (مخبأ JWKS) و OPA/ABAC على البوابة.
MTLS profiles للعملاء/الشركاء الموثوق بهم.
التحقق من HMAC لخطافات الويب على حافة الهاوية (قبل الخدمات الداخلية).
سياسات المعدل/الحصص، قاطع الدائرة على مزود 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

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، التعطيل الفوري للقديم («طفل» → إنكار)، تحديث الإعاقة، الإخراج القسري.
استبدال خطوط الويب: تدوير الأسرار، قائمة السماح ببروتوكول الإنترنت، تضخيم نافذة «X-Timestamp»، التسليم المتكرر للأحداث الفائتة.
إعادة التشغيل/القوة الغاشمة: تمكين DPoP/mTLS على الطرق الحرجة، والحصص الضيقة، والكتل المؤقتة بواسطة IP/ASN، وتمكين قائمة كتل 'jti'.
OIDC الانقطاع: تدهور الرموز المخبأة (النعمة)، مزود قاطع الدائرة، إشعار العملاء.

14) قوائم التنفيذ المرجعية

• OAuth2: Code + PKCE (Web/Mobile), Client Credicals (server-to-server)
• TTL: الوصول ≤ 15 دقيقة، التحديث مع الدوران واكتشاف إعادة الاستخدام
• JWKS: مفتاحان نشطان، «طفل»، مخبأ ≤ 5 دقائق
• خطافات الويب: HMAC v1، "X-Timestamp"، "X-Event-Id'، النافذة ≤ 300 ثانية، الغباء
• مقيد المرسل: mTLS/DPoP على الطرق الحرجة
• ABAC/OPA: النطاقات + المستأجر/المخاطر في سياسات البوابة
• المعدل/الحصة и 429 ؛ قوائم السماح لشركاء التنفيذ/ASN
• مراجعة الحسابات والتنبيهات (401/403/429، إعادة استخدام التحديث، توقيعات HMAC)

• لا تسجل الرموز/الأسرار/هيئات البطاقة الكاملة
• قناع PII ؛ دعم منطقة DSAR ؛ مدة صلاحية جذوع الأشجار محدودة

15) الأنماط المضادة

'alg = لا شيء' أو الثقة في رمز بدون التحقق من التوقيع/JWKS.
رموز الوصول طويلة العمر (ساعات/يوم).
سر واحد مشترك لـ HMAC لجميع الشركاء.
خطافات الويب بدون طابع زمني/خمول.
قم بتحديث الرموز بدون دوران ودون إعادة استخدام الكشف.
عدم التحقق من صحة 'aud'/' iss' وتناوب' الأطفال '.
تخزين الأسرار في متغيرات البيئة بدون KMS/Vault.

16) NFT/SLO (معالم)

توافر مركز البيانات الدولي/مراكز العمل المشتركة ≥ 99. 95٪ (يقلل مخبأ الحافة من التبعية).
مادة مضافة للتحقق من صحة JWT على البوابة ≤ 2-5 ms p95.
أخطاء التوثيق ('401') ≤ 0. 5٪ من إجمالي حركة المرور (باستثناء الروبوتات).
خطوط الويب الموقعة: حصة ≥ 99 التي تم التحقق منها بنجاح. 9٪، متوسط تأخير التسليم ≤ 3 ث.

موجز

دمج الآليات: OAuth2/OIDC + JWT للمستخدمين ونصوص الخوادم الغنية، HMAC لخطابات الويب/الشركاء البسطاء، وللعمليات الهامة - mTLS/DPoP. احتفظ بـ TTLs القصيرة، ودوران المفاتيح (JWKS)، وسياسات ABAC/OPA الصارمة، وحماية الحلقات من إعادة التشغيل والتسريبات، وأتمتة كل شيء على مستوى API Gateway. لذلك ستصبح المصادقة قابلة للتنبؤ وقابلة للتطوير وآمنة - دون تنازلات عن UX وتحقيق الدخل.