מדיניות ValidJWS

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

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

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

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

וידאו

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

טעימות

• אימות של מסמך JWS מצורף שנחתם באמצעות ה-HS256 אלגוריתם
• אימות של JWS מנותק שנחתם באמצעות ה-RS256 אלגוריתם

אימות של מסמך JWS מצורף שנחתם עם ה-HS256 אלגוריתם

המדיניות לדוגמה הזו מאמתת קובץ JWS מצורף שנחתם באמצעות אלגוריתם ההצפנה HS256, HMAC באמצעות סיכום ביקורת (checksum) מסוג SHA-256. ה-JWS מועבר בבקשת שרת ה-proxy באמצעות פרמטר טופס בשם JWS המפתח נמצא במשתנה בשם private.secretkey.

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

header.payload.signature

הגדרת המדיניות כוללת את המידע שנדרש ל-Edge כדי לפענח ולהעריך את ה-JWS. למשל, איפה למצוא את ה-JWS (במשתנה זרימה שצוין ברכיב <Source>), את אלגוריתם החתימה הנדרש ואיפה נמצא המפתח הסודי (שמאוחסן במשתנה זרימה של Edge, שיכול אוחזרו מ-Edge KVM, לדוגמה).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

הפלט של המדיניות נכתב במשתני ההקשר, כך שכללי המדיניות או התנאים הבאים נכתבים בשרת ה-proxy ל-API יכול לבדוק את הערכים האלה. בקטע משתני זרימה אפשר למצוא של המשתנים שהוגדרו במדיניות הזו.

אימות של JWS מנותק שנחתם עם ה-RS256 אלגוריתם

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

JWS מנותק משמיט את המטען הייעודי (payload) מה-JWS:

header..signature

באחריותך להעביר את המטען הייעודי (payload) למדיניות VerifyJWS על ידי ציון שם המשתנה שמכיל את המטען הייעודי (payload) אל רכיב <DetachedContent>. התוכן שצוין ב-<DetachedContent> להיות בפורמט המקורי שאינו מקודד שבו נוצרה חתימת ה-JWS.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

הפלט של המדיניות נכתב במשתני ההקשר, כך שכללי המדיניות או התנאים הבאים נכתבים בשרת ה-proxy ל-API יכול לבדוק את הערכים האלה. בקטע משתני זרימה אפשר למצוא של המשתנים שהוגדרו במדיניות הזו.

הגדרת הרכיבים העיקריים

הרכיבים שבהם משתמשים כדי לציין את המפתח שמשמש לאימות ה-JWS תלויים באלגוריתם שנבחר, כפי שמוצג בטבלה הבאה:

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

הפניה לרכיב

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

מציינת את אלגוריתם ההצפנה לצורך חתימה על האסימון. אלגוריתמי RS*/PS*/ES* משתמשים בזוג מפתחות ציבורי/סודי, ואילו אלגוריתמים של HS* משתמשים בסוד משותף. ראו גם מידע על אלגוריתמים להצפנת חתימות

אפשר לציין כמה ערכים ולהפריד ביניהם באמצעות פסיקים. לדוגמה "HS256, HS512" או RS256, PS256. עם זאת, לא ניתן לשלב אלגוריתמים של HS* עם אחרים או עם אלגוריתמים של ES* עם אחרים, כי הם לדרוש סוג מפתח ספציפי. אפשר לשלב אלגוריתמי RS* ו-PS*.

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

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

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

הרכיב <Claim> לוקח את המאפיינים הבאים:

• name – (חובה) שם התלונה.
• ref - (אופציונלי) השם של משתנה זרימה. אם השדה הזה קיים, המדיניות תשתמש בערך בתור ההצהרה. אם ציינתם גם מאפיין ref וגם ערך הצהרה מפורש, הערך של הפרמטר ערך מפורש הוא ברירת המחדל, ויש להשתמש בו אם משתנה הזרימה המופנה לא מפוענח.
• type – (אופציונלי) אחת מהאפשרויות: מחרוזת (ברירת מחדל), מספר, ערך בוליאני או מפה
• מערך – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: לא נכון.

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

