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

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

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

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

تعمل سياسة JWT Decode بغض النظر عن الخوارزمية التي تم استخدامها لتوقيع 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 لمواصلة تنفيذ التدفق حتى بعد تعذُّر تنفيذ إحدى السياسات.

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

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

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

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

عند النجاح، تم ضبط السياستَين التحقّق من 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، وهكذا. يُرجى الاطّلاع على مَعلمة العنوان(الخوارزمية) لمزيد من المعلومات.
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 في حالة التحقق منJWT، سيكون هذا المتغير صحيحًا عند التحقق من التوقيع، الوقت الحالي قبل انتهاء صلاحية الرمز المميز، وبعد قيمة notBefore، إذا كانت موجودة. وبخلاف ذلك، يتم عرض "خطأ".

في حالة 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>