כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
מה
אימות החתימה ב-JWT שהתקבל מלקוחות או ממערכות אחרות. המדיניות הזו גם מחלצת את ההצהרות למשתני הקשר, כדי שכללי המדיניות או התנאים הבאים יוכלו לבחון את הערכים האלה כדי לקבל החלטות בנוגע להרשאות או לניתוב. מבוא מפורט זמין בסקירה הכללית על מדיניות JWS ו-JWT.
כשהמדיניות הזו מתקיימת, Edge מאמת את החתימה של JWT ומאמת שה-JWT תקף בהתאם למועד התפוגה ולא לפני כן, אם הם קיימים. המדיניות יכולה לאמת גם את הערכים של תלונות ספציפיות ב-JWT, כמו הנושא, המנפיק, הקהל או הערך של תלונות נוספות.
אם ה-JWT מאומת ותקף, כל ההצהרות שכלולות ב-JWT חולצו למשתני הקשר לשימוש במדיניות או בתנאים הבאים, והבקשה יכולה להמשיך. אם לא ניתן לאמת את חתימת ה-JWT או שה-JWT לא תקין בגלל אחת מחותמות הזמן, כל העיבודים מופסקים ותוחזר שגיאה בתגובה.
מידע נוסף על החלקים של JWT ועל אופן ההצפנה והחתימה שלהם זמין ב-RFC7519.
וידאו
בסרטון הקצר הבא מוסבר איך מאמתים את החתימה ב-JWT.
טעימות
אימות 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 תלויים באלגוריתם שנבחר, כפי שמוצג בטבלה הבאה:
אלגוריתם | אלמנטים מרכזיים | |
---|---|---|
HS* |
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <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">
המאפיינים הבאים משותפים לכל רכיבי ההורה של המדיניות.
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
name |
השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל:
A-Z0-9._\-$ % . אבל בממשק המשתמש לניהול Edge אוכפים הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.
אפשר להשתמש באלמנט |
לא רלוונטי | חובה |
continueOnError |
צריך להגדיר את הערך false כדי להחזיר שגיאה במקרה של כישלון במדיניות. זו התנהגות צפויה
ברוב כללי המדיניות.
צריך להגדיר את הערך |
false | אופציונלי |
פעיל |
צריך להגדיר את הערך true כדי לאכוף את המדיניות.
צריך להגדיר את הערך |
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*.
ברירת מחדל | לא רלוונטי |
נוכחות | חובה |
סוג | מחרוזת של ערכים מופרדים בפסיקים |
ערכים חוקיים | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<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 רשומות. הערך של הצהרה נוספת יכול להיות מחרוזת, מספר, ערך בוליאני, מפה או מערך. מפה היא קבוצה של צמדים של שם/ערך. אפשר לציין את הערך של הצהרה מכל אחד מהסוגים האלה במפורש בהגדרות המדיניות, או בעקיפין באמצעות הפניה למשתנה זרימה.
ברירת מחדל | לא רלוונטי |
נוכחות | אופציונלי |
סוג | מחרוזת, מספר, ערך בוליאני או מפה |
מערך | מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: False |
ערכים חוקיים | כל ערך שבו רוצים להשתמש להצהרה נוספת על זכויות יוצרים. |
הרכיב <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 רשומות. הערך של הצהרה נוספת יכול להיות מחרוזת, מספר, ערך בוליאני, מפה או מערך. מפה היא קבוצה של צמדים של שם/ערך. אפשר לציין את הערך של הצהרה מכל אחד מהסוגים האלה במפורש בהגדרות המדיניות, או בעקיפין באמצעות הפניה למשתנה זרימה.
ברירת מחדל | לא רלוונטי |
נוכחות | אופציונלי |
סוג |
מחרוזת (ברירת מחדל), מספר, בוליאני או מפה. ברירת המחדל של הסוג היא 'מחרוזת' אם לא צוין טיפוס. |
מערך | מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: False |
ערכים חוקיים | כל ערך שבו רוצים להשתמש להצהרה נוספת על זכויות יוצרים. |
הרכיב <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 היא אם נמצאים בסביבת בדיקה ועדיין לא מוכנים לגרום לתקלה בכותרת חסרה.
ברירת מחדל | false |
נוכחות | אופציונלי |
סוג | בוליאני |
ערכים חוקיים | נכון או לא נכון |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
צריך להגדיר את הערך כ-false (ברירת המחדל) אם רוצים שהמדיניות תכריע שגיאה כאשר JWT מכיל הצהרת
iat
(הונפקה בתאריך) שמציינת שעה בעתיד.
יש להגדיר את הערך True כדי לגרום למדיניות להתעלם מ-iat
במהלך האימות.
ברירת מחדל | false |
נוכחות | אופציונלי |
סוג | בוליאני |
ערכים חוקיים | נכון או לא נכון |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
צריך להגדיר את הערך כ-false אם רוצים שהמדיניות תגרור שגיאה כאשר לא ניתן לפתור את משתנה ההפניה שצוין במדיניות. צריך להגדיר את הערך True כדי להתייחס לכל משתנה שלא ניתן לפתרון כמחרוזת ריקה (null).
ברירת מחדל | false |
נוכחות | אופציונלי |
סוג | בוליאני |
ערכים חוקיים | נכון או לא נכון |
<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.
ברירת מחדל | לא רלוונטי |
נוכחות | כדי לאמת JWT שחתום באמצעות אלגוריתם RSA, צריך להשתמש ברכיבים של האישור, JWKS או הערך. |
סוג | מחרוזת |
ערכים חוקיים | מחרוזת או משתנה זרימה. |
<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 שוב.
ברירת מחדל | לא רלוונטי |
נוכחות | כדי לאמת JWT באמצעות אלגוריתם RSA, צריך להשתמש ברכיב Certificate, JWKS או Value. |
סוג | מחרוזת |
ערכים חוקיים | משתנה זרימה, ערך מחרוזת או כתובת URL. |
<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.
ברירת מחדל | לא רלוונטי |
נוכחות | כדי לאמת JWT שחתום באמצעות אלגוריתם RSA, צריך להשתמש ברכיבים של האישור, JWKS או הערך. |
סוג | מחרוזת |
ערכים חוקיים | מחרוזת או משתנה זרימה. |
<SecretKey/Value>
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.your-variable-name"/> </SecretKey>
מספקת את המפתח הסודי המשמש לאימות אסימונים או לחתימה עליהם באמצעות אלגוריתם HMAC. יש להשתמש רק כאשר האלגוריתם הוא מסוג HS256 , HS384 או HS512.
ברירת מחדל | לא רלוונטי |
נוכחות | נדרשת לאלגוריתמים של HMAC. |
סוג | מחרוזת |
ערכים חוקיים |
עבור אפשר להשתמש במאפיין ref כדי להעביר את המפתח במשתנה זרימה. הערה: אם משתנה זרימה, יש להוסיף לו את הקידומת "private". לדוגמה,
|
<מקור>
<Source>jwt-variable</Source>
אם השדה הזה קיים, הוא מציין את משתנה הזרימה שבו המדיניות מצפה למצוא את ה-JWT לאימות.
ברירת מחדל | request.header.authorization (בהערה שלמעלה יש מידע חשוב על ברירת המחדל). |
נוכחות | אופציונלי |
סוג | מחרוזת |
ערכים חוקיים | שם משתנה של זרימה ב-Edge. |
<Subject>
<Subject>subject-string-here</Subject>
המדיניות מאמתת שהנושא ב-JWT תואם למחרוזת שצוינה בהגדרת המדיניות. הטענה הזו מציינת את הנושא של ה-JWT או מצהירה עליו. זוהי אחת מקבוצת התלונות הקבועה שצוינה ב-RFC7519.
ברירת מחדל | לא רלוונטי |
נוכחות | אופציונלי |
סוג | מחרוזת |
ערכים חוקיים | כל ערך שמזהה נושא באופן ייחודי. |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
'תקופת החסד' לזמנים. לדוגמה, אם מכסת הזמן מוגדרת ל-60 שניות, JWT שפג תוקפו יהיה בתוקף למשך 60 שניות אחרי התפוגה שהוצהרה. ההערכה לפני התאריך האחרון תוערך באופן דומה. ברירת המחדל היא 0 שניות (ללא תקופת חסד).
ברירת מחדל | 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
)
שם משתנה | התיאור |
---|---|
claim.audience |
תביעת הבעלות על קהל ה-JWT. הערך הזה יכול להיות מחרוזת או מערך של מחרוזות. |
claim.expiry |
התאריך/שעת התפוגה, מבוטא באלפיות שנייה מאז תחילת התקופה. |
claim.issuedat |
התאריך שבו הונפק האסימון, מבוטא באלפיות שנייה מאז epoch. |
claim.issuer |
התביעה של מנפיק ה-JWT. |
claim.notbefore |
אם ה-JWT כולל הצהרת nbf, המשתנה הזה יכיל את הערך, מבוטא באלפיות שנייה מאז תחילת התקופה. |
claim.subject |
התלונה לגבי נושא ה-JWT. |
claim.name |
הערך של הצהרת זכויות היוצרים בעלת השם (רגילה או נוספת) במטען הייעודי (payload). אחת מהאפשרויות האלה תוגדר לכל הצהרה על זכויות יוצרים במטען הייעודי (payload). |
decoded.claim.name |
הערך הניתן לניתוח JSON של התביעה בעלת השם (רגיל או נוסף) במטען הייעודי (payload). משתנה אחד מוגדר
לכל הצהרה על זכויות יוצרים במטען הייעודי (payload). לדוגמה, אפשר להשתמש ב-decoded.claim.iat כדי
לאחזר את השעה שהונפקו בזמן ה-JWT, מבוטא בשניות מאז תחילת התקופה (epoch). אפשר
להשתמש גם במשתני הזרימה claim.name , אבל זהו
המשתנה המומלץ כדי לגשת להצהרה על זכויות יוצרים. |
decoded.header.name |
הערך שניתן לניתוח JSON של כותרת במטען הייעודי (payload). לכל כותרת במטען הייעודי (payload) מוגדר משתנה אחד. אפשר להשתמש גם במשתני הזרימה header.name ,
אבל זה המשתנה המומלץ כדי לגשת לכותרת. |
expiry_formatted |
התאריך/שעת התפוגה, בפורמט של מחרוזת שאנשים יכולים לקרוא. לדוגמה: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
אלגוריתם החתימה שבו נעשה שימוש ב-JWT. לדוגמה, RS256, HS384 וכו'. מידע נוסף זמין בפרמטר של כותרת(Algorithm). |
header.kid |
מזהה המפתח, אם הוא נוסף בזמן יצירת ה-JWT. כדי לאמת JWT, ראו גם "שימוש ב-JSON Web Key Set (JWKS)" בסקירה הכללית על מדיניות JWT. מידע נוסף זמין במאמר פרמטר מפתח מזהה). |
header.type |
יוגדר לערך JWT . |
header.name |
הערך של הכותרת בעלת השם (רגילה או נוספת). אחת מהאפשרויות האלה תוגדר לכל כותרת נוספת בחלק הכותרת של ה-JWT. |
header-json |
הכותרת בפורמט JSON. |
is_expired |
נכון או לא נכון |
payload-claim-names |
מערך של תביעות הנתמכות על ידי ה-JWT. |
payload-json |
המטען הייעודי (payload) בפורמט JSON.
|
seconds_remaining |
מספר השניות עד שיפוג התוקף של האסימון. אם תוקף האסימון פג, המספר יהיה שלילי. |
time_remaining_formatted |
הזמן שנותר עד שיפוג התוקף של האסימון, בפורמט של מחרוזת שאנשים יכולים לקרוא. דוגמה: 00:59:59.926 |
valid |
במקרה שלVerifyJWT, המשתנה הזה יהיה TRUE כשהחתימה מאומתת,
והשעה הנוכחית היא לפני תפוגת האסימון ואחרי הערך של האסימון notBefore, אם הם
קיימים. אחרת, הערך False.
במקרה של DecodeJWT, המשתנה הזה לא מוגדר. |
הפניה לשגיאות
בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בזמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
קוד שגיאה | סטטוס HTTP | מופיע כאשר |
---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 | מופיע כשמדיניות האימות כוללת כמה אלגוריתמים. |
steps.jwt.AlgorithmMismatch |
401 | האלגוריתם שצוין במדיניות היצירה לא תאם לאלגוריתם המצופה במדיניות האימות. האלגוריתמים שצוינו צריכים להתאים. |
steps.jwt.FailedToDecode |
401 | המדיניות לא הצליחה לפענח את ה-JWT. ייתכן שה-JWT פגום. |
steps.jwt.GenerationFailed |
401 | המדיניות לא הצליחה ליצור את ה-JWT. |
steps.jwt.InsufficientKeyLength |
401 | למפתח עם פחות מ-32 בייטים לאלגוריתם HS256, פחות מ-48 בייטים לאגוריתמי HS386 ופחות מ-64 בייטים לאלגוריתם HS512. |
steps.jwt.InvalidClaim |
401 | כאשר חסרה תלונה על הפרת זכויות יוצרים או תלונה על הפרת זכויות יוצרים, או חוסר התאמה בכותרת או בכותרת חסרה. |
steps.jwt.InvalidCurve |
401 | העקומה שצוינה על ידי המפתח אינה חוקית עבור האלגוריתם 'עקומה אליפטית'. |
steps.jwt.InvalidJsonFormat |
401 | נמצא JSON לא חוקי בכותרת או במטען הייעודי (payload). |
steps.jwt.InvalidToken |
401 | השגיאה הזו מתרחשת כאשר אימות החתימה של JWT נכשל. |
steps.jwt.JwtAudienceMismatch |
401 | תביעת הבעלות על הקהל נכשלה באימות האסימון. |
steps.jwt.JwtIssuerMismatch |
401 | תביעת המנפיק נכשלה בתהליך אימות האסימון. |
steps.jwt.JwtSubjectMismatch |
401 | תביעת הבעלות על הנושא נכשלה באימות האסימון. |
steps.jwt.KeyIdMissing |
401 | במדיניות האימות נעשה שימוש ב-JWKS כמקור למפתחות ציבוריים, אבל ה-JWT החתום
לא כולל נכס kid בכותרת. |
steps.jwt.KeyParsingFailed |
401 | לא ניתן היה לנתח את המפתח הציבורי מפרטי המפתח שצוינו. |
steps.jwt.NoAlgorithmFoundInHeader |
401 | מופיע כשה-JWT לא מכיל כותרת אלגוריתם. |
steps.jwt.NoMatchingPublicKey |
401 | במדיניות האימות נעשה שימוש ב-JWKS כמקור למפתחות ציבוריים, אבל kid
ב-JWT החתום לא רשום ב-JWKS. |
steps.jwt.SigningFailed |
401 | ב-GenerateJWT, למפתח שגודלו קטן מהגודל המינימלי לאלגוריתמים HS384 או HS512 |
steps.jwt.TokenExpired |
401 | המדיניות מנסה לאמת אסימון שפג תוקפו. |
steps.jwt.TokenNotYetValid |
401 | האסימון עדיין לא תקף. |
steps.jwt.UnhandledCriticalHeader |
401 | כותרת שנמצאה במדיניות 'אימות JWT' בכותרת crit לא
רשומה ב-KnownHeaders . |
steps.jwt.UnknownException |
401 | אירעה חריגה לא ידועה. |
steps.jwt.WrongKeyType |
401 | צוין סוג שגוי של מפתח. לדוגמה, אם ציינת מפתח RSA לאלגוריתם Elliptic Curve, או מפתח עקומה לאלגוריתם RSA. |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה | תיקון |
---|---|---|
InvalidNameForAdditionalClaim |
הפריסה תיכשל אם ההצהרה שנעשה בה שימוש ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> היא אחד מהשמות הרשומים הבאים:
kid , iss , sub , aud , iat ,
exp , nbf או jti .
|
build |
InvalidTypeForAdditionalClaim |
אם ההצהרה שנעשה בה שימוש ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> אינה מסוג string , number , boolean או map , הפריסה תיכשל.
|
build |
MissingNameForAdditionalClaim |
אם שם ההצהרה לא צוין ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> , הפריסה תיכשל.
|
build |
InvalidNameForAdditionalHeader |
השגיאה הזו נשלחת כאשר שם הצהרת זכויות היוצרים ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> הוא alg או typ .
|
build |
InvalidTypeForAdditionalHeader |
אם סוג התביעה שבו נעשה שימוש ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> אינו מסוג string , number , boolean או map , הפריסה תיכשל.
|
build |
InvalidValueOfArrayAttribute |
השגיאה הזו מתרחשת כאשר הערך של מאפיין המערך ברכיב הצאצא <Claim>
של הרכיב <AdditionalClaims> לא מוגדר ל-true או ל-false .
|
build |
InvalidValueForElement |
אם הערך שצוין ברכיב <Algorithm> אינו ערך נתמך, הפריסה תיכשל.
|
build |
MissingConfigurationElement |
השגיאה הזו תופיע אם לא משתמשים ברכיב <PrivateKey> בשילוב עם אלגוריתמים ממשפחת RSA, או אם לא משתמשים ברכיב <SecretKey> באלגוריתמים של משפחת HS.
|
build |
InvalidKeyConfiguration |
אם רכיב הצאצא <Value> לא מוגדר ברכיבים <PrivateKey> או <SecretKey> , הפריסה תיכשל.
|
build |
EmptyElementForKeyConfiguration |
אם מאפיין ה-ref של אלמנט הצאצא <Value> מתוך הרכיבים <PrivateKey>
או <SecretKey> ריק או שלא צוין, הפריסה תיכשל.
|
build |
InvalidConfigurationForVerify |
השגיאה הזו מופיעה אם הרכיב <Id> מוגדר בתוך הרכיב <SecretKey> .
|
build |
InvalidEmptyElement |
השגיאה הזו מתרחשת אם הרכיב <Source> של המדיניות 'אימות JWT'
ריק. אם היא קיימת, יש להגדיר אותה עם שם משתנה של זרימה ב-Edge.
|
build |
InvalidPublicKeyValue |
אם הערך המשמש ברכיב הצאצא <JWKS> של הרכיב <PublicKey> אינו בפורמט חוקי כפי שצוין ב-RFC 7517, הפריסה תיכשל.
|
build |
InvalidConfigurationForActionAndAlgorithm |
אם נעשה שימוש ברכיב <PrivateKey> עם אלגוריתמים של Family HS או אם נעשה שימוש באלמנט <SecretKey> עם אלגוריתמים של משפחת RSA, הפריסה תיכשל.
|
build |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה. | fault.name Matches "TokenExpired" |
JWT.failed |
כל כללי המדיניות של JWT מגדירים את אותו משתנה במקרה של כשל. | JWT.failed = true |
דוגמה לשגיאה
לטיפול בשגיאות, השיטה המומלצת היא להעתיק את החלק 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>