VerifyJWS policy

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

מה

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

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

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

וידאו

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

דוגמאות

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

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

מדיניות לדוגמה שמאמתת קובץ JWS מצורף שנחתם באמצעות אלגוריתם ההצפנה HS256, ‏ HMAC באמצעות סכום ביקורת 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 מנותק, המטען הייעודי מושמט מה-JWS:

header..signature

אתם צריכים להעביר את מטען הנתונים למדיניות VerifyJWS על ידי ציון שם המשתנה שמכיל את מטען הנתונים ברכיב <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>

הפניה לרכיב

ההפניה למדיניות מתארת את האלמנטים והמאפיינים של מדיניות Verify JWS.

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<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 – (אופציונלי) אחד מהערכים הבאים: string (ברירת מחדל), number,‏ boolean או map
• ‫array – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: ‫false.

<DetachedContent>

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

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

header.payload.signature

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

header..signature

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

המדיניות מחזירה שגיאה במקרים הבאים:

• ‫<DetachedContent> מצוין כש-JWS לא מכיל מטען ייעודי (payload) של תוכן מנותק (קוד השגיאה הוא steps.jws.ContentIsNotDetached).
• הפרמטר <DetachedContent> מושמט וב-JWS יש מטען תוכן מנותק (קוד השגיאה הוא 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

הפניה לשגיאה

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

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

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

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

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

משתני כשל

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

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

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