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

أنت الآن بصدد الاطّلاع على مستندات 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

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name Description
claim.audience The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer The JWT issuer claim.
claim.notbefore If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject The JWT subject claim.
claim.name The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type Will be set to JWT.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json The header in JSON format.
is_expired true or false
payload-claim-names An array of claims supported by the JWT.
payload-json
The payload in JSON format.
seconds_remaining The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWT, this variable is not set.

مرجع الخطأ

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

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

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

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

أخطاء النشر

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

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

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"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

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