سياسة CREATEJWS

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

الموضوع

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

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

حملة فيديو

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

عيّنات

إنشاء حزمة 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 التي تم إنشاؤها الحمولة. تقع على عاتقك مسؤولية نقل الحمولة إلى سياسة التحقُّق من Google Workspace باستخدام العنصر <DetachedContent> في سياسة التحقُّق من Google Workspace.

<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 لمواصلة تنفيذ التدفق حتى بعد تعذُّر تنفيذ السياسة.

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

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

صحيح اختياري
async تم إيقاف هذه السمة نهائيًا. false منهي العمل به

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

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

<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 - (اختياري) واحد مما يلي: سلسلة (تلقائية) أو رقم أو قيمة منطقية أو خريطة
  • 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” ],
}

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

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

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

header.payload.signature

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

header..signature

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

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

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

<Payload>

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

or

<Payload>payload-value</Payload>

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

تلقائي لا ينطبق
الحضور مطلوبة
النوع سلسلة أو مصفوفة بايت أو مصدر بيانات أو أي تمثيل آخر لحمولة 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.

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

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

<PrivateKey/Value>

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

<SecretKey/Id>

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

or

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

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

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

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

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

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

مرجع الخطأ

يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد خطأ للتعامل مع الأخطاء. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن أخطاء السياسة وأخطاء المعالجة.

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

رمز الخطأ رموز حالة HTTP يحدث عند
steps.jws.GenerationFailed 401 تعذَّر على السياسة إنشاء JWS.
steps.jws.InsufficientKeyLength 401 بالنسبة إلى مفتاح أقل من 32 بايت لخوارزمية HS256
steps.jws.InvalidClaim 401 بسبب عدم تطابق مطالبة أو مطالبة، أو عدم تطابق العنوان أو العنوان.
steps.jws.InvalidCurve 401 المنحنى المحدد بالمفتاح غير صالح لخوارزمية المنحنى البيضاوي.
steps.jws.InvalidJsonFormat 401 تم العثور على تنسيق JSON غير صالح في عنوان JWS.
steps.jws.InvalidPayload 401 حمولة JWS غير صالحة.
steps.jws.InvalidSignature 401 تم حذف <DetachedContent> ولديها حمولة بيانات منفصلة في JWS.
steps.jws.KeyIdMissing 401 تستخدم سياسة "التحقّق" رمز JWKS كمصدر للمفاتيح العامة، إلا أنّ سياسة JWS الموقَّعة لا تتضمّن السمة kid في العنوان.
steps.jws.KeyParsingFailed 401 تعذّر تحليل المفتاح العام من المعلومات الأساسية المحددة.
steps.jws.MissingPayload 401 حمولة JWS مفقودة.
steps.jws.NoAlgorithmFoundInHeader 401 يحدث عندما تغفل JWS عنوان الخوارزمية.
steps.jws.SigningFailed 401 في CREATEJWS لمفتاح أقل من الحد الأدنى للحجم لخوارزميات HS384 أو HS512
steps.jws.UnknownException 401 حدث استثناء غير معروف.
steps.jws.WrongKeyType 401 تم تحديد نوع خاطئ للمفتاح. على سبيل المثال، إذا حدّدت مفتاح RSA لخوارزمية "منحنى بيضاوي" أو مفتاح منحنى لخوارزمية RSA.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

اسم الخطأ يحدث عند
InvalidAlgorithm القيم الصالحة الوحيدة هي: 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

أخطاء النشر المحتملة الأخرى

متغيرات الخطأ

ويتم ضبط هذه المتغيرات عند حدوث خطأ في وقت التشغيل. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات.

المتغيرات المكان مثال
fault.name="fault_name" fault_name هو اسم الخطأ، كما هو موضَّح في جدول أخطاء وقت التشغيل أعلاه. اسم الخطأ هو الجزء الأخير من رمز الخطأ. fault.name Matches "TokenExpired"
JWS.failed تحدِّد جميع سياسات JWS المتغيّر نفسه في حال تعذُّر التثبيت. jws.JWS-Policy.failed = true

مثال على الردّ على الخطأ

بالنسبة إلى معالجة الأخطاء، أفضل ممارسة هي إدراج الجزء 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>