JWS שנוצר עם מטען ייעודי (payload) של תוכן מופיע בתבנית:

header.payload.signature

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

header..signature

במטען ייעודי (payload) מנותק, באחריותך להעביר את המטען הייעודי (payload) למדיניות VerifyJWS באמצעות רכיב <DetachedContent>. המטען הייעודי של התוכן שצוין חייב להיות במקור לא מקודד זה היה כשחתימת ה-JWS נוצרה.

המדיניות גורמת לשגיאה כאשר:

• הערך <DetachedContent> מצוין כש-JWS לא מכיל תוכן נותק מטען ייעודי (payload) (קוד השגיאה הוא steps.jws.ContentIsNotDetached).
• השדה <DetachedContent> הושמט ויש ל-JWS מטען ייעודי (payload) של תוכן שנותק (קוד השגיאה הוא steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

יש להגדיר את הערך False אם רוצים שהמדיניות תגרור שגיאה כשכותרת כלשהי שמופיעה ברשימה הכותרת crit של ה-JWS לא מופיעה ברכיב <KnownHeaders>. יש להגדיר את הערך כ-True כדי לגרום למדיניות VerifyJWS להתעלם מהכותרת crit.

אחת מהסיבות להגדיר את הרכיב הזה כ-True היא אם אתם בסביבת בדיקה אינך רוצה שהמדיניות תכשל בגלל חסרה כותרת.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<KnownHeaders>

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

מדיניות GenerateJWS משתמשת ברכיב <CriticalHeaders> כדי לאכלס את הכותרת crit באסימון. לדוגמה:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

המדיניות של VerifyJWS בודקת את כותרת ה-crit ב-JWS, אם היא קיימת, ולכל פריט שצוין בה בודקת שהרכיב <KnownHeaders> גם מציין את הכותרת הזו. הרכיב <KnownHeaders> יכול להכיל קבוצת-על של הפריטים שרשומים ב-crit. חשוב רק שכל הכותרות המפורטות ב-crit יופיעו ב רכיב <KnownHeaders>. כל כותרת שהמדיניות מוצאת בקטע crit שלא מופיע גם ב-<KnownHeaders>, גורמת למדיניות VerifyJWS להיכשל.

אפשר להגדיר את המדיניות VerifyJWS להתעלם מהכותרת crit על ידי הגדרת הרכיב <IgnoreCriticalHeaders> ל-true.

<PublicKey/JWKS>

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

מציין ערך בפורמט JWKS (RFC 7517) שמכילה קבוצה של מפתחות ציבוריים. יש להשתמש רק כאשר האלגוריתם הוא אחד מהערכים RS256/RS384/RS512, PS256/PS384/PS512, או ב-ES256/ES384/ES512.

אם ה-JWS הנכנס נושא מזהה מפתח שמופיע בקבוצה של JWKS, אז המדיניות תשתמש במפתח הציבורי הנכון כדי לאמת את חתימת ה-JWS. לפרטים על התכונה הזו, ראו שימוש ב-JSON Web Key Set (JWKS) כדי לאמת JWS.

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

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

מציינת את המפתח הציבורי שמשמש לאימות החתימה ב-JWS. שימוש במאפיין ref כדי מעבירים את המפתח במשתנה זרימה, או מציינים את המפתח בקידוד PEM באופן ישיר. יש להשתמש רק כאשר הוא אחד מהפרמטרים הבאים: RS256/RS384/RS512 , PS256/PS384/PS512 או ES256/ES384/ES512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

מספקת את המפתח הסודי המשמש לאימות אסימונים או לחתימה עליהם באמצעות אלגוריתם HMAC. שימוש בלבד כאשר האלגוריתם הוא אחד מ-HS256, HS384, HS512. שימוש במאפיין ref כדי להעביר את המפתח במשתנה זרימה.

<Source>

<Source>JWS-variable</Source>

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

משתני זרימה

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

jws.{policy_name}.{variable_name}

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

התייחסות לשגיאות

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

משתני כשל

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

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

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