כרגע מוצג התיעוד של 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 אוכפים הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.
אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך false כדי להחזיר שגיאה במקרה של כישלון במדיניות. זו התנהגות צפויה
ברוב כללי המדיניות.
צריך להגדיר את הערך |
false | אופציונלי |
פעיל |
צריך להגדיר את הערך true כדי לאכוף את המדיניות.
צריך להגדיר את הערך |
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 לא תקין, לא תקין או לא ניתן לפענוח. | build |
steps.jwt.FailedToResolveVariable |
401 | מופיע כשמשתנה הזרימה שצוין ברכיב <Source> של המדיניות לא קיים. |
|
steps.jwt.InvalidToken |
401 | הערך הזה מופיע כשמשתנה הזרימה שצוין ברכיב <Source> של המדיניות
לא רלוונטי או שלא ניתן לפענח אותו. |
build |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה | תיקון |
---|---|---|
InvalidEmptyElement |
מופיע כשמשתנה הזרימה שמכיל את ה-JWT לפענוח לא צוין ברכיב <Source> של המדיניות.
|
build |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה. | fault.name Matches "TokenExpired" |
JWT.failed |
כל כללי המדיניות של JWT מגדירים את אותו משתנה במקרה של כשל. | JWT.failed = true |
דוגמה לשגיאה
לטיפול בשגיאות, השיטה המומלצת היא להעתיק את החלק 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>