מדיניות VerifyJWT

מדיניות רגילה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

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

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

אימות של JWT חתום

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

דוגמאות ל-JWT חתום

בדוגמאות הבאות אפשר לראות איך מאמתים JWT חתום.

אלגוריתם HS256

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

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

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

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

הגדרת רכיבי המפתח לאימות JWT חתום

הרכיבים הבאים מציינים את המפתח שמשמש לאימות של 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 מוצפן

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

דוגמה ל-JWT מוצפן

בדוגמה הבאה אפשר לראות איך מאמתים אסימון JWT מוצפן (עם <Type> שמוגדר ל-Encrypted), שבו:

  • המפתח מוצפן באמצעות אלגוריתם RSA-OAEP-256.
  • התוכן מוצפן באמצעות אלגוריתם A128GCM.
<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

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

הגדרת רכיבי המפתח לאימות JWT מוצפן

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

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

אלגוריתם אלמנטים מרכזיים
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

הערה: המשתנה שאתם מציינים צריך להיות מפתח פרטי מסוג RSA בפורמט PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

הערה: המשתנה שאתם מציינים צריך להיות מפתח פרטי של עקומה אליפטית בפורמט PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

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

הפניה לרכיב

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

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

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

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

מאפיין תיאור ברירת מחדל נוכחות
name השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל: A-Z0-9._\-$ %. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים.

אופציונלית, אפשר להשתמש ברכיב <displayname></displayname> כדי לתת למדיניות שם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

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

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

 FALSE אופציונלי
מופעל מגדירים את המדיניות למצב true כדי לאכוף אותה.

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

 TRUE אופציונלי
אסינכרוני המאפיין הזה הוצא משימוש. FALSE הוצא משימוש

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>HS256</Algorithm>

מציין את האלגוריתם הקריפטוגרפי שמשמש לאימות האסימון. משתמשים ברכיב <Algorithm> כדי לאמת JWT חתום.

אלגוריתמים מסוג RS*/PS*/ES* משתמשים בזוג מפתחות ציבורי/סודי, ואלגוריתמים מסוג HS* משתמשים בסוד משותף. אפשר לעיין גם במאמר מידע על אלגוריתמים להצפנת חתימות.

אפשר לציין כמה ערכים ולהפריד ביניהם באמצעות פסיקים. לדוגמה, "HS256, HS512" או "RS256, PS256". עם זאת, אי אפשר לשלב אלגוריתמים של HS* עם אלגוריתמים אחרים, או אלגוריתמים של ES* עם אלגוריתמים אחרים, כי הם דורשים סוג מפתח ספציפי. אפשר לשלב בין אלגוריתמים של RS* ו-PS*.

ברירת מחדל לא רלוונטי
נוכחות חובה
סוג מחרוזת של ערכים מופרדים בפסיקים
ערכים אפשריים ‫HS256, ‏ HS384, ‏ HS512, ‏ RS256, ‏ RS384, ‏ RS512, ‏ ES256, ‏ ES384, ‏ ES512, ‏ PS256, ‏ PS384, ‏ PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

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

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

רכיבי צאצא של <Algorithms>

בטבלה הבאה מופיע תיאור כללי של רכיבי הצאצא של <Algorithms>:

רכיב צאצא חובה? תיאור
<Key> חובה מציינת את אלגוריתם ההצפנה של המפתח.
<Content> אופציונלי מציינים את אלגוריתם ההצפנה של התוכן.

האימות ייכשל אם:

  • האלגוריתם שצוין במאפיין alg בכותרת של אסימון ה-JWT המוצפן שונה מאלגוריתם הצפנת המפתח שצוין כאן ברכיב <Key>.
  • המדיניות מציינת רכיב <Content>, והאלגוריתם שצוין במאפיין enc בכותרת של אסימון ה-JWT המוצפן שונה מזה שצוין ברכיב <Content>.

