سياسة CREATEJWS

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

المزايا

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

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

فيديو

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

نماذج

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

إنشاء JWS مرفق موقَّعًا باستخدام HS256 الخوارزمية

تنشئ هذه السياسة نموذج JavaScript مرفقًا ويوقّعها باستخدام خوارزمية HS256. يعتمد HS256 على سر مشترك لكلٍ من التوقيع والتحقق من التوقيع.

يحتوي JWS على العنوان والحمولة والتوقيع المشفّرَين:

header.payload.signature

اضبط <DetachContent> على "صحيح" لإنشاء محتوى منفصل. اطّلِع على أجزاء من JWS/JWT للتعرّف على مزيد من المعلومات حول بنية JWS وتنسيقه.

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

تنشئ إعدادات السياسة أدناه JWS من حمولة بيانات مضمنة في المتغيّر. private.payload

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

تنشئ هذه السياسة نموذج JWS منفصلاً وتوقّعها باستخدام خوارزمية RS256. جارٍ إنشاء يعتمد توقيع RS256 على مفتاح خاص بترميز RSA، ويجب تقديمه بتنسيق PEM بترميز.

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

header..signature

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

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

تحديد العناصر الرئيسية

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

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

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

مرجع عنصر لإنشاء JWS

يصف مرجع السياسة عناصر سياسة إنشاء JWS وسماتها.

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

تُحدِّد خوارزمية التشفير لتوقيع الرمز المميّز.

<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

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

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

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

إضافة العنوان المهم، crit، إلى JWS الرأس crit عبارة عن مصفوفة من أسماء رؤوس الأعمدة التي يجب أن يعرفها ويتعرف عليها مستلم JWS. على سبيل المثال:

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

تحدِّد هذه السياسة ما إذا كان سيتم إنشاء JWS باستخدام حمولة منفصلة، <DetachContent>true</DetachContent>. أو لا، <DetachContent>false</DetachContent>.

في حال التحديد على "خطأ"، سيكون الإعداد التلقائي هو JWS الذي تم إنشاؤه على النحو التالي:

header.payload.signature

في حال تحديد "صحيح" لإنشاء حمولة منفصلة، يحذف JWS الذي تم إنشاؤه الحمولة، ويكون على النحو التالي:

header..signature

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

تحدِّد هذه السياسة مكان وضع خدمات JWS التي تم إنشاؤها من خلال هذه السياسة. يتم وضعه تلقائيًا في متغير التدفق jws.POLICYNAME.generated_jws.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

تحدِّد هذه السياسة حمولة JWS الأولية وغير المشفَّرة. حدِّد متغيّرًا يحتوي على الحمولة أو سلسلة.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

تُستخدَم لتحديد معرّف المفتاح (kid) المطلوب تضمينه في عنوان JWS. الاستخدام فقط إذا كانت الخوارزمية هي RS256/RS384/RS512 أو PS256/PS384/PS512 أو ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

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

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

تحدّد هذه السياسة معرّف المفتاح (kid) المطلوب تضمينه في عنوان JWS الخاص بخدمة JWS الموقَّعة باستخدام بروتوكول HMAC. للخوارزمية. للاستخدام فقط إذا كانت الخوارزمية هي واحدة من HS256/HS384/HS512.

<SecretKey/Value>

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

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

تفرض Edge حدًا أدنى لقوة المفتاح لخوارزميات HS256/HS384/HS512. الحد الأدنى لطول المفتاح يبلغ الحد الأقصى لحجم الملف في بروتوكول HS256 32 بايت، أمّا بالنسبة إلى HS384، فيبلغ 48 بايت، أمّا بالنسبة إلى HS512، فيبلغ 64 بايت. يؤدي استخدام مفتاح بقوة أقل إلى حدوث خطأ في بيئة التشغيل.

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

لا تضبط سياسة إنشاء JWS متغيّرات التدفق.

مرجع الخطأ

يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها 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>