نظرة عامة على سياستَي JWS وJWT

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلىمستندات Apigee X. info

يقدّم هذا الموضوع معلومات عامة عن JWT (رمز JSON المميّز للويب) وJWS (توقيع JSON على الويب) وسياسات JWS/JWT في Apigee التي قد تهمّ مطوّري وكلاء Apigee.

مقدمة

يتم استخدام كل من JWS وJWT بشكل شائع لمشاركة الطلبات أو التأكيدات بين التطبيقات المتصلة تتيح سياسات JWS/JWT لوكلاء Edge API ما يلي:

  • إنشاء رمز JWT أو JWS موقَّع.
  • التحقّق من رمز JWT أو JWS موقَّع والطلبات ضِمن JWS/JWT.
  • فك ترميز رمز JWT أو JWS موقَّع بدون التحقّق من صحة التوقيع.

في الحالتَين الأخيرتَين، تضبط السياسة أيضًا متغيّرات تسمح لسياسات إضافية أو لل خدمات الخلفية نفسها بفحص الطلبات التي تم التحقّق منها واتّخاذ قرارات استنادًا إلى هذه الطلبات.

عند استخدام سياسة التحقّق من JWS/JWT، سيتم رفض رمز JWS/JWT غير الصالح وسيؤدي إلى ظهور حالة خطأ. وبالمثل، عند استخدام سياسة فك ترميز JWS/JWT، سيؤدي رمز JWS/JWT الذي تم تنسيقه بشكل غير صحيح إلى ظهور حالة خطأ

الفيديوهات

يمكنك مشاهدة فيديو قصير للحصول على مقدّمة سريعة عن JWT. على الرغم من أنّ هذا الفيديو خاص بإنشاء رمز JWT، فإنّ العديد من المفاهيم هي نفسها بالنسبة إلى JWS.

يمكنك مشاهدة فيديو قصير لمعرفة المزيد عن بنية JWT.

حالات الاستخدام

يمكنك استخدام سياسات JWS/JWT من أجل:

  • إنشاء رمز JWS/JWT جديد على جانبَي نقطة نهاية الوكيل أو نقطة النهاية المستهدَفة في وكيل Edge. على سبيل المثال، يمكنك إنشاء مسار طلب وكيل ينشئ رمز JWS/JWT ويعرضه على العميل. أو يمكنك تصميم وكيل ينشئ رمز JWS/JWT في مسار طلب نقطة النهاية المستهدَفة، و يرفقه بالطلب المُرسَل إلى نقطة النهاية المستهدَفة. ستكون هذه الطلبات متاحة بعد ذلك لتمكين الخدمات الخلفية من تطبيق المزيد من إجراءات الأمان.
  • التحقّق من الطلبات واستخراجها من رمز JWS/JWT تم الحصول عليه من طلبات العملاء الواردة أو من ردود الخدمة المستهدَفة أو من ردود سياسة استدعاء الخدمة أو من مصادر أخرى سيتحقّق Edge من التوقيع على رمز JWS/JWT، سواء تم إنشاء رمز JWS/JWT بواسطة جهة خارجية أو بواسطة Edge نفسه، باستخدام خوارزميات RSA أو HMAC.
  • فك ترميز رمز JWS/JWT يكون فك الترميز مفيدًا جدًا عند استخدامه بالتزامن مع سياسة التحقّق من JWS/JWT، عندما يجب معرفة قيمة طلب (JWT) أو عنوان (JWS/JWT) من داخل رمز JWS/JWT قبل التحقّق من رمز JWS/JWT.

أجزاء رمز JWS/JWT

يرمّز رمز JWS/JWT الموقَّع المعلومات في ثلاثة أجزاء مفصولة بنقاط: العنوان والحمولة والـ توقيع:

header.payload.signature
  • تنشئ سياسة إنشاء JWS/JWT جميع الأجزاء الثلاثة.
  • تفحص سياسة التحقّق من JWS/JWT جميع الأجزاء الثلاثة.
  • تفحص سياسة فك ترميز JWS/JWT العنوان والحمولة فقط.

يتيح JWS أيضًا تنسيقًا منفصلاً يحذف الحمولة من JWS:

header..signature

