‫VerifyJWT policy

אתם צופים במסמכי התיעוד של 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"
}

המטען הייעודי הזה …

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

הפניה לרכיב

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

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

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

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

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

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

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

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

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

<CustomClaims>

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

<Id>

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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

אם רוצים שהמדיניות תציג שגיאה כש-JWT מכיל טענה של iat (זמן הנפקה) שמציינת זמן עתידי, צריך להגדיר את הערך false (ברירת מחדל). אם המדיניות מוגדרת כ-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 שניות (אין תקופת חסד).

משתני זרימה

לאחר השלמת התהליך, כללי המדיניות אימות 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>