‫DecodeJWS policy

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

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

לא רלוונטי חובה
continueOnError מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים.

הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת.

FALSE אופציונלי
מופעל כדי לאכוף את המדיניות, צריך להגדיר את הערך true.

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

TRUE אופציונלי
אסינכרוני המאפיין הזה הוצא משימוש. FALSE הוצא משימוש

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>JWS-variable</Source>

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

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

流变量

成功后,验证 JWS 和解码 JWS 政策将根据此模式设置上下文变量:

jws.{policy_name}.{variable_name}

例如,如果政策名称为 verify-jws,则该政策会将 JWS 中指定的算法存储在此上下文变量中:jws.verify-jws.header.algorithm

变量名称 说明
decoded.header.name 载荷中标头的 JSON 可解析值。为载荷中的每个标头设置一个变量。虽然您还可以使用 header.name 流变量,但建议使用此变量来访问标头。
header.algorithm JWS 中使用的签名算法。例如 RS256、HS384 等。如需了解详情,请参阅(算法)标头参数。
header.kid 生成 JWS 时添加的密钥 ID。另请参阅 JWT 和 JWS 政策概览中的“使用 JSON 网络密钥集 (JWKS)”来验证 JWS。如需了解详情,请参阅(密钥 ID)标头参数。
header.type 标头类型值。如需了解详情,请参阅(类型)标头参数。
header.name 已命名标头的值(标准或附加)。将为 JWS 标头部分中的每个附加标头设置其中一个。
header-json JSON 格式的标头。
payload 如果 JWS 具有附加的载荷,则为 JWS 载荷。对于分离的载荷,此变量为空。
valid 对于 VerifyJWS,在验证签名时,此变量为 true,而且当前时间在令牌有效期之前且在令牌 notBefore 值之后(如果两者存在)。否则为 false。

对于 DecodeJWS,无需设置此变量。

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jws.FailedToDecode 401 The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.FailedToResolveVariable 401 Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidJws 401 This error occurs when the JWS signature verification fails.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.UnknownException 401 An unknown exception occurred.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when
InvalidAlgorithm The only valid values are: 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

Other possible deployment errors.

故障变量

发生运行时错误时,系统会设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。

变量 其中 示例
fault.name="fault_name" fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "TokenExpired"
JWS.failed 所有 JWT 政策都将在发生故障时设置同一变量。 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>