מדיניות אימות 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 באמצעות סיכום ביקורת (checksum) מסוג 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 לא תואמת לערך הנדרש של ה'נושא' רכיב בתור שצוינו בהגדרות המדיניות.

הפלט של המדיניות נכתב במשתני ההקשר, כך שכללי המדיניות או התנאים הבאים נכתבים בשרת ה-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/Claim>

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

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

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

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

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

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

<CustomClaims>

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

<Id>

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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

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

<Source>jwt-variable</Source>

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

<Subject>

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

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

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

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

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

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

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.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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