‫DecodeJWT policy

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

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

משתנים בתהליך

אם הפעולה מצליחה, מדיניות 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	תאריך ושעת התפוגה, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
claim.issuedat	התאריך שבו הונפק האסימון, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
claim.issuer	הצהרת המנפיק של JWT.
claim.notbefore	אם ה-JWT כולל טענת nbf, המשתנה הזה יכיל את הערך, שמבוטא באלפיות השנייה מאז תקופת ה-epoch.
claim.subject	הצהרת הנושא של JWT.
claim.name	הערך של הטענה עם השם (רגילה או נוספת) במטען הייעודי (payload). אחד מהערכים האלה יוגדר לכל טענה במטען הייעודי.
decoded.claim.name	הערך שניתן לניתוח באמצעות JSON של ההצהרה שצוין השם שלה (סטנדרטית או נוספת) במטען הייעודי (payload). משתנה אחד מוגדר לכל הצהרה במטען הייעודי. לדוגמה, אפשר להשתמש ב-decoded.claim.iat כדי לאחזר את השעה שבה הונפק JWT, בפורמט של שניות מאז תקופת האפוק. אפשר גם להשתמש במשתני זרימת העבודה claim.name, אבל מומלץ להשתמש במשתנה הזה כדי לגשת להצהרה.
decoded.header.name	הערך שניתן לניתוח ב-JSON של כותרת במטען הייעודי (payload). משתנה אחד מוגדר לכל כותרת במטען הייעודי (payload). אפשר גם להשתמש במשתני הזרימה header.name, אבל המשתנה המומלץ לגישה לכותרת הוא
expiry_formatted	תאריך ושעת התפוגה, בפורמט של מחרוזת שקריאה לאנשים. דוגמה: 2017-09-28T21:30:45.000+0000
header.algorithm	אלגוריתם החתימה שבו נעשה שימוש ב-JWT. לדוגמה, RS256,‏ HS384 וכן הלאה. מידע נוסף זמין במאמר בנושא פרמטר הכותרת(אלגוריתם).
header.kid	מזהה המפתח, אם הוא נוסף כשנוצר ה-JWT. אפשר גם לעיין בקטע 'שימוש בקבוצת מפתחות אינטרנט בפורמט JSON‏ (JWKS)' במאמר סקירה כללית של מדיניות JWT כדי לאמת JWT. מידע נוסף זמין במאמר פרמטר הכותרת(מזהה המפתח).
header.type	הערך יהיה JWT.
header.name	הערך של הכותרת עם השם (רגילה או נוספת). אחד מהם יוגדר לכל כותרת נוספת בחלק הכותרת של ה-JWT.
header-json	הכותרת בפורמט JSON.
is_expired	true or false
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 הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name Matches "InvalidToken"
JWT.failed	כל כללי המדיניות של JWT מגדירים את אותו משתנה במקרה של כשל.	JWT.failed = true

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

לצורך טיפול בשגיאות, מומלץ ללכוד את החלק 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>