سياسة CheckJWS

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

الأدوات المستخدمة

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

إذا تم التحقّق من صحة JWS، سيُسمح بمتابعة الطلب. إذا تعذّر التحقّق من توقيع JWS أو إذا كان JWS غير صالح بسبب نوع من الأخطاء، تتوقف جميع عمليات المعالجة ويتم عرض رسالة خطأ في الردّ.

لمعرفة المزيد عن أجزاء JWS وكيفية تشفيرها وتوقيعها، يُرجى الرجوع إلى RFC7515.

فيديو

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

العيّنات

• التحقّق من صحة JWS مرفق موقَّع باستخدام خوارزمية HS256
• التحقّق من صحة توقيع JWS منفصل باستخدام خوارزمية RS256

التحقّق من توقيع JWS المرفق باستخدام خوارزمية HS256

تتحقّق سياسة المثال هذه من توقيع JWS مرفق باستخدام خوارزمية التشفير HS256، أي HMAC، باستخدام مجموع اختباري SHA-256. يتم تمرير JWS في طلب الخادم الوكيل باستخدام مَعلمة نموذجية باسم JWS. يتم تضمين المفتاح في متغيّر باسم private.secretkey.

يحتوي JWS المرفق على العنوان والحمولة والتوقيع بترميز:

header.payload.signature

تتضمّن إعدادات السياسة المعلومات التي يحتاجها Edge لفك تشفير JWS وتقييمه، مثل مكان العثور على JWS (في متغيّر تدفق محدّد في العنصر <Source>)، وخوارزمية التوقيع المطلوبة، ومكان العثور على المفتاح السري (المخزَّن في متغيّر تدفق Edge، والذي يمكن أن يكون قد تم استرداده من KVM في Edge، على سبيل المثال).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

تكتب السياسة ناتجها إلى متغيرات السياق حتى تتمكّن السياسات أو الشروط اللاحقة في خادم وكيل واجهة برمجة التطبيقات من فحص هذه القيم. يمكنك الاطّلاع على متغيرات التدفق للحصول على قائمة بالمتغيرات التي تحدّدها هذه السياسة.

التحقّق من توقيع JWS منفصل باستخدام خوارزمية RS256

تتحقّق سياسة المثال هذه من صحة توقيع JWS منفصل تم توقيعه باستخدام خوارزمية RS256. لإثبات الملكية، عليك تقديم المفتاح العام. يتم تمرير JWS في طلب الخادم الوكيل باستخدام مَعلمة نموذجية اسمها JWS. يتم تضمين المفتاح العام في متغيّر باسم public.publickey.

تحذف JWS المنفصلة الحمولة من JWS:

header..signature

يعود إليك تحديد الحمولة إلى سياسة VerifyJWS من خلال تحديد اسم المتغيّر الذي يحتوي على الحمولة إلى العنصر <DetachedContent>. يجب أن يكون المحتوى المحدّد في <DetachedContent> بالشكل الأصلي غير المشفّر الذي كان عليه عند إنشاء توقيع JWS.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

تكتب السياسة ناتجها إلى متغيرات السياق حتى تتمكّن السياسات أو الشروط اللاحقة في خادم وكيل واجهة برمجة التطبيقات من فحص هذه القيم. يمكنك الاطّلاع على متغيرات التدفق للحصول على قائمة بالمتغيرات التي تحدّدها هذه السياسة.

ضبط العناصر الرئيسية

تعتمد العناصر التي تستخدمها لتحديد المفتاح المستخدَم للتحقّق من توقيع JWS على الخوارزمية التي تختارها، كما هو موضّح في الجدول التالي:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

مرجع العنصر

يصف مرجع السياسة عناصر وسمات سياسة Verify JWS.

ملاحظة: سيختلف الإعداد إلى حد ما حسب خوارزمية التشفير التي تستخدمها. راجِع الأمثلة للاطّلاع على أمثلة توضّح عمليات الضبط لحالات استخدام معيّنة.

السمات التي تنطبق على العنصر ذي المستوى الأعلى

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

السمات التالية مشتركة بين جميع العناصر الرئيسية للسياسة.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

استخدِم هذه السمة بالإضافة إلى سمة الاسم لتصنيف السياسة في أداة تعديل وكيل واجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<Algorithm>

<Algorithm>HS256</Algorithm>

تحدّد هذه السمة خوارزمية التشفير لتوقيع الرمز المميّز. تستخدم خوارزميات RS*/PS*/ES* مفتاحَي تشفير عام/خاص، بينما تستخدم خوارزميات HS* مفتاحًا سريًا مشتركًا. يُرجى الاطّلاع أيضًا على لمحة عن خوارزميات تشفير التوقيع.

يمكنك تحديد قيم متعددة مفصولة بفواصل. على سبيل المثال، "HS256, HS512" أو "RS256, PS256". ومع ذلك، لا يمكنك دمج خوارزميات HS* مع أي خوارزميات أخرى أو خوارزميات ES* مع أي خوارزميات أخرى لأنّها تتطلّب نوع مفتاح معيّنًا. يمكنك الجمع بين خوارزميات RS* وPS*.

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

تتحقّق هذه السمة من أنّ عنوان JWS يحتوي على أزواج اسم/قيمة المطالبة الإضافية المحدّدة وأنّ قيم المطالبة المؤكَّدة تتطابق.

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

يأخذ العنصر <Claim> السمات التالية:

• name: (مطلوبة) تمثّل اسم المطالبة.
• ref: (اختياري) اسم متغيّر سير العمل. في حال توفّرها، ستستخدم السياسة قيمة هذا المتغيّر كعنصر. في حال تحديد كلّ من السمة ref وقيمة مطالبة صريحة، تكون القيمة الصريحة هي القيمة التلقائية، ويتم استخدامها إذا لم يتم حلّ متغيّر التدفق المشار إليه.
• type - (اختياري) إحدى القيم التالية: string (القيمة التلقائية) أو number أو boolean أو map
• array: (اختياري) اضبط القيمة على true للإشارة إلى ما إذا كانت القيمة مصفوفة من الأنواع. القيمة التلقائية: false.

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

يكون تنسيق JWS الذي تم إنشاؤه مع حمولة المحتوى كما يلي:

header.payload.signature

إذا كنت تستخدم سياسة GenerateJWS لإنشاء حمولة منفصلة، سيتم حذف الحمولة من JWS الذي تم إنشاؤه وسيكون بالتنسيق التالي:

header..signature

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

تظهر السياسة خطأ في الحالات التالية:

• يتم تحديد <DetachedContent> عندما لا يحتوي JWS على حمولة محتوى منفصلة (رمز الخطأ هو steps.jws.ContentIsNotDetached).
• يتم حذف <DetachedContent> ويحتوي JWS على حمولة محتوى منفصلة (رمز الخطأ هو steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

اضبط القيمة على "خطأ" إذا أردت أن تطرح السياسة خطأً عند عدم إدراج أي رأس مُدرَج في الرأس crit الخاص بتوقيع JWS ضمن العنصر <KnownHeaders>. اضبط القيمة على "صحيح" لكي تتجاهل سياسة VerifyJWS العنوان crit.

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

اضبط القيمة على "خطأ" إذا كنت تريد أن تعرض السياسة خطأً عند تعذُّر تحديد أي متغير مرجعي محدّد في السياسة. اضبط القيمة على "صحيح" للتعامل مع أي متغيّر لا يمكن حله كسلسلة فارغة (قيمة فارغة).

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

تستخدِم سياسة GenerateJWS العنصر <CriticalHeaders> لتعبئة العنوان crit في الرمز المميز. على سبيل المثال:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

تفحص سياسة VerifyJWS العنوان crit في JWS، إذا كان متوفرًا، وتتحقق من أنّ العنصر <KnownHeaders> يدرج هذا العنوان أيضًا لكل عنصر مدرَج. يمكن أن يحتوي العنصر <KnownHeaders> على مجموعة فرعية من العناصر المدرَجة في crit. يجب فقط أن يتم إدراج جميع العناوين المُدرَجة في crit ضمن العنصر <KnownHeaders>. أي عنوان تعثر عليه السياسة في crit ولم يتم إدراجه أيضًا في <KnownHeaders> يؤدي إلى تعذُّر تنفيذ سياسة VerifyJWS.

يمكنك اختياريًا ضبط سياسة VerifyJWS لتجاهل العنوان crit من خلال ضبط العنصر <IgnoreCriticalHeaders> على true.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

تحدّد هذه السمة قيمة بتنسيق JWKS (RFC 7517) تحتوي على مجموعة من المفاتيح العامة. يجب استخدامها فقط عندما تكون الخوارزمية إحدى الخوارزميات التالية: RS256 أو RS384 أو RS512 أو PS256 أو PS384 أو PS512 أو ES256 أو ES384 أو ES512.

إذا كان JWS الوارد يحمل معرّف مفتاح متوفّر في مجموعة JWKS، ستستخدم السياسة المفتاح العام الصحيح للتحقّق من توقيع JWS. للحصول على تفاصيل حول هذه الميزة، اطّلِع على استخدام مجموعة مفاتيح الويب JSON (JWKS) للتحقّق من توقيع JWS.

إذا كنت تسترد القيمة من عنوان URL متاح للجميع، يخزّن Edge مفتاح JWKS مؤقتًا لمدة 300 ثانية. عند انتهاء صلاحية ذاكرة التخزين المؤقت، يستردّ Edge مجموعة JWKS مرة أخرى.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

تحدّد هذه السمة المفتاح العام المستخدَم للتحقّق من صحة التوقيع على JWS. استخدِم السمة ref لتمرير المفتاح في متغيّر تدفّق أو لتحديد المفتاح المرمّز بتنسيق PEM مباشرةً. يجب استخدامها فقط عندما تكون الخوارزمية إحدى الخوارزميات التالية: RS256 أو RS384 أو RS512 أو PS256 أو PS384 أو PS512 أو ES256 أو ES384 أو ES512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

توفّر هذه السمة المفتاح السري المستخدَم للتحقّق من الرموز المميزة أو توقيعها باستخدام خوارزمية HMAC. استخدِم هذه السمة فقط عندما تكون الخوارزمية إحدى الخوارزميات التالية: HS256 أو HS384 أو HS512. استخدِم السمة ref لتمرير المفتاح في متغيّر التدفق.

<Source>

<Source>JWS-variable</Source>

في حال توفّره، يحدّد متغيّر التدفق الذي تتوقّع السياسة العثور فيه على JWS للتحقّق منه.

متغيّرات التدفق

بعد النجاح، تم ضبط السياستَين التحقّق من JWS وفك ترميز JWS. متغيرات السياق وفقًا لهذا النمط:

jws.{policy_name}.{variable_name}

على سبيل المثال، إذا كان اسم السياسة هو verify-jws، يتم تخزين السياسة. الخوارزمية المحدّدة في JWS لمتغير السياق هذا: jws.verify-jws.header.algorithm

مرجع الخطأ

يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد للأخطاء للتعامل معها. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

متغيّرات الأخطاء

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

مثال على استجابة الخطأ

لمعالجة الخطأ، أفضل ممارسة هي رصد الجزء errorcode من الخطأ الاستجابة. لا تعتمد على النص في faultstring، لأنه قد يتغير.

مثال على قاعدة الخطأ

<FaultRules>
    <FaultRule name="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>