باستخدام JWS منفصل، يتم إرسال الحمولة بشكل منفصل عن JWS. يمكنك استخدام العنصر <DetachedContent> في سياسة التحقّق من JWS لتحديد حمولة JWS الأولية غير المرمّزة. بعد ذلك، تتحقّق سياسة التحقّق من JWS من رمز JWS باستخدام العنوان والتوقيع في JWS والحمولة المحدّدة بواسطة العن0/}صر.<DetachedContent>

لمعرفة المزيد عن الرموز المميّزة وكيفية ترميزها وتوقيعها، يُرجى الاطّلاع على ما يلي:

الاختلافات بين JWS وJWT

يمكنك استخدام JWT أو JWS لمشاركة الطلبات أو التأكيدات بين التطبيقات المتصلة. ويتمثل الاختلاف الرئيسي بينهما في تمثيل الحمولة:

  • JWT
    • الحمولة هي دائمًا عنصر JSON
    • يتم إرفاق الحمولة دائمًا برمز JWT
    • يتم دائمًا ضبط عنوان typ للرمز على JWT
  • JWS
    • يمكن تمثيل الحمولة بأي تنسيق، مثل عنصر JSON أو دفق بايت أو دفق ثماني أو غير ذلك
    • ليس من الضروري إرفاق الحمولة برمز JWS

بما أنّ تنسيق JWT يستخدم دائمًا عنصر JSON لتمثيل الحمولة، فإنّ سياستَي إنشاء JWT والتحقّق من JWT في Edge تتضمّنان دعمًا مدمجًا للتعامل مع أسماء الطلبات المسجّلة الشائعة، مثل aud، iss، sub وغيرها. ما يعني أنّه يمكنك استخدام عناصر سياسة إنشاء JWT لضبط هذه الطلبات في الحمولة، وعناصر سياسة التحقّق من JWT للتحقّق من قيمها. لمزيد من المعلومات، يُرجى الاطّلاع على قسم أسماء الطلبات المسجّلة في مواصفات JWT.

بالإضافة إلى إتاحة أسماء الطلبات المسجّلة معيّنة، تتيح سياسة إنشاء JWT مباشرةً إضافة طلبات بأسماء عشوائية إلى JWT. كل طلب هو زوج بسيط من الاسم/القيمة، ويمكن أن تكون القيمة من نوع رقم أو منطقي أو سلسلة أو خريطة أو مصفوفة.

بما أنّ JWS يمكنه استخدام أي تمثيل للبيانات للحمولة، لا يمكنك إضافة طلبات إلى الحمولة. تتيح سياسة إنشاء JWS إضافة طلبات بأسماء عشوائية إلى عنوان JWS. بالإضافة إلى ذلك، تتيح سياسات JWS حمولة منفصلة، حيث يحذف JWS الحمولة. تتيح لك الحمولة المنفصلة إرسال JWS والحمولة بشكل منفصل، ويتطلبها العديد من معايير الأمان.

منع إدخال النماذج عند استخدام JWS وJWT

لمنع الإفصاح غير المصرّح به عن البيانات، اتّبِع هذه الإرشادات عند استخدام سياستَي GenerateJWT أو GenerateJWS:

  • تجنُّب الإشارات المباشرة إلى بيانات أدخلها المستخدم: لا تستخدِم أبدًا إدخالات غير موثوق بها (مثل request.queryparam.* أو request.header.*) مباشرةً في سمة ref التي تتيح إنشاء النماذج.
  • تنظيف الإدخالات: إذا كان عليك استخدام بيانات خارجية في طلب JWT/JWS، استخدِم أولاً سياسة AssignMessage لإزالة أي أقواس معقوفة ({ }) أو أحرف نماذج أخرى من الإدخال قبل الإشارة إليه.
  • استخدام طلبات صريحة للسلاسل: بالنسبة إلى طلبات السلاسل البسيطة، تجنَّب type="map". يمنع استخدام type="string" التلقائي إنشاء النماذج الضمني للقيمة المُشار إليها.
  • ملاحظة التناقض في السلوك بين سياستَي التحقّق والإنشاء: تختلف سياسات إنشاء JWS و JWT عن سياسات التحقّق في ما يتعلق بإنشاء النماذج.

لمحة عن خوارزميات التوقيع

