מדיניות DecodeJWT

מדיניות רגילה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל: `A-Z0-9._\-$ %`. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים. אופציונלי. אפשר להשתמש ברכיב `<displayname></displayname>` כדי להוסיף תווית למדיניות בכלי לעריכת ה-proxy בממשק המשתמש של Apigee, עם שם אחר בשפה טבעית.	לא רלוונטי	חובה
continueOnError	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת.	FALSE	אופציונלי
מופעל	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
אסינכרוני	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

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

הערה: כברירת מחדל, ה-JWT מאוחזר מהמשתנה request.header.authorization. במקרה הזה, Apigee מחפש את ה-JWT בכותרת Authorization של הבקשה. אם מעבירים את ה-JWT בכותרת Authorization, לא צריך לכלול את רכיב Source במדיניות, אבל חייבים לכלול את Bearer בכותרת האימות. לדוגמה, אפשר להעביר את ה-JWT בכותרת Authorization כך:

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

אפשר להגדיר את המדיניות כך שתאחזר את ה-JWT ממשתנה של טופס או פרמטר שאילתה, או מכל משתנה אחר. אם המשתנה לא קיים או אם המדיניות לא מצליחה למצוא את ה-JWT, המדיניות מחזירה שגיאה.

ברירת מחדל	`request.header.authorization` (מידע חשוב על ברירת המחדל מופיע בהערה שלמעלה).
נוכחות	אופציונלי
סוג	String
ערכים אפשריים	שם של משתנה בתהליך Apigee

משתני Flow

אם הפעולה מצליחה, כללי המדיניות Verify JWT ו-Decode 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`	הערך של כותרת במטען הייעודי (payload) שאפשר לנתח ב-JSON. משתנה אחד מוגדר לכל כותרת במטען הייעודי (payload). אפשר גם להשתמש במשתני הזרימה `header.name`, אבל מומלץ להשתמש במשתנה הזה כדי לגשת לכותרת.
`expiry_formatted`	תאריך ושעת התפוגה, בפורמט של מחרוזת שאנשים יכולים לקרוא. דוגמה: 2017-09-28T21:30:45.000+0000
`header.algorithm`	אלגוריתם החתימה שבו נעשה שימוש ב-JWT. לדוגמה, RS256,‏ HS384 וכן הלאה. מידע נוסף זמין במאמר פרמטר הכותרת(אלגוריתם).
`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, המשתנה הזה לא מוגדר.

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס 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` הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name Matches "InvalidToken"`
`JWT.failed`	כל כללי המדיניות של JWT מגדירים את אותו משתנה במקרה של כשל.	`JWT.failed = true`

דוגמה לתגובת שגיאה

קודי תקלות של מדיניות JWT

לצורך טיפול בשגיאות, מומלץ ללכוד את החלק errorcode בתגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

דוגמה לכלל שגיאה

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>

מדיניות DecodeJWT קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.