‫DecodeJWS policy

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

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

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

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

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

header.payload.signature

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

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

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

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

אם הפעולה מצליחה, כללי המדיניות Verify JWS ו-Decode 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 וכן הלאה. מידע נוסף זמין במאמר בנושא פרמטר הכותרת(אלגוריתם).
header.kid	מזהה המפתח, אם הוא נוסף כשנוצר ה-JWS. כדי לאמת JWS, אפשר לעיין גם במאמר בנושא סקירה כללית של כללי מדיניות JWT ו-JWS, בקטע 'שימוש ב-JSON Web Key Set ‏(JWKS)'. מידע נוסף זמין במאמר בנושא פרמטר הכותרת(מזהה המפתח).
header.type	הערך של סוג הכותרת. מידע נוסף זמין במאמר בנושא פרמטר הכותרת(Type).
header.name	הערך של הכותרת שצוין השם שלה (רגילה או נוספת). אחד מהם יוגדר לכל כותרת נוספת בחלק של הכותרת ב-JWS.
header-json	הכותרת בפורמט JSON.
payload	מטען הייעודי (payload) של JWS אם יש לו מטען ייעודי מצורף. אם המטען הייעודי מנותק, המשתנה הזה ריק.
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 הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	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>