‫DecodeJWT policy

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

מה

פענוח של 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>

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

הסבר על רכיבים של Decode JWT

הפניה למדיניות מתארת את האלמנטים והמאפיינים של מדיניות Decode JWT.

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

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

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

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

אופציונלית, אפשר להשתמש ברכיב <displayname></displayname> כדי לתת למדיניות שם אחר בשפה טבעית, ולתייג אותה בכלי לעריכת ה-proxy של ממשק ניהול.

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

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

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

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

 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 התאריך/שעת התפוגה, מבוטא באלפיות השנייה מאז 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, המשתנה הזה לא מוגדר.

הפניה לשגיאה

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

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד שגיאה סטטוס HTTP סיבה תיקון
steps.jwt.FailedToDecode 401 מופיע כשהמדיניות לא יכולה לפענח את ה-JWT. יכול להיות שה-JWT לא תקין, לא תקין או לא ניתן לפענוח.
steps.jwt.FailedToResolveVariable 401 מופיע כשמשתנה הזרימה שצוין ברכיב <Source> של המדיניות לא קיים.
steps.jwt.InvalidToken 401 הערך הזה מופיע כשמשתנה הזרימה שצוין ברכיב <Source> של המדיניות לא רלוונטי או שלא ניתן לפענח אותו.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

שם השגיאה סיבה תיקון
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>