سياسة فك ترميز الترميز البرمجي

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

الموضوع

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

تعمل سياسة فك ترميز JWT بغض النظر عن الخوارزمية التي تم استخدامها لتوقيع JWT. يمكنك الاطّلاع على نظرة عامة على سياسات JWS وJWT للاطّلاع على مقدّمة مفصّلة.

حملة فيديو

شاهِد فيديو قصيرًا لمعرفة كيفية فك ترميز JWT.

النموذج: فك ترميز JWT

تفكّ السياسة المعروضة أدناه ترميز JWT في متغير التدفق var.jwt. ويجب أن يكون هذا المتغيّر متاحًا وأن يحتوي على رمز JWT صالح (قابل للفكه). يمكن للسياسة الحصول على JWT من أي متغيّر تدفق.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

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

مرجع عنصر لفك ترميز JWT

يصف مرجع السياسة عناصر وسمات سياسة فك ترميز JWT.

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

<DecodeJWT name="JWT" 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>

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

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

<المصدر>

<Source>jwt-variable</Source>

في حال توفّره، تحدّد السياسة متغيّر التدفق الذي تتوقّع السياسة أن تجد فيه JWT لفك ترميزه.

تلقائي request.header.authorization (اطّلِع على الملاحظة الواردة أعلاه للحصول على معلومات مهمة عن الإعداد التلقائي).
الحضور إجراء اختياري
النوع سلسلة
القيم الصالحة اسم متغيّر تدفق الحافة

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

بعد نجاح العملية، تضبط سياستا التحقّق من JWT وفك ترميز JWT متغيّرات السياق وفقًا للنمط التالي:

jwt.{policy_name}.{variable_name}

على سبيل المثال، إذا كان اسم السياسة jwt-parse-token، ستخزّن السياسة الموضوع المحدّد في JWT في متغيّر السياق المسمى jwt.jwt-parse-token.decoded.claim.sub. (للتوافق مع الأنظمة القديمة، سيكون متاحًا أيضًا في jwt.jwt-parse-token.claim.subject)

اسم المتغير الوصف
claim.audience مطالبة جمهور JWT قد تكون هذه القيمة سلسلة أو مصفوفة من السلاسل.
claim.expiry تاريخ/وقت انتهاء الصلاحية، معبرًا عنه بالمللي ثانية منذ البداية.
claim.issuedat تاريخ إصدار الرمز المميّز بالمللي ثانية منذ البداية.
claim.issuer مطالبة جهة إصدار JWT
claim.notbefore إذا تضمّن JWT مطالبة nbf، سيحتوي هذا المتغيّر على القيمة معبرًا عنها بالملي ثانية منذ الحقبة.
claim.subject مطالبة موضوع JWT
claim.name قيمة المطالبة المحدّدة (عادية أو إضافية) في الحمولة سيتم ضبط إحدى هذه الطرق لكل مطالبة في الحمولة.
decoded.claim.name القيمة القابلة للتحليل بتنسيق JSON للمطالبة المعنية (عادية أو إضافية) في الحمولة. يتم ضبط متغيّر واحد لكل مطالبة في الحمولة. على سبيل المثال، يمكنك استخدام decoded.claim.iat لاسترداد وقت إصدار JWT معبرًا عنه بالثواني منذ البداية. يمكنك أيضًا استخدام متغيّرات مسار claim.name، إلا أنّ هذا هو المتغيّر الذي يُنصح باستخدامه للوصول إلى المطالبة.
decoded.header.name القيمة القابلة للتحليل بتنسيق JSON لعنوان في الحمولة. يتم ضبط متغيّر واحد لكل عنوان في الحمولة. يمكنك أيضًا استخدام متغيّرات مسار header.name، إلا أنّ هذا هو المتغيّر المقترَح استخدامه للوصول إلى العنوان.
expiry_formatted تاريخ/وقت انتهاء الصلاحية، منسَّق كسلسلة يمكن لشخص عادي قراءتها مثال: 2017-09-28T21:30:45.000+0000
header.algorithm خوارزمية التوقيع المستخدمة في JWT. على سبيل المثال، RS256 وHS384 وما إلى ذلك. راجِع مَعلمة العنوان(Algorithm) لمعرفة المزيد.
header.kid رقم تعريف المفتاح، إذا تمت إضافته عند إنشاء JWT. يمكنك الاطّلاع أيضًا على مقالة "استخدام مجموعة مفاتيح ويب JSON (JWKS)" في نظرة عامة على سياسات JWT للتأكّد من صحة JWT. اطّلِع على مَعلمة العنوان(معرّف المفتاح) لمزيد من المعلومات.
header.type سيتم ضبطها على JWT.
header.name قيمة العنوان المُسمّى (عادية أو إضافية). سيتم ضبط أحد هذه الإعدادات لكل عنوان إضافي في جزء العنوان من JWT.
header-json العنوان بتنسيق JSON.
is_expired صواب أم خطأ
payload-claim-names مجموعة من المطالبات التي يدعمها فريق JWT
payload-json
الحمولة بتنسيق JSON.
seconds_remaining عدد الثواني قبل انتهاء صلاحية الرمز المميّز. وإذا انتهت صلاحية الرمز المميّز، سيكون هذا الرقم سالبًا.
time_remaining_formatted الوقت المتبقي قبل انتهاء صلاحية الرمز المميّز، ويكون منسَّقًا كسلسلة يمكن لشخص عادي قراءتها مثال: 00:59:59.926
valid في حالة التحقّق من صحة التوقيع، سيكون هذا المتغيّر صحيحًا عند التحقُّق من التوقيع، ويكون الوقت الحالي قبل انتهاء صلاحية الرمز المميّز، وبعد قيمة "not before" في حال توفُّرها. وإلا false.

في حالة DecodeJWT، لا يتم تعيين هذا المتغير.

مرجع الخطأ

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

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

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

رمز الخطأ رموز حالة HTTP السبب إصلاح
steps.jwt.FailedToDecode 401 يحدث ذلك عندما يتعذّر على السياسة فك ترميز JWT. قد يكون JWT مكتوبًا بصيغة غير صحيحة أو غير صالح أو غير قابل للفصل.
steps.jwt.FailedToResolveVariable 401 يحدث ذلك عندما لا يكون متغيّر التدفق المحدّد في العنصر <Source> ضِمن السياسة متوفّرًا.
steps.jwt.InvalidToken 401 يحدث ذلك عندما يكون متغيّر التدفق المحدّد في العنصر <Source> ضمن السياسة خارج النطاق أو يتعذّر حلّه.

أخطاء النشر

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

اسم الخطأ السبب إصلاح
InvalidEmptyElement يحدث ذلك عندما لا يتم تحديد متغيّر التدفق الذي يحتوي على JWT المطلوب فك ترميزه في العنصر <Source> للسياسة.

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

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

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

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

رموز الخطأ في سياسة JWT

بالنسبة إلى معالجة الأخطاء، أفضل ممارسة هي إدراج الجزء errorcode من استجابة الخطأ. لا تعتمد على النص في faultstring لأنه قد يتغير.

مثال لقاعدة خطأ

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>