מדיניות 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 באמצעות סיכום ביקורת של 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, משמט את המטען הייעודי (payload):

header..signature

באחריותך להעביר את המטען הייעודי (payload) למדיניות verificationJWS. לשם כך, צריך לציין את שם המשתנה שמכיל את המטען הייעודי לרכיב <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 - (אופציונלי) אחד מהערכים הבאים: מחרוזת (ברירת מחדל), מספר, בוליאני או מפה
• array – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: False.

<DetachedContent>

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

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

header.payload.signature

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

header..signature

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

המדיניות מקפיצה הודעת שגיאה כאשר:

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

צריך להגדיר את הערך כ-False אם רוצים שהמדיניות תגרום לשגיאה כשכותרת כלשהי שרשומה בכותרת crit של ה-JWS לא רשומה ברכיב <KnownHeaders>. יש להגדיר את הערך כ-True כדי לגרום למדיניות verificationJWS להתעלם מהכותרת 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” ],
}

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

אפשר להגדיר את המדיניות ValidJWS להתעלם מהכותרת 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>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>