לדוגמה, כדי לאמת JWT מוצפן ולבדוק שאלגוריתם המפתח הוא RSA-OAEP-256 ואלגוריתם התוכן הוא A128GCM:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

לעומת זאת, כדי לאמת JWT מוצפן ולבדוק שאלגוריתם המפתח הוא RSA-OAEP-256, ולא לאכוף אילוץ על אלגוריתם התוכן:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

אלגוריתמים להצפנת מפתחות

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

הערך של <Key> (אלגוריתם להצפנת מפתחות הצפנה) המרכיב העיקרי שנדרש לאימות
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

במאמר אימות של JWT מוצפן יש דוגמה שבה אלגוריתם הצפנת המפתח הוא RSA-OAEP-256, ולכן משתמשים ברכיב <PrivateKey>.

אלגוריתמים להצפנת תוכן

במדיניות VerifyJWT לא נדרש לציין אלגוריתם להצפנת תוכן. אם רוצים לציין את האלגוריתם שמשמש להצפנת תוכן, צריך לעשות זאת באמצעות האלמנט הבן<Content> של האלמנט<Algorithms>.

ללא קשר לאלגוריתם הצפנת המפתח, האלגוריתמים הבאים – כולם סימטריים ומבוססים על AES – נתמכים להצפנת תוכן:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

<Audience>

<Audience>audience-here</Audience>

or:

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

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

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

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

ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג מחרוזת, מספר, ערך בוליאני או מפה
מערך מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: ‫false
ערכים אפשריים כל ערך שרוצים להשתמש בו לטענה נוספת.

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

ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג

מחרוזת (ברירת מחדל), מספר, ערך בוליאני או מפה.

אם לא מציינים סוג, ברירת המחדל היא String.
מערך מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: ‫false
ערכים אפשריים כל ערך שרוצים להשתמש בו לטענה נוספת.

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

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

<CustomClaims>

הערה: בשלב הזה, רכיב CustomClaims מוכנס כשמוסיפים מדיניות GenerateJWT חדשה דרך ממשק המשתמש. האלמנט הזה לא פונקציונלי והמערכת מתעלמת ממנו. במקום זאת, צריך להשתמש ברכיב הנכון <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 היא אם אתם נמצאים בסביבת בדיקה ועדיין לא מוכנים לטפל בכשל בכותרת חסרה.

ברירת מחדל FALSE
נוכחות אופציונלי
סוג בוליאני
ערכים אפשריים נכון או לא נכון

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

ברירת מחדל FALSE
נוכחות אופציונלי
סוג בוליאני
ערכים אפשריים נכון או לא נכון

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

ברירת מחדל FALSE
נוכחות אופציונלי
סוג בוליאני
ערכים אפשריים נכון או לא נכון

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

המדיניות בודקת שהנפקן ב-JWT (ההצהרה iss) תואם למחרוזת שצוינה ברכיב ההגדרה. הטענה iss היא אחת מהטענות הרשומות שמוזכרות ב-IETF RFC 7519.

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

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

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

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

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

  • ‫s - שניות
  • m - דקות
  • h - hours
  • ‫d עד ימים
  • w - שבועות

לדוגמה, אפשר לציין אחד מהערכים הבאים: ‎120s, ‏ ‎10m, ‏ ‎1h, ‏ ‎7d, ‏ ‎3w.

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

אפשר להגדיר את מאפיין האופציונלי useIssueTime לערך true כדי להשתמש בערך iat במקום בערך nbf כשמחשבים את משך החיים של הטוקן.

השימוש ברכיב MaxLifespan הוא אופציונלי. אם משתמשים ברכיב הזה, אפשר להשתמש בו רק פעם אחת.

<PrivateKey>

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

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

צאצא של הרכיב <PrivateKey>. מציינת את הסיסמה שבה המדיניות צריכה להשתמש כדי לפענח את המפתח הפרטי, אם יש צורך בכך, כשמאמתים JWT מוצפן. משתמשים במאפיין ref כדי להעביר את הסיסמה במשתנה של זרימת נתונים.

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

