מדיניות DecodeJWS

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

מה

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

ל-JWS יכול להיות מטען ייעודי (payload) מצורף, כמו בצורה הבאה:

header.payload.signature

לחלופין, ה-JWS יכול להשמיט את המטען הייעודי (payload), שנקרא detached מנותק, ולהיות בפורמט הבא:

header..signature

המדיניות DecodeJWS פועלת עם שני הטפסים כי היא מפענחת רק את חלק הכותרת של ה-JWS. המדיניות בנושא DecodeJWS פועלת גם בלי קשר לאלגוריתם ששימש לחתימה על ה-JWS.

לפרטים נוספים וסקירה כללית של הפורמט של JWS, קראו את הסקירה הכללית על מדיניות JWS ו-JWT.

וידאו

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

דוגמה: פענוח JWS

המדיניות שמוצגת בהמשך מפענחת JWS שנמצא במשתנה הזרימה var.JWS. המשתנה הזה חייב להיות קיים ולהכיל JWS בר-קיימא (שניתן לפענוח). המדיניות יכולה לקבל את ה-JWS מכל משתנה זרימה.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

לכל כותרת בחלק הכותרת של ה-JWS, המדיניות מגדירה משתנה זרימה בשם:

jws.policy-name.header.header-name

אם ל-JWS מצורף מטען ייעודי (payload), הוא מגדיר את משתנה הזרימה jws.policy-name.header.payload למטען הייעודי (payload). עבור מטען ייעודי (payload) שהתנתק, payload ריק. בקטע משתני זרימה מוצגת רשימה מלאה של המשתנים שמוגדרים במדיניות הזו.

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

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

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

<DecodeJWS name="JWS" 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>JWS-variable</Source>

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

ברירת מחדל	request.header.authorization (בהערה שלמעלה יש מידע חשוב על ברירת המחדל).
נוכחות	אופציונלי
סוג	מחרוזת
ערכים חוקיים	שם משתנה של זרימה ב-Edge

משתני זרימה

לאחר הצלחה, המדיניות אימות JWS ופענוח JWS מגדירה את משתני ההקשר בהתאם לדפוס הבא:

jws.{policy_name}.{variable_name}

לדוגמה, אם שם המדיניות הוא verify-jws, המדיניות תאחסן את האלגוריתם שצוין ב-JWS למשתנה ההקשר הזה: jws.verify-jws.header.algorithm

שם משתנה	תיאור
decoded.header.name	הערך שניתן לניתוח JSON של כותרת במטען הייעודי (payload). לכל כותרת במטען הייעודי (payload) מוגדר משתנה אחד. אפשר להשתמש גם במשתני הזרימה header.name, אבל זה המשתנה המומלץ כדי לגשת לכותרת.
header.algorithm	אלגוריתם החתימה שבו נעשה שימוש ב-JWS. לדוגמה, RS256, HS384 וכו'. מידע נוסף זמין בפרמטר של כותרת(Algorithm).
header.kid	מזהה המפתח, אם הוא נוסף בזמן יצירת ה-JWS. כדי לאמת JWS, ראו גם "שימוש ב-JSON Web Key Set (JWKS)" בסקירה הכללית על מדיניות JWT ו-JWS. מידע נוסף זמין במאמר פרמטר מפתח מזהה).
header.type	הערך של סוג הכותרת. מידע נוסף זמין במאמר פרמטר של כותרת(סוג).
header.name	הערך של הכותרת בעלת השם (רגילה או נוספת). אחת מהאפשרויות האלה תוגדר לכל כותרת נוספת בחלק הכותרת של ה-JWS.
header-json	הכותרת בפורמט JSON.
payload	אם המטען של JWS מצורף למטען הייעודי (payload) של JWS. אם מדובר במטען ייעודי שנותק, המשתנה הזה ריק.
valid	במקרה שלVerifyJWS, המשתנה הזה יהיה TRUE כשהחתימה מאומתת, והשעה הנוכחית היא לפני תפוגת האסימון ואחרי הערך של האסימון notBefore, אם הם קיימים. אחרת, הערך False. במקרה של DecodeJWS, המשתנה הזה לא מוגדר.

הפניה לשגיאות

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

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

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

קוד שגיאה	סטטוס HTTP	מופיע כאשר
steps.jws.FailedToDecode	401	המדיניות לא הצליחה לפענח את ה-JWS. יכול להיות שה-JWS פגום.
steps.jws.FailedToResolveVariable	401	מופיע כשמשתנה הזרימה שצוין ברכיב <Source> של המדיניות לא קיים.
steps.jws.InvalidClaim	401	כאשר חסרה תלונה על הפרת זכויות יוצרים או תלונה על הפרת זכויות יוצרים, או חוסר התאמה בכותרת או בכותרת חסרה.
steps.jws.InvalidJsonFormat	401	נמצא JSON לא חוקי בכותרת ה-JWS.
steps.jws.InvalidJws	401	השגיאה הזו מתרחשת כאשר אימות החתימה של JWS נכשל.
steps.jws.InvalidPayload	401	המטען הייעודי של JWS לא חוקי.
steps.jws.InvalidSignature	401	<DetachedContent> לא נכלל וב-JWS יש מטען ייעודי (payload) נפרד.
steps.jws.MissingPayload	401	המטען הייעודי של JWS חסר.
steps.jws.NoAlgorithmFoundInHeader	401	מופיע כשה-JWS משמיטה את כותרת האלגוריתם.
steps.jws.UnknownException	401	אירעה חריגה לא ידועה.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

שם השגיאה	מופיע כאשר
InvalidAlgorithm	הערכים החוקיים היחידים הם: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.
EmptyElementForKeyConfiguration FailedToResolveVariable InvalidConfigurationForActionAndAlgorithmFamily InvalidConfigurationForVerify InvalidEmptyElement InvalidFamiliesForAlgorithm InvalidKeyConfiguration InvalidNameForAdditionalClaim InvalidNameForAdditionalHeader InvalidPublicKeyId InvalidPublicKeyValue InvalidSecretInConfig InvalidTypeForAdditionalClaim InvalidTypeForAdditionalHeader InvalidValueForElement InvalidValueOfArrayAttribute InvalidVariableNameForSecret MissingConfigurationElement MissingElementForKeyConfiguration MissingNameForAdditionalClaim MissingNameForAdditionalHeader	שגיאות אפשריות אחרות בפריסה.

משתני שבר

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

משתנים	מיקום	דוגמה
fault.name="fault_name"	fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה.	fault.name Matches "TokenExpired"
JWS.failed	כל כללי המדיניות של JWS מגדירים את אותו משתנה במקרה של כשל.	jws.JWS-Policy.failed = true

דוגמה לשגיאה

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

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

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