מדיניות DecodeJWS

מדיניות ניתנת להרחבה

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

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

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

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

header.payload.signature

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

header..signature

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

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

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

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

הפניה לרכיב Decode JWS

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

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

<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>JWS-variable</Source>

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

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

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

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

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

משתני Flow

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

jws.{policy_name}.{variable_name}

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

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

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס 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	המטען הייעודי (payload) של JWS לא תקין.
steps.jws.InvalidSignature	401	‫<DetachedContent> מושמט, ול-JWS יש מטען ייעודי (payload) של תוכן מנותק.
steps.jws.MissingPayload	401	מטען הייעודי (payload) של 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>