سياسة CREATEJWS

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

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

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

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

فيديو

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

نماذج

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

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

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

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

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

header.payload.signature

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

header..signature

في حال استخدام حمولة منفصلة، يعود إليك أمر تمرير الحمولة الأصلية غير المشفرة إلى سياسة VerifyJWS باستخدام العنصر <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 بايت. يؤدي استخدام مفتاح أقل قوة إلى حدوث خطأ في وقت التشغيل.

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

لا تضبط سياسة Generate JWS متغيّرات التدفق.

مرجع الخطأ

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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