Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫VerifyJWT policy

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

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

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

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

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

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

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

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

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

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

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

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

<SecretKey>
<PublicKey>

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

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

אלגוריתם

אלמנטים מרכזיים

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 מוצפן:

<PrivateKey>
<SecretKey>
<PasswordKey>
<DirectKey>

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

אלגוריתם	אלמנטים מרכזיים
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>

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

הפניה לרכיב

הפניה למדיניות מתארת את האלמנטים והמאפיינים של מדיניות Verify 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* משתמשים בסוד משותף. אפשר לעיין גם במאמר מידע על אלגוריתמים להצפנת חתימות.

הערה: צריך להשתמש רק באחד מהאלמנטים <Algorithm> ו-<Algorithms>.

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

הערה: צריך להשתמש בדיוק באחד מהרכיבים <Algorithm> ו-<Algorithms>.

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

האלמנט <Claim> תומך בתכונה של החלפת מחרוזות דינמיות שנקראת תבניות הודעות.

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

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

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

‫name – (חובה) שם התלונה.
הערה: אסור להשתמש באף אחד משמות התביעות הרשומים ברכיב הזה. התביעות הרשומות מפורטות ב-RFC7519. הם כוללים את: iss,‏ sub,‏ aud,‏ iat,‏ exp,‏ nbf ו-jti.
‫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 מכילה את צמדי המפתח/ערך הנוספים שצוינו, ושערכי ההצהרות שצוינו תואמים.

האלמנט <Claim> תומך בתכונה של החלפת מחרוזות דינמיות שנקראת תבניות הודעות.

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

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

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

‫name – (חובה) שם התלונה.
הערה: אסור להשתמש באף אחד משמות התביעות הרשומים ברכיב הזה. התביעות הרשומות מפורטות ב-RFC7519. הם כוללים את: iss,‏ sub,‏ aud,‏ iat,‏ exp,‏ nbf ו-jti.
‫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 היא אם אתם נמצאים בסביבת בדיקה ועדיין לא מוכנים לטפל בכשל בכותרת חסרה.

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

ברירת מחדל	FALSE
נוכחות	אופציונלי
סוג	בוליאני
ערכים אפשריים	true or 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.

הערה: המדיניות VerifyJWT לא מטפלת בפועל בכותרות שמופיעות ברשימה של רכיב <KnownHeaders>, ולא מעבדת אותן. הטיפול בכותרות האלה נשאר למועד מאוחר יותר בשרת הפרוקסי או בשרת העורפי.

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

<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 - שעות
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`. הערה: ב-Apigee יש דרישה לחוזק מינימלי של מפתחות. פרטים נוספים מופיעים במסמכי העזרה בנושא רכיב `Value`.
ערך (רכיב)	חובה	מפתח סודי מקודד. מציינת את המפתח הסודי שישמש לאימות המטען הייעודי (payload). משתמשים במאפיין `ref` כדי לספק את המפתח באופן עקיף באמצעות משתנה, כמו `private.secret-key` . <SecretKey> <Value ref="private.my-secret-variable"/> </SecretKey> הערה: שם המשתנה צריך לכלול את התחילית private כמו בדוגמה שלמעלה. ‫Apigee אוכף חוזק מפתח מינימלי לאלגוריתמים HS256/HS384/HS512. אורך המפתח המינימלי עבור HS256 הוא 32 בייטים, עבור HS384 הוא 48 בייטים ועבור HS512 הוא 64 בייטים. שימוש במפתח חלש יותר גורם לשגיאת זמן ריצה.

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

הערה: ב-Apigee יש דרישה לחוזק מינימלי של מפתחות. פרטים נוספים מופיעים במסמכי העזרה בנושא רכיב Value.

ערך (רכיב)

חובה

מפתח סודי מקודד. מציינת את המפתח הסודי שישמש לאימות המטען הייעודי (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`

משתנים בתהליך

