سياسة CREATEJWS

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

المزايا

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

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

فيديو

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

نماذج

إنشاء 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 على الخوارزمية التي تم اختيارها، كما هو موضح في الجدول التالي:

خوارزمية العناصر الرئيسية
HS{256/384/512}* 
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}* 
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

العنصران <Password> و<Id> اختياريان.
*لمزيد من المعلومات حول المتطلبات الرئيسية، يُرجى الاطّلاع على لمحة عن خوارزميات تشفير التوقيع

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

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

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

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

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

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

السمة الوصف تلقائي الحضور
الاسم الاسم الداخلي للسياسة. تقتصر الأحرف التي يمكنك استخدامها في الاسم على: A-Z0-9._\-$ % ومع ذلك، تفرض واجهة مستخدم إدارة Edge المزيد مثل الإزالة التلقائية للأحرف غير الأبجدية الرقمية.

يمكنك استخدام العنصر <displayname></displayname> بشكل اختياري من أجل تسمية السياسة في محرِّر الخادم الوكيل لواجهة مستخدم الإدارة بلغة طبيعية مختلفة الاسم.

 لا ينطبق مطلوب
continueOnError اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ سياسة. هذا متوقّع السلوك في معظم السياسات.

يمكنك ضبط القيمة على true لمواصلة تنفيذ المسار حتى بعد تطبيق إحدى السياسات. فشل.

 خطأ اختياري
مفعّلة اضبط القيمة على true لفرض السياسة.

ضبط على false على "إيقاف" السياسة. لن يتم فرض السياسة حتى لو بقيت مرتبطة بتدفق.

 صحيح اختياري
غير متزامن تم إيقاف هذه السمة نهائيًا. خطأ منهي العمل به

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

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

تلقائي إذا لم تستخدم هذا العنصر، سيتم استخدام قيمة سمة اسم السياسة.
الحضور اختياري
النوع سلسلة

&lt;Algorithm&gt;

<Algorithm>algorithm-here</Algorithm>

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

تلقائي لا ينطبق
الحضور مطلوب
النوع سلسلة
القيم الصالحة HS256 وHS384 وHS512 وRS256 وRS384 وRS512 وES256 وES384 وES512 وPS256 وPS384 وPS512

&lt;AdditionalHeaders/Claim&gt;

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

&lt;CriticalHeaders&gt;

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

تلقائي لا ينطبق
الحضور اختياري
النوع مصفوفة السلاسل المفصولة بفواصل
القيم الصالحة إمّا مصفوفة أو اسم متغير يحتوي على المصفوفة.

&lt;DetachContent&gt;

<DetachContent>true|false</DetachContent>

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

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

header.payload.signature

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

header..signature

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

تلقائي خطأ
الحضور اختياري
النوع منطقي
القيم الصالحة صواب أم خطأ

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

تلقائي خطأ
الحضور اختياري
النوع منطقي
القيم الصالحة صواب أم خطأ

&lt;OutputVariable&gt;

<OutputVariable>JWS-variable</OutputVariable>

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

تلقائي jws.POLICYNAME.generated_jws
الحضور اختياري
النوع سلسلة (اسم متغيّر التدفق)

&lt;Payload&gt;

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

or

<Payload>payload-value</Payload>

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

تلقائي لا ينطبق
الحضور مطلوب
النوع سلسلة أو مصفوفة بايت أو مصدر بيانات أو أي تمثيل آخر لحمولة JWS غير المشفَّرة

&lt;PrivateKey/Id&gt;

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

تلقائي لا ينطبق
الحضور اختياري
النوع سلسلة
القيم الصالحة متغير تدفق أو سلسلة

&lt;PrivateKey/Password&gt;

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

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

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

ملاحظة: يجب تحديد متغيّر تدفق. سيتم رفض Edge على أنّه غير صالح تهيئة السياسة التي يتم فيها تحديد كلمة المرور في نص عادي. متغيّر التدفق يجب أن يحتوي على البادئة "private". على سبيل المثال: private.mypassword

&lt;PrivateKey/Value&gt;

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

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

تلقائي لا ينطبق
الحضور مطلوب لإنشاء JWS باستخدام خوارزمية RS256.
النوع سلسلة
القيم الصالحة متغيّر تدفق يحتوي على سلسلة تمثّل قيمة مفتاح خاص بترميز RSA بترميز PEM.

ملاحظة: يجب أن يتضمّن متغيّر التدفق البادئة "private". على سبيل المثال: private.mykey

&lt;SecretKey/Id&gt;

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

or

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

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

تلقائي لا ينطبق
الحضور اختياري
النوع سلسلة
القيم الصالحة متغير تدفق أو سلسلة

&lt;SecretKey/Value&gt;

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

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

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

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

ملاحظة: في حال كان متغيّر التدفق، يجب أن يتضمّن البادئة "خاص". بالنسبة مثال: private.mysecret

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

لا تضبط سياسة إنشاء 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.

Fault code HTTP status Occurs when
steps.jws.GenerationFailed 401 The policy was unable to generate the JWS.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.SigningFailed 401 In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Error name Occurs when
InvalidAlgorithm The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Other possible deployment errors.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "TokenExpired"
JWS.failed All JWS policies set the same variable in the case of a failure. jws.JWS-Policy.failed = true

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>