מדיניות אימות JWT

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מה

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

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

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

מידע נוסף על החלקים של JWT ועל אופן ההצפנה והחתימה שלהם זמין ב-RFC7519.

וידאו

בסרטון הקצר הבא מוסבר איך מאמתים את החתימה ב-JWT.

טעימות

• אימות של JWT שנחתם באמצעות האלגוריתם HS256
• אימות JWT שנחתם באמצעות האלגוריתם RS256

אימות JWT החתום באמצעות האלגוריתם HS256

המדיניות לדוגמה הזו מאמתת JWT שנחתם באמצעות אלגוריתם ההצפנה HS256, HMAC באמצעות סיכום ביקורת של SHA-256. ה-JWT מועבר בבקשת שרת ה-proxy באמצעות פרמטר טופס שנקרא jwt. המפתח נמצא במשתנה בשם private.secretkey. בסרטון שלמעלה תוכלו לראות דוגמה מלאה לכך, כולל הסברים על שליחת בקשה למדיניות.

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

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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

אימות JWT החתום באמצעות האלגוריתם RS256

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

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

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

עבור התצורה שלמעלה, JWT עם הכותרת הזו...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

והמטען הייעודי (payload) הזה...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... תיחשב תקפה אם ניתן לאמת את החתימה באמצעות המפתח הציבורי שסופק.

JWT עם אותה כותרת אבל עם המטען הייעודי (payload) הזה...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... ייקבע כלא חוקי, גם אם ניתן לאמת את החתימה, מפני שהצהרת ה-"sub" הכלולה ב-JWT לא תואמת לערך הנדרש של האלמנט "Subject" כפי שצוין בהגדרת המדיניות.

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

הגדרת הרכיבים המרכזיים

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

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

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

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

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

הפניה לרכיב

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

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

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

<VerifyJWT name="JWT" 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*.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

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

<AdditionalClaims/Claims>

<AdditionalClaims>
    <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'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

אימות שהמטען הייעודי(payload) של JWT מכיל את ההצהרות הנוספות שצוינו, ושערכי ההצהרות שהוצהרו תואמים.

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

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

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

כשכוללים את הרכיב <Claim>, שמות התלונות מוגדרים בצורה סטטית במהלך הגדרת המדיניות. לחלופין, אפשר להעביר אובייקט JSON כדי לציין את שמות ההצהרות. מכיוון שאובייקט ה-JSON מועבר כמשתנה, שמות ההצהרות על זכויות יוצרים נקבעים בזמן הריצה.

לדוגמה:

<AdditionalClaims ref='json_claims'/>

כאשר המשתנה json_claims מכיל אובייקט JSON בצורה:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

<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>

מאמת שכותרת ה-JWT מכילה את צמדי השם/הערכים הנוספים של הצהרת זכויות היוצרים שציינתם, ושערכי ההצהרה שטענתם תואמים.

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

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

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

<CustomClaims>

הערה: בשלב הזה, המערכת מוסיפה רכיב CustomClaims כשמוסיפים מדיניות GenerateJWT חדשה דרך ממשק המשתמש. הרכיב הזה לא פעיל והמערכת מתעלמת ממנו. הרכיב הנכון לשימוש במקום זאת הוא <AdditionalClaims>. מאוחר יותר, ממשק המשתמש יעודכן ויוסיף את הרכיבים הנכונים.

<מזהה>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

מוודאים שה-JWT מכיל את הצהרת jti הספציפית. כשערך הטקסט והמאפיין ref ריקים, המדיניות תיצור jti שמכיל מזהה ייחודי אוניברסלי (UUID) אקראי. הצהרת מזהה JWT (jti) היא מזהה ייחודי של ה-JWT. מידע נוסף על jti זמין ב-RFC7519.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

צריך להגדיר את הערך כ-false (ברירת המחדל) אם רוצים שהמדיניות תכריע שגיאה כאשר JWT מכיל הצהרת iat (הונפקה בתאריך) שמציינת שעה בעתיד. יש להגדיר את הערך True כדי לגרום למדיניות להתעלם מ-iat במהלך האימות.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

המדיניות מאמתת שהמנפיק ב-JWT תואם למחרוזת שצוינה ברכיב התצורה. הצהרה שמזהה את מנפיק ה-JWT. זוהי אחת מקבוצת התלונות הרשומה שצוינה ב-RFC7519.

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

במדיניות GenerateJWT נעשה שימוש ברכיב <CriticalHeaders> כדי לאכלס את הכותרת crit ב-JWT. לדוגמה:

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

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

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

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

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

<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.

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

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

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</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>

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

<SecretKey/Value>

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.your-variable-name"/>
</SecretKey>

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

<מקור>

<Source>jwt-variable</Source>

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

<Subject>

<Subject>subject-string-here</Subject>

המדיניות מאמתת שהנושא ב-JWT תואם למחרוזת שצוינה בהגדרת המדיניות. הטענה הזו מציינת את הנושא של ה-JWT או מצהירה עליו. זוהי אחת מקבוצת התלונות הקבועה שצוינה ב-RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

'תקופת החסד' לזמנים. לדוגמה, אם מכסת הזמן מוגדרת ל-60 שניות, JWT שפג תוקפו יהיה בתוקף למשך 60 שניות אחרי התפוגה שהוצהרה. ההערכה לפני התאריך האחרון תוערך באופן דומה. ברירת המחדל היא 0 שניות (ללא תקופת חסד).

משתני זרימה

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

jwt.{policy_name}.{variable_name}

לדוגמה, אם שם המדיניות הוא jwt-parse-token , המדיניות תשמור את הנושא שצוין ב-JWT למשתנה ההקשר בשם jwt.jwt-parse-token.decoded.claim.sub. (בתאימות לאחור, תהיה זמינה גם ב-jwt.jwt-parse-token.claim.subject)

הפניה לשגיאות

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

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

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

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

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

משתני שבר

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

דוגמה לשגיאה

לטיפול בשגיאות, השיטה המומלצת היא להעתיק את החלק errorcode של התגובה לשגיאה. אין להסתמך על הטקסט שבfaultstring, כי הוא עשוי להשתנות.

דוגמה לכלל שגיאה

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>