אם הפעולה מצליחה, מדיניות 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`	תאריך ושעת התפוגה, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
`claim.issuedat`	התאריך שבו הונפק האסימון, באלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
`claim.issuer`	הצהרת המנפיק של JWT.
`claim.notbefore`	אם ה-JWT כולל טענת nbf, המשתנה הזה יכיל את הערך, שמבוטא באלפיות השנייה מאז תקופת ה-epoch.
`claim.subject`	הצהרת הנושא של JWT.
`claim.name`	הערך של הטענה עם השם (רגילה או נוספת) במטען הייעודי (payload). אחד מהערכים האלה יוגדר לכל טענה במטען הייעודי.
`decoded.claim.name`	הערך שניתן לניתוח באמצעות JSON של ההצהרה שצוין השם שלה (סטנדרטית או נוספת) במטען הייעודי (payload). משתנה אחד מוגדר לכל הצהרה במטען הייעודי. לדוגמה, אפשר להשתמש ב-`decoded.claim.iat` כדי לאחזר את השעה שבה הונפק JWT, בפורמט של שניות מאז תקופת האפוק. אפשר גם להשתמש במשתני זרימת העבודה `claim.name`, אבל מומלץ להשתמש במשתנה הזה כדי לגשת להצהרה.
`decoded.header.name`	הערך שניתן לניתוח ב-JSON של כותרת במטען הייעודי (payload). משתנה אחד מוגדר לכל כותרת במטען הייעודי (payload). אפשר גם להשתמש במשתני הזרימה `header.name`, אבל המשתנה המומלץ לגישה לכותרת הוא
`expiry_formatted`	תאריך ושעת התפוגה, בפורמט של מחרוזת שקריאה לאנשים. דוגמה: 2017-09-28T21:30:45.000+0000
`header.algorithm`	אלגוריתם החתימה שבו נעשה שימוש ב-JWT. לדוגמה, RS256,‏ HS384 וכן הלאה. מידע נוסף זמין במאמר בנושא פרמטר הכותרת(אלגוריתם).
`header.kid`	מזהה המפתח, אם הוא נוסף כשנוצר ה-JWT. אפשר גם לעיין בקטע 'שימוש בקבוצת מפתחות אינטרנט בפורמט JSON‏ (JWKS)' במאמר סקירה כללית של מדיניות JWT כדי לאמת JWT. מידע נוסף זמין במאמר פרמטר הכותרת(מזהה המפתח).
`header.type`	הערך יהיה `JWT`.
`header.name`	הערך של הכותרת עם השם (רגילה או נוספת). אחד מהם יוגדר לכל כותרת נוספת בחלק הכותרת של ה-JWT.
`header-json`	הכותרת בפורמט JSON.
`is_expired`	true or false
`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`	כותרת שנמצאה על ידי מדיניות Verify 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>` של מדיניות האימות של JWT ריק. אם הוא קיים, צריך להגדיר אותו עם שם משתנה של תהליך Apigee.
`InvalidPublicKeyValue`	אם הערך שמשמש ברכיב הצאצא `<JWKS>` של הרכיב `<PublicKey>` לא תואם לפורמט תקין שמוגדר ב-RFC 7517, הפריסה תיכשל.
`InvalidConfigurationForActionAndAlgorithm`	אם משתמשים באלמנט `<PrivateKey>` עם אלגוריתמים של HS Family או באלמנט `<SecretKey>` עם אלגוריתמים של RSA Family, הפריסה תיכשל.

משתני תקלות

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

משתנים	כאשר:	דוגמה
`fault.name="fault_name"`	‫`fault_name` הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`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>

‫VerifyJWT policy קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

אלגוריתם HS256

אלגוריתם RS256

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

אימות של JWT מוצפן

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

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

הפניה לרכיב

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

<DisplayName>

<Algorithm>

<Algorithms>

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

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

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

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<CustomClaims>

<Id>

<IgnoreCriticalHeaders>

<IgnoreIssuedAt>

<IgnoreUnresolvedVariables>

<Issuer>

<KnownHeaders>

<MaxLifespan>

<PrivateKey>

<Password>

<Value>

<PublicKey>

<Certificate>

<JWKS>

<Value>

<RequiredClaims>

<SecretKey>

ילדים של <SecretKey>

<Source>

<Subject>

<TimeAllowance>

<Type>

משתנים בתהליך

הפניה לשגיאה

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

שגיאות בהטמעה

משתני תקלות

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

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

‫VerifyJWT policy

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

ילדים של `<SecretKey>`