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

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
المعلومات

يقدّم هذا الموضوع معلومات عامة حول سياسات JWT (JSON Web Token) وJWS (توقيع الويب JSON) وسياسات Apigee JWS/JWT التي قد تهمّ مطوّري البرامج الوكيلة لـ Apigee.

مقدمة

يتم استخدام JWS وJWT بشكل شائع لمشاركة المطالبات أو التأكيدات بين التطبيقات المرتبطة. تفعِّل سياسات JWS/JWT خوادم Edge API 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 عندما يكون من الضروري معارف قيمة المطالبة (JW/JWT) أو العنوان (JWS/JWT) من داخل JWS/JWT قبل التحقّق من JW/JWT.

أجزاء JWS/JWT

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

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

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

header..signature

باستخدام JWS المنفصلة، يتم إرسال حمولة البيانات بشكل منفصل عن JWS. ويمكنك استخدام العنصر <DetachedContent> ضِمن سياسة "التحقّق من JWS" لتحديد حمولة بيانات JWS الأولية غير المشفّرة. بعد ذلك، تتحقّق سياسة "التحقّق من JWS" من JWS باستخدام العنوان والتوقيع في JWS وحمولة البيانات التي يحدّدها العنصر <DetachedContent>.

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

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

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

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

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

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

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

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

تتوافق سياسات التحقّق من 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، وتستخدم الطرف الذي يُثبت هويته المفتاح العام المطابق لإثبات صحة التوقيع في 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 (JWKs). 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 من جهة إصدار، تُدرِج جهة الإصدار رقم تعريف مفتاح (أو ملف شخصي) في عنوان 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، يجب عليك تنفيذ ما يلي لإجراء التحقق من JWS/JWT:

  1. استرجع قائمة المفاتيح والمعرِّفات من نقطة النهاية المعروفة لجهة إصدار معيّنة. ويمكنك في هذه الخطوة استخدام سياسة وسائل شرح الخدمة.
  2. في سياسة التحقّق من JWS/JWT، حدِّد موقع JWS/JWT في العنصر <Source> وحمولة JWKS في العنصر <PublicKey/JWKS>. على سبيل المثال، بالنسبة إلى سياسة التحقّق من صحة المعلومات الضريبية:
    <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" أي إجراء آخر:

  • إذا لم يتم العثور على مفتاح يتضمن رقم تعريف مفتاح يتطابق مع رقم تعريف المفتاح (الطفل) الذي تم تأكيده في JWT، تعرض سياسة التحقّق من JWT خطأً ولا تتحقّق من صحة JWT.
  • إذا كان ملف JWT الوارد لا يحمل رقم تعريف مفتاح (kid) في العنوان، لن يكون من الممكن ربط هذا المفتاح الخاص بـ keyid-to-verification.

وبصفتك مصمم الخادم الوكيل، تقع على عاتقك مسؤولية تحديد المفتاح الذي تريد استخدامه، وقد يكون هذا المفتاح في بعض الحالات مفتاحًا ثابتًا وترميزًا ثابتًا.