מדיניות DecodeJWT

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

מפענח JWT בלי לאמת את החתימה ב-JWT. האפשרות הזו שימושית במיוחד כשמשתמשים תואם למדיניות VerifyJWT, כאשר הערך של תביעה מתוך ה-JWT חייב להיות ידוע לפני אימות החתימה ב-JWT.

המדיניות של JWT פענוח קוד פועלת בלי קשר לאלגוריתם ששימש לחתימה על ה-JWT. מבוא מפורט זמין במאמר סקירה כללית של המדיניות של JWS ו-JWT.

וידאו

בסרטון קצר זה מוסבר איך לפענח את הקוד של JWT.

דוגמה: Decode a JWT

המדיניות שמוצגת בהמשך מפענחת JWT שנמצא במשתנה הזרימה var.jwt. הזה חייב להיות קיים ולהכיל ערך JWT בר-קיימא (ניתן לפענוח). המדיניות יכולה לקבל את ה-JWT מ: כל משתנה של זרימה.

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

הפלט של המדיניות נכתב במשתני ההקשר, כך שכללי המדיניות או התנאים הבאים נכתבים בשרת ה-proxy ל-API יכול לבדוק את הערכים האלה. בקטע משתני זרימה אפשר למצוא של המשתנים שהוגדרו במדיניות הזו.

מסמך עזר של רכיב לפענוח קוד של JWT

בחומר העזר בנושא המדיניות מתוארים הרכיבים והמאפיינים של מדיניות 'פענוח הקידוד של JWT'.

מאפיינים החלה על הרכיב ברמה העליונה

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

המאפיינים הבאים משותפים לכל רכיבי ההורה של המדיניות.

מאפיין תיאור ברירת מחדל נוכחות
שם השם הפנימי של המדיניות. תווים שבהם אפשר להשתמש בשם מוגבלים ל: A-Z0-9._\-$ % עם זאת, בממשק המשתמש לניהול Edge אוכפים פקודות נוספות הגבלות, כגון הסרה אוטומטית של תווים שאינם אלפאנומריים.

אפשר להשתמש ברכיב <displayname></displayname> כדי להוסיף תווית למדיניות בעורך ה-Proxy של ממשק המשתמש לניהול בשפה טבעית אחרת שם.

 לא רלוונטי חובה
continueOnError צריך להגדיר את הערך false כדי להחזיר שגיאה כשמדיניות נכשלת. המצב הזה צפוי של רוב כללי המדיניות.

יש להגדיר ל-true כדי שביצוע התהליך יימשך גם לאחר המדיניות נכשל.

 false אופציונלי
פעיל צריך להגדיר את הערך true כדי לאכוף את המדיניות.

הגדרת הערך false כ'כיבוי' המדיניות. המדיניות לא תיאכף גם אם הוא נשאר מחובר לזרימה.

 true אופציונלי
אסינכרוני המאפיין הזה הוצא משימוש. false הוצא משימוש

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

שימוש בנוסף למאפיין השם כדי להוסיף תווית למדיניות בעורך ה-Proxy של ממשק המשתמש לניהול בשם אחר בשפה טבעית.

ברירת מחדל אם משמיטים את הרכיב הזה, המערכת תשתמש בערך של מאפיין השם של המדיניות.
נוכחות אופציונלי
סוג מחרוזת

&lt;Source&gt;

<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 התאריך/שעת התפוגה, מבוטא באלפיות השנייה מאז epoch.
claim.issuedat התאריך שבו הונפק האסימון, מבוטא באלפיות שנייה מאז epoch.
claim.issuer הצהרת הבעלות על מנפיק ה-JWT.
claim.notbefore אם ה-JWT כולל הצהרת nbf, המשתנה הזה יכיל את הערך, באלפיות שנייה מאז epoch.
claim.subject הצהרת הנושא של JWT.
claim.name הערך של ההצהרה בעלת השם (רגילה או נוספת) במטען הייעודי (payload). אחד מאלה יוגדר עבור כל הצהרה במטען הייעודי (payload).
decoded.claim.name ערך שניתן לנתח בפורמט JSON של ההצהרה בעלת השם (רגילה או נוספת) במטען הייעודי (payload). משתנה אחד מוגדר עבור כל הצהרה במטען הייעודי (payload). לדוגמה, אפשר להשתמש ב-decoded.claim.iat כדי לאחזר את תאריך ההנפקה של ה-JWT, המבוטא בשניות מאז epoch. בזמן ש הוא גם יכול להשתמש במשתני הזרימה claim.name, המשתנה המומלץ לשימוש כדי לגשת להצהרה על זכויות יוצרים.
decoded.header.name ערך של כותרת שאפשר לנתח בפורמט JSON במטען הייעודי (Payload). משתנה אחד מוגדר עבור כל כותרת במטען הייעודי (payload). אפשר גם להשתמש במשתני הזרימה header.name, זה המשתנה המומלץ שבו צריך להשתמש כדי לגשת לכותרת.
expiry_formatted התאריך/שעת התפוגה בפורמט של מחרוזת שאנשים יכולים לקרוא. דוגמה: 2017-09-28T21:30:45.000+0000
header.algorithm אלגוריתם החתימה שנעשה בו שימוש ב-JWT. לדוגמה, RS256 , HS384 וכן הלאה. מידע נוסף זמין במאמר (Algorithm) Header Parameter.
header.kid מזהה המפתח, אם הוא נוסף בזמן יצירת ה-JWT. ראו גם "שימוש בערכת מפתחות אינטרנט מסוג JSON (JWKS)" ב-JWT סקירה כללית של המדיניות כדי לאמת JWT. מידע נוסף זמין במאמר (Key ID) Header Parameter (פרמטר הכותרת של מזהה המפתח).
header.type יוגדר כ-JWT.
header.name הערך של הכותרת בעלת השם (רגילה או נוספת). אחד מאלה יוגדר עבור כל כותרת נוספת בחלק הכותרת של ה-JWT.
header-json הכותרת בפורמט JSON.
is_expired נכון או לא נכון
payload-claim-names מערך הצהרות שנתמכות על ידי ה-JWT.
payload-json
המטען הייעודי (Payload) בפורמט JSON.
seconds_remaining מספר השניות לפני פקיעת התוקף של האסימון. אם פג התוקף של האסימון, המספר יהיה שלילי.
time_remaining_formatted הזמן שנותר לפני פקיעת התוקף של האסימון, בפורמט של מחרוזת שאנשים יכולים לקרוא. דוגמה: 00:59:59.926
valid במקרה של VerifyJWT, המשתנה הזה יהיה True כשהחתימה תאומת. הזמן הנוכחי הוא לפני תפוגת האסימון, ואחרי הערך לאלפני האסימון, אם קיימים. אחרת, הערך יהיה False.

במקרה של DecodeJWT, המשתנה הזה לא מוגדר.

התייחסות לשגיאות

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.jwt.FailedToDecode 401 Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
steps.jwt.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jwt.InvalidToken 401 Occurs when the flow variable specified in the <Source> element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidEmptyElement Occurs when the flow variable containing the JWT to be decoded is not specified in the <Source> element of the policy.

משתני כשל

המשתנים האלה מוגדרים כשמתרחשת שגיאה בסביבת זמן הריצה. מידע נוסף זמין במאמר מה צריך לדעת? על שגיאות שקשורות למדיניות.

משתנים איפה דוגמה
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>