הערה: צריך לציין משתנה של זרימת נתונים. ‫Apigee ידחה הגדרת מדיניות שבה הסיסמה מצוינת בטקסט רגיל, כי היא לא תקינה. למשתנה של התהליך חייבת להיות הקידומת 'private'. לדוגמה, private.mypassword.

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

רכיב צאצא של הרכיב <PrivateKey>. מציין מפתח פרטי בקידוד PEM שהמדיניות תשתמש בו כדי לאמת JWT מוצפן. משתמשים במאפיין ref כדי להעביר את המפתח במשתנה של זרימת נתונים.

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

הערה: למשתנה של זרימת הנתונים צריך להיות הקידומת 'private'. לדוגמה, private.mykey

<PublicKey>

מציינת את המקור של המפתח הציבורי שמשמש לאימות JWT שנחתם באמצעות אלגוריתם אסימטרי. האלגוריתמים הנתמכים כוללים את RS256/RS384/RS512,‏ PS256/PS384/PS512 או ES256/ES384/ES512. בהמשך מופיע תיאור של רכיבי הצאצא האפשריים.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

רכיב צאצא של הרכיב <PublicKey>. מציין את האישור החתום שמשמש כמקור של המפתח הציבורי. משתמשים במאפיין ref כדי להעביר את האישור החתום במשתנה של זרימת העבודה, או מציינים את האישור בקידוד PEM ישירות. חשוב לוודא שנתוני האישור בצד ימין מיושרים כמו בדוגמה שמופיעה כאן.

ברירת מחדל לא רלוונטי
נוכחות זה שינוי אופציונלי. כדי לאמת JWT שנחתם באמצעות אלגוריתם אסימטרי, צריך להשתמש ברכיב <Certificate>, <JWKS> או <Value> כדי לספק את המפתח הציבורי.
סוג String
ערכים אפשריים משתנה או מחרוזת של זרימת נתונים.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

רכיב צאצא של הרכיב <PublicKey>. הגדרה של JWKS כמקור של מפתחות ציבוריים. זו תהיה רשימת מפתחות בפורמט שמתואר ב-IETF RFC 7517 – JSON Web Key (JWK).

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

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

ברירת מחדל לא רלוונטי
נוכחות זה שינוי אופציונלי. כדי לאמת JWT שנחתם באמצעות אלגוריתם אסימטרי, צריך להשתמש ברכיב <Certificate>, <JWKS> או <Value> כדי לספק את המפתח הציבורי.
סוג String
ערכים אפשריים

אפשר לציין את JWKS באחת מארבע דרכים:

  • פשוטו כמשמעו, כערך טקסט:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • באופן עקיף, באמצעות המאפיין ref, ציון משתנה זרימה:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    המשתנה שאליו מתבצעת ההפניה צריך להכיל מחרוזת שמייצגת JWKS.

  • באופן עקיף דרך URI סטטי, עם המאפיין uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • באופן עקיף באמצעות URI שנקבע באופן דינמי, עם המאפיין uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

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

ברירת מחדל לא רלוונטי
נוכחות זה שינוי אופציונלי. כדי לאמת JWT שנחתם באמצעות אלגוריתם אסימטרי, צריך להשתמש ברכיב <Certificate>, <JWKS> או <Value> כדי לספק את המפתח הציבורי.
סוג String
ערכים אפשריים משתנה או מחרוזת של זרימת נתונים.

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

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

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

<SecretKey>

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

האלמנט SecretKey הוא אופציונלי. הוא מציין את המפתח הסודי שבו יש להשתמש כשמאמתים JWT חתום שמשתמש באלגוריתם סימטרי (HS*) או כשמאמתים JWT מוצפן שמשתמש באלגוריתם סימטרי (AES) להצפנת מפתח.