تتيح سياستَا التحقّق من JWS/JWT وإنشاء JWS/JWT خوارزميات RSA وRSASSA-PSS وECDSA وHMAC، باستخدام مجموعات SHA2 من قوة البت 256 أو 384 أو 512. تعمل سياسة فك ترميز JWS/JWT بغض النظر عن الـ خوارزمية التي تم استخدامها لتوقيع JWS/JWT.

خوارزمية HMAC

تعتمد خوارزمية HMAC على المفتاح السري المشترك، لإنشاء الـ توقيع (المعروف أيضًا باسم توقيع JWS/JWT) وللتحقّق من التوقيع.

يعتمد الحد الأدنى لطول المفتاح السري على قوة البت في الخوارزمية:

  • HS256: الحد الأدنى لطول المفتاح هو 32 بايت
  • HS386: الحد الأدنى لطول المفتاح هو 48 بايت
  • HS512: الحد الأدنى لطول المفتاح هو 64 بايت

خوارزمية RSA

تستخدم خوارزمية RSA زوجًا من المفاتيح العلنية والخاصة للتوقيع المشفر. باستخدام توقيعات RSA ، يستخدم الطرف الذي يوقّع مفتاح RSA خاصًا لتوقيع JWS/JWT، ويستخدم الطرف الذي يتحقّق من صحة التوقيع مفتاح RSA العلني المطابق للتحقّق من التوقيع على JWS/JWT. ما مِن متطلبات بشأن حجم المفاتيح.

خوارزمية RSASSA-PSS

خوارزمية RSASSA-PSS هي تعديل على خوارزمية RSA. على غرار RSS، تستخدم خوارزمية RSASSA-PSS زوجًا من المفاتيح العلنية والخاصة لـ RSA للتوقيع المشفر. يكون تنسيق المفتاح هو نفسه بالنسبة إلى RSS. يستخدم الطرف الذي يوقّع مفتاحًا خاصًا لتوقيع JWS/JWT، ويستخدم الطرف الذي يتحقّق من صحة التوقيع المفتاح العلني المطابق للتحقّق من التوقيع على JWS/JWT. ما مِن متطلبات بشأن حجم المفاتيح.

خوارزمية ECDSA

خوارزمية توقيع المنحنى الإهليلجي الرقمي (ECDSA) هي خوارزمية تشفير منحنى إهليلجي مع منحنى P-256 وP-384 وP-521. عند استخدام خوارزميات ECDSA، تحدّد الخوارزمية نوع المفتاح العلني والخاص الذي يجب تحديده:

الخوارزمية المنحنى المتطلبات الأساسية
ES256 P-256 مفتاح تم إنشاؤه من منحنى P-256 (المعروف أيضًا باسم secp256r1 أو prime256v1)
ES384 P-384 مفتاح تم إنشاؤه من منحنى P-384 (المعروف أيضًا باسم secp384r1)
ES512 P-521 مفتاح تم إنشاؤه من منحنى P-521 (المعروف أيضًا باسم secp521r1)

خوارزميات تشفير المفتاح

تتيح سياسات JWS/JWT جميع خوارزميات تشفير المفتاح التي تتيحها OpenSSL.

استخدام مجموعة مفاتيح JSON للويب (JWKS) للتحقّق من JWS/JWT

عند التحقّق من رمز JWS/JWT موقَّع، عليك تقديم المفتاح العلني المرتبط بالمفتاح الخاص المستخدَم لتوقيع الرمز. أمامك خياران لـ تقديم المفتاح العلني إلى سياسات التحقّق من JWS/JWT:

  • استخدام قيمة المفتاح العلني الفعلية (يتم تقديمها عادةً في متغيّر مسار)، أو
  • استخدام مفتاح علني مضمّن في JWKS

لمحة عن JWKS

‫JWKS هو بنية JSON تمثّل مجموعة من مفاتيح JSON للويب (JWK). ‫JWK هو بنية بيانات JSON تمثّل مفتاح تشفير. يتم وصف JWK وJWKS في RFC7517. يمكنك الاطّلاع على أمثلة JKWS في الملحق أ. أمثلة على مجموعات مفاتيح JSON للويب

بنية JWKS

