سياسة CheckJWS

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

المزايا

التحقق من صحة التوقيع على خدمات 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، والذي يمكن أن من Edge KVM، على سبيل المثال).

<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>

مرجع العنصر

يصف مرجع السياسة عناصر سياسة "التحقّق من 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 - (اختيارية) أحد الخيارات التالية: سلسلة (تلقائي) أو رقم أو قيمة منطقية أو خريطة
• صفيف - (اختيارية) يتم ضبطها على صحيح للإشارة إلى ما إذا كانت القيمة مصفوفة من الأنواع. الإعداد التلقائي: خطأ.

<DetachedContent>

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

تظهر تجربة JWS التي تم إنشاؤها مع حمولة المحتوى على النحو التالي:

header.payload.signature

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

header..signature

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

تعرض السياسة خطأً في الحالات التالية:

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<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>