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

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

يوفر هذا الموضوع معلومات عامة حول JWT (رمز JSON المميّز للويب) وJWS (توقيع الويب بتنسيق JSON) وسياسات Apigee JWS/JWT التي قد تهم مطوّري الخادم الوكيل في 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 والحمولة. الذي يحدده العنصر <DetachedContent>.

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

• JWT: مجموعة مهندسي شبكة الإنترنت (IETF RFC7519)
• JWS: IETF RFC7515

الاختلافات بين 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 Generation مع خوارزميات 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 لتوقيع JWS/JWT، كما أن الطرف الذي يثبت الملكية يستخدم المفتاح العام RSA المطابق للتحقق من التوقيع على JWS/JWT. ليست هناك أي متطلبات للحجم في المفاتيح.

خوارزمية RSASSA-PSS

خوارزمية RSASSA-PSS هي تحديث لخوارزمية RSA. مثلما هو الحال مع RSS، يستخدم RSASSA-PSS إعلانًا متجاوبًا على شبكة البحث. زوج مفاتيح عام/خاص للتوقيع المشفر. ويكون تنسيق المفتاح هو نفسه تنسيق 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:

   <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 في JWKS، فلن تعرض سياسة التحقق من JWT خطأ ولا تتحقَّق من JWT.
• إذا لم يتضمن JWT الوارد معرّف مفتاح (kid) في العنوان، فإن عملية تعيين لمفتاح التشفير-to-verification-key.

بصفتك مصمم الوكيل، فأنت مسئول عن تحديد المفتاح المراد استخدامه؛ وفي بعض الحالات، قد يكون مفتاحًا ثابتًا غير قابل للتغيير.