ילדים של <SecretKey>

בטבלה הבאה מפורטים מאפייני הצאצא של <SecretKey>:

צאצא נוכחות תיאור
קידוד (מאפיין) אופציונלי

מציין איך המפתח מקודד במשתנה שאליו מתבצעת ההפניה. כברירת מחדל, אם לא מופיע מאפיין encoding, הקידוד של המפתח נחשב ל-UTF-8. הערכים התקינים של המאפיין הם: hex,‏ base16,‏ base64 או base64url. הערכים hex ו-base16 הם מילים נרדפות.

<SecretKey encoding="hex" >
  <Value ref="private.secretkey"/>
</SecretKey>

בדוגמה שלמעלה, מכיוון שהקידוד הוא hex, אם התוכן של המשתנה private.secretkey הוא 494c6f766541504973, המפתח יפוענח כקבוצה של 9 בייטים, שיוצגו בפורמט הקסדצימלי 49 4c 6f 76 65 41 50 49 73.

ערך (רכיב) חובה

מפתח סודי מוצפן. מציינת את המפתח הסודי שישמש לאימות המטען הייעודי (payload). אפשר להשתמש במאפיין ref כדי לספק את המפתח באופן עקיף באמצעות משתנה, כמו private.secret-key .

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

מערכת Apigee אוכפת חוזק מינימלי של מפתח לאלגוריתמים HS256/HS384/HS512. אורך המפתח המינימלי ל-HS256 הוא 32 בייטים, ל-HS384 הוא 48 בייטים ול-HS512 הוא 64 בייטים. שימוש במפתח עם חוזק נמוך יותר גורם לשגיאת זמן ריצה.

<Source>

<Source>jwt-variable</Source>

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

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

כברירת מחדל, כשאין רכיב <Source>, המדיניות מאחזרת את אסימון ה-JWT על ידי קריאת המשתנה request.header.authorization והסרת הקידומת Bearer. אם מעבירים את ה-JWT בכותרת Authorization בתור טוקן מסוג Bearer (עם הקידומת Bearer), לא מציינים את הרכיב <Source> בהגדרת המדיניות. לדוגמה, לא תשתמשו ברכיב <Source> בהגדרת המדיניות אם תעבירו את ה-JWT בכותרת Authorization כך:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
ברירת מחדל request.header.authorization (מידע חשוב על ברירת המחדל מופיע בהערה שלמעלה).
נוכחות אופציונלי
סוג String
ערכים אפשריים שם של משתנה בתהליך עבודה ב-Apigee.

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

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

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

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

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

ברירת מחדל 0 שניות (אין תקופת חסד)
נוכחות אופציונלי
סוג String
ערכים אפשריים ביטוי של טווח זמן או הפניה למשתנה של זרימת עבודה שמכיל ביטוי. אפשר לציין טווחי זמן באמצעות מספר שלם חיובי שאחריו תו אחד שמציין יחידת זמן, באופן הבא:
  • s = שניות
  • m = minutes
  • h = hours
  • d = days

<Type>

<Type>type-string-here</Type>

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

  • אם רכיב <Type> קיים:
    • אם הערך של <Type> הוא Signed, המדיניות מאמתת JWT חתום, ורכיב <Algorithm> חייב להיות קיים.
    • אם הערך של <Type> הוא Encrypted, המדיניות מאמתת JWT מוצפן, והרכיב <Algorithms> חייב להיות קיים.
  • אם רכיב <Type> לא מופיע:
    • אם הרכיב <Algorithm> קיים, המדיניות מניחה שהערך של <Type> הוא Signed.
    • אם הרכיב <Algorithms> קיים, המדיניות מניחה ש-<Type> הוא Encrypted.
  • אם אף אחד מהפרמטרים <Algorithm> ו-<Algorithms> לא מופיע, ההגדרה לא תקינה.
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג String
ערכים אפשריים Signed או Encrypted

