يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات
Apigee X. المعلومات
الموضوع
تنشئ 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 التي تم إنشاؤها الحمولة.
تقع على عاتقك مسؤولية نقل الحمولة إلى سياسة التحقُّق من 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> العنصران |
|
*لمزيد من المعلومات حول متطلبات المفتاح، يُرجى الاطّلاع على لمحة عن خوارزميات تشفير التوقيعات. |
مرجع عنصر لإنشاء JWS
يصف مرجع السياسة عناصر وسمات سياسة إنشاء JWS.
ملاحظة: ستختلف الإعدادات إلى حد ما بناءً على خوارزمية التشفير التي تستخدمها. يُرجى الرجوع إلى النماذج للاطّلاع على أمثلة توضّح الإعدادات لحالات استخدام معيّنة.
السمات التي تنطبق على عنصر المستوى الأعلى
<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">
السمات التالية شائعة في جميع العناصر الرئيسية للسياسة.
السمة | الوصف | تلقائي | الحضور |
---|---|---|---|
اسم |
الاسم الداخلي للسياسة تقتصر الأحرف التي يمكنك استخدامها في الاسم على:
A-Z0-9._\-$ % . ومع ذلك، تفرض واجهة مستخدم إدارة Edge قيودًا إضافية، مثل الإزالة التلقائية للأحرف غير الأبجدية الرقمية.
ويمكنك اختياريًا استخدام العنصر |
لا ينطبق | مطلوبة |
continueOnError |
اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ السياسة. وهو سلوك متوقّع لمعظم السياسات.
اضبط القيمة على |
false | اختياري |
مفعّلة |
اضبط القيمة على true لفرض السياسة.
اضبط القيمة على |
صحيح | اختياري |
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". مثلاً: |
<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.
ملاحظة: يجب أن يحتوي متغيّر التدفق على البادئة "خاص". مثلاً:
|
<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. |
النوع | سلسلة |
القيم الصالحة |
متغير تدفق يشير إلى سلسلة
ملاحظة: إذا كان متغيّر التدفق، يجب أن يتضمن البادئة "خاص". على سبيل
المثال، |
متغيرات التدفق
لا تضبط سياسة إنشاء 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. |
|
أخطاء النشر المحتملة الأخرى |
متغيرات الخطأ
ويتم ضبط هذه المتغيرات عند حدوث خطأ في وقت التشغيل. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات.
المتغيرات | المكان | مثال |
---|---|---|
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>