RFC7517 تصف عناصر مفتاح JWKS لكل نوع مفتاح، مثل "RSA" أو "EC". على سبيل المثال، استنادًا إلى نوع المفتاح، يمكن أن تتضمّن هذه المَعلمات ما يلي:

  • kty : نوع المفتاح، مثل "RSA" أو "EC"
  • kid (رقم تعريف المفتاح): يمكن أن تكون أي قيمة عشوائية (بدون تكرار ضِمن مجموعة المفاتيح ). إذا كان رمز JWT الوارد يتضمّن رقم تعريف مفتاح موجودًا في مجموعة JWKS، ستستخدم السياسة المفتاح العلني الصحيح للتحقّق من توقيع JWS/JWT.

في ما يلي أمثلة على العناصر الاختيارية وقيمها:

  • alg : خوارزمية المفتاح يجب أن تتطابق مع خوارزمية التوقيع في JWS/JWT.
  • use : إذا كان هذا العنصر متوفرًا، يجب أن تكون قيمته sig.

يتضمّن JWKS التالي العناصر والقيم المطلوبة وسيكون صالحًا على Edge (من https://www.googleapis.com/oauth2/v3/certs):

{
   "keys":[
      {
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

تصميم الوكيل لاستخدام JWKS

عند الحصول على رمز JWS/JWT من جهة إصدار، غالبًا ما تُدرِج جهة الإصدار رقم تعريف مفتاح (أو kid) في عنوان JWS/JWT يخبر المفتاح مستلِم رمز JWS/JWT كيفية العثور على المفتاح العلني أو السري اللازم للتحقّق من التوقيع على رمز JWS/JWT الموقَّع.

على سبيل المثال، لنفترض أنّ جهة إصدار توقّع رمز JWT باستخدام مفتاح خاص. يحدّد "رقم تعريف المفتاح" المفتاح العلني المطابق الذي سيتم استخدامه للتحقّق من رمز JWT. تكون قائمة المفاتيح العلنية متاحة عادةً على نقطة نهاية معروفة، مثلاً: https://www.googleapis.com/oauth2/v3/certs.

في ما يلي التسلسل الأساسي الذي يجب أن ينفّذه Edge (أو أي منصة تعمل مع JWKS) للعمل مع رمز JWS/JWT يتضمّن JWKS:

  1. فحص عنوان JWS/JWT للعثور على رقم تعريف المفتاح (kid)
  2. فحص عنوان JWS/JWT للعثور على خوارزمية التوقيع (alg)، مثل RS256
  3. استرداد قائمة المفاتيح وأرقام التعريف من JWKS لنقطة النهاية المعروفة لجهة إصدار معيّنة
  4. استخراج المفتاح العلني من قائمة المفاتيح التي تتضمّن رقم تعريف المفتاح المذكور في عنوان JWS/JWT والخوارزمية المطابقة، إذا كان مفتاح JWKS يحدّد الخوارزمية
  5. استخدام هذا المفتاح العلني للتحقّق من التوقيع على JWS/JWT

بصفتك مطوّر وكيل Edge API، عليك تنفيذ ما يلي لإجراء عملية التحقّق من JWS/JWT:

  1. استرداد قائمة المفاتيح وأرقام التعريف من نقطة النهاية المعروفة لجهة إصدار معيّنة يمكنك استخدام سياسة استدعاء الخدمة لهذه الخطوة.
  2. في سياسة التحقّق من JWS/JWT، حدِّد موقع JWS/JWT في العنصر <Source> وحمولة JWKS في العنصر <PublicKey/JWKS>. على سبيل المثال، بالنسبة إلى سياسة VerifyJWT: 
    <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS ref="public.jwks"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

تنفّذ سياسة التحقّق من JWT كل الإجراءات الأخرى:

  • إذا لم يتم العثور في JWKS على مفتاح يتضمّن رقم تعريف مفتاح يطابق رقم تعريف المفتاح (kid) الذي تم تأكيده في JWT، ستعرض سياسة التحقّق من JWT خطأ ولن تتحقّق من صحة JWT.
  • إذا كان رمز JWT الوارد لا يتضمّن رقم تعريف مفتاح (kid) في العنوان، لن يكون من الممكن إجراء عملية الربط بين رقم تعريف المفتاح ومفتاح التحقّق.

بصفتك مصمّم الوكيل، أنت مسؤول عن تحديد المفتاح الذي سيتم استخدامه، وقد يكون هذا المفتاح ثابتًا ومبرمَجًا في بعض الحالات.