משתני Flow

אם הפעולה מצליחה, כללי המדיניות Verify JWT ו-Decode 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 הערך של כותרת במטען הייעודי (payload) שאפשר לנתח ב-JSON. משתנה אחד מוגדר לכל כותרת במטען הייעודי (payload). אפשר גם להשתמש במשתני הזרימה header.name, אבל מומלץ להשתמש במשתנה הזה כדי לגשת לכותרת.
expiry_formatted תאריך ושעת התפוגה, בפורמט של מחרוזת שאנשים יכולים לקרוא. דוגמה: 2017-09-28T21:30:45.000+0000
header.algorithm אלגוריתם החתימה שבו נעשה שימוש ב-JWT. לדוגמה, RS256,‏ HS384 וכן הלאה. מידע נוסף זמין במאמר פרמטר הכותרת(אלגוריתם).
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, המשתנה הזה לא מוגדר.

הפניה לשגיאה

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

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

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

קוד תקלה סטטוס HTTP מתרחש כאשר
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 השגיאה מתרחשת כשבמדיניות האימות יש כמה אלגוריתמים.
steps.jwt.AlgorithmMismatch 401 האלגוריתם שצוין במדיניות Generate לא תאם לזה שצוין במדיניות Verify. האלגוריתמים שצוינו צריכים להיות זהים.
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.InvalidConfiguration 401 האלמנטים <Algorithm> ו-<Algorithms> קיימים.
steps.jwt.InvalidCurve 401 העקומה שצוינה על ידי המפתח לא תקפה לאלגוריתם של עקומה אליפטית.
steps.jwt.InvalidIterationCount 401 מספר האיטרציות ששימש ב-JWT המוצפן לא שווה למספר האיטרציות שצוין בהגדרת המדיניות VerifyJWT. ההגדרה הזו חלה רק על JWT שנעשה בהם שימוש ב-<PasswordKey>.
steps.jwt.InvalidJsonFormat 401 נמצא JSON לא תקין בכותרת או במטען הייעודי (payload).
steps.jwt.InvalidKeyConfiguration 401 הערך JWKS ברכיב <PublicKey> לא תקין. יכול להיות שהסיבה לכך היא שלא ניתן להגיע לנקודת הקצה של ה-URI של ה-JWKS ממופע Apigee. בודקים את הקישוריות לנקודת הקצה על ידי יצירת פרוקסי passthrough ושימוש בנקודת הקצה של JWKS כיעד.
steps.jwt.InvalidSaltLength 401 אורך המלח ששימש ב-JWT המוצפן לא שווה לאורך המלח שצוין בהגדרת המדיניות VerifyJWT. ההגדרה הזו חלה רק על JWT שנעשה בהם שימוש ב-<PasswordKey>.
steps.jwt.InvalidPasswordKey 401 המפתח שצוין לא עמד בדרישות.
steps.jwt.InvalidPrivateKey 401 המפתח שצוין לא עמד בדרישות.
steps.jwt.InvalidPublicKey 401 המפתח שצוין לא עמד בדרישות.
steps.jwt.InvalidSecretKey 401 המפתח שצוין לא עמד בדרישות.
steps.jwt.InvalidToken 401 השגיאה הזו מתרחשת כשאימות החתימה של ה-JWT נכשל.
steps.jwt.JwtAudienceMismatch 401 הטענה לגבי הקהל נכשלה באימות הטוקן.
steps.jwt.JwtIssuerMismatch 401 האימות של הטוקן נכשל בגלל טענת המנפיק.
steps.jwt.JwtSubjectMismatch 401 הטענה בנושא נכשלה באימות הטוקן.
steps.jwt.KeyIdMissing 401 המדיניות Verify משתמשת ב-JWKS כמקור למפתחות ציבוריים, אבל ה-JWT החתום לא כולל את המאפיין kid בכותרת.
steps.jwt.KeyParsingFailed 401 לא הייתה אפשרות לנתח את המפתח הציבורי מפרטי המפתח שצוינו.
steps.jwt.NoAlgorithmFoundInHeader 401 השגיאה מתרחשת כש-JWT לא מכיל כותרת אלגוריתם.
steps.jwt.NoMatchingPublicKey 401 מדיניות Verify משתמשת ב-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 לאלגוריתם של עקומות אליפטיות, או מפתח עקומה לאלגוריתם RSA.

