سياسة 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

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

<DetachedContent>

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

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

header.payload.signature

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

header..signature

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

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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

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

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

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

يمكنك اختياريًا ضبط سياسة CheckJWS لتجاهل عنوان 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. ويمكنك استخدام سمة المرجع لتمرير المفتاح في متغيّر تدفق، أو تحديد المفتاح المشفّر بواسطة 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>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>