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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

מה

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

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

הפניה לרכיב עבור פענוח JWT

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

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

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

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

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

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

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

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

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

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

true אופציונלי
async המאפיין הזה הוצא משימוש. false הוצא משימוש

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<מקור>

<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 התאריך שבו הונפק האסימון, מבוטא באלפיות שנייה מאז epoch.
claim.issuer התביעה של מנפיק ה-JWT.
claim.notbefore אם ה-JWT כולל הצהרת nbf, המשתנה הזה יכיל את הערך, מבוטא באלפיות שנייה מאז תחילת התקופה.
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.kid מזהה המפתח, אם הוא נוסף בזמן יצירת ה-JWT. כדי לאמת JWT, ראו גם "שימוש ב-JSON Web Key Set (JWKS)" בסקירה הכללית על מדיניות JWT. מידע נוסף זמין במאמר פרמטר מפתח מזהה).
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 כשהחתימה מאומתת, והשעה הנוכחית היא לפני תפוגת האסימון ואחרי הערך של האסימון notBefore, אם הם קיימים. אחרת, הערך 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>