שגיאות פריסה

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

שם השגיאה מטרה תיקון
InvalidNameForAdditionalClaim הפריסה תיכשל אם התביעה שמשמשת ברכיב הצאצא <Claim> של הרכיב <AdditionalClaims> היא אחת מהשמות הרשומים הבאים: kid, ‏iss, ‏sub, ‏aud, ‏iat, ‏exp, ‏nbf או jti.
InvalidTypeForAdditionalClaim אם התביעה שנעשה בה שימוש ברכיב הבן <Claim> של הרכיב <AdditionalClaims> היא לא מסוג string, number, boolean או map, הפריסה תיכשל.
MissingNameForAdditionalClaim אם השם של התביעה לא מצוין ברכיב הצאצא <Claim> של הרכיב <AdditionalClaims>, הפריסה תיכשל.
InvalidNameForAdditionalHeader השגיאה הזו מתרחשת כששם הטענה שמשמש ברכיב הצאצא <Claim> של הרכיב <AdditionalClaims> הוא alg או typ.
InvalidTypeForAdditionalHeader אם סוג הטענה שמשמש ברכיב הבן <Claim> של הרכיב <AdditionalClaims> הוא לא מהסוגים string, number, boolean או map, הפריסה תיכשל.
InvalidValueOfArrayAttribute השגיאה הזו מתרחשת כשערך מאפיין המערך ברכיב הצאצא <Claim> של הרכיב <AdditionalClaims> לא מוגדר כ-true או כ-false.
InvalidValueForElement אם הערך שצוין ברכיב <Algorithm> הוא לא ערך נתמך, הפריסה תיכשל.
MissingConfigurationElement השגיאה הזו תתרחש אם לא משתמשים באלמנט <PrivateKey> עם אלגוריתמים של משפחת RSA, או אם לא משתמשים באלמנט <SecretKey> עם אלגוריתמים של משפחת HS.
InvalidKeyConfiguration אם רכיב הבן <Value> לא מוגדר ברכיבים <PrivateKey> או <SecretKey>, הפריסה תיכשל.
EmptyElementForKeyConfiguration אם מאפיין ההפניה ref של רכיב הבן <Value> של הרכיבים <PrivateKey> או <SecretKey> ריק או לא צוין, הפריסה תיכשל.
InvalidConfigurationForVerify השגיאה הזו מתרחשת אם האלמנט <Id> מוגדר בתוך האלמנט <SecretKey>.
InvalidEmptyElement השגיאה הזו מתרחשת אם הרכיב <Source> של מדיניות Verify JWT ריק. אם הוא קיים, צריך להגדיר אותו עם שם משתנה של Apigee flow.
InvalidPublicKeyValue אם הערך שמשמש ברכיב הצאצא <JWKS> של הרכיב <PublicKey> לא תואם לפורמט התקין שמוגדר ב-RFC 7517, הפריסה תיכשל.
InvalidConfigurationForActionAndAlgorithm אם משתמשים באלמנט <PrivateKey> עם אלגוריתמים של HS Family או באלמנט <SecretKey> עם אלגוריתמים של RSA Family, הפריסה תיכשל.

משתני תקלות

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

משתנים כאשר: דוגמה
fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name Matches "InvalidToken"
JWT.failed כל כללי המדיניות של JWT מגדירים את אותו משתנה במקרה של כשל. JWT.failed = true

דוגמה לתגובת שגיאה

קודי תקלות של מדיניות JWT

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

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

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