מדיניות פענוח קוד JWT

מוצג המסמך של 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, המשתנה הזה לא מוגדר.

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

בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי 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>