מדיניות GenerateJWT

מדיניות ניתנת להרחבה

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

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

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

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

אם משתמשים ברכיב <Algorithm>, המדיניות יוצרת JWT חתום.
אם משתמשים ברכיב <Algorithms>, המדיניות יוצרת אסימון JWT מוצפן.

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

יצירת JWT חתום

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

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

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

אלגוריתם HS256

מדיניות לדוגמה שיוצרת אסימון JWT חדש וחותמת עליו באמצעות האלגוריתם HS256. ‫HS256 מסתמך על סוד משותף גם לחתימה וגם לאימות החתימה.

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

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

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

הכותרת של ה-JWT שיתקבל תהיה …

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

… ויהיה לו מטען ייעודי (payload) עם תוכן שדומה לזה:

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-JWT-policy-test",
  "aud" : "fans",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

הערכים של הטענות iat,‏ exp ו-jti יהיו שונים.

אלגוריתם RS256

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

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

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

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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

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

כדי לציין את המפתח שמשמש ליצירת JWT חתום, צריך להשתמש בדיוק באחד מהרכיבים הבאים:

<SecretKey>
<PrivateKey>

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

אלגוריתם	אלמנטים מרכזיים
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey>

אלגוריתם

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

HS{256/384/512}^*

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id ref="secretkey-id">key-1918290</Id>
</SecretKey>

RS/PS/ES{256/384/512}^*

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="privatekey-id">key-1918290</Id>
</PrivateKey>

בדוגמאות שלמעלה, הרכיבים <Password> ו-<Id> הם אופציונליים.

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

יצירת JWT מוצפן

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

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

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

RSA-OAEP-256

בדוגמה הבאה:

המפתח מוצפן באמצעות אלגוריתם RSA-OAEP-256.
התוכן מוצפן באמצעות אלגוריתם A128GCM.

רכיב <PublicKey> מציין את המפתח שמשמש להצפנת מפתח.

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

A128KW

בדוגמה הבאה:

המפתח מוצפן באמצעות אלגוריתם A128KW.
התוכן מוצפן באמצעות אלגוריתם A128GCM.

רכיב <SecretKey> מציין את המפתח שמשמש להצפנת מפתח.

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

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

כדי ליצור JWT מוצפן, צריך להשתמש בדיוק באחד מהרכיבים הבאים כדי לציין את מפתח ההצפנה עבור GenerateJWT:

<PublicKey>
<SecretKey>
<PasswordKey>
<DirectKey>

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

אלגוריתם להצפנת מפתחות	אלמנטים מרכזיים
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> הערה: המפתח צריך להיות מפתח RSA ציבורי.
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> הערה: המפתח חייב להיות מפתח ציבורי של עקומה אליפטית.
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16\|hex\|base64\|base64url" ref="private.directkey"/> </DirectKey>

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

הפניה לרכיב Generate JWT

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

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

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

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

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

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל: `A-Z0-9._\-$ %`. עם זאת, בממשק המשתמש של Apigee יש הגבלות נוספות, כמו הסרה אוטומטית של תווים שהם לא אלפאנומריים. אופציונלי. אפשר להשתמש ברכיב `<displayname></displayname>` כדי להוסיף תווית למדיניות בכלי לעריכת ה-proxy בממשק המשתמש של Apigee, עם שם אחר בשפה טבעית.	לא רלוונטי	חובה
continueOnError	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת.	FALSE	אופציונלי
מופעל	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
אסינכרוני	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

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

ברירת מחדל	לא רלוונטי
נוכחות	אופציונלי. חובה להגדיר את אחד מהמאפיינים הבאים: `<Algorithm>` או `<Algorithms>`.
סוג	String
ערכים אפשריים	‫HS256, ‏ HS384, ‏ HS512, ‏ RS256, ‏ RS384, ‏ RS512, ‏ ES256, ‏ ES384, ‏ ES512, ‏ PS256, ‏ PS384, ‏ PS512

<Algorithms>

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

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

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

ברירת מחדל	לא רלוונטי
אופציונלי. חובה להגדיר את אחד מהמאפיינים הבאים: `<Algorithm>` או `<Algorithms>`.	חובה
סוג	String

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

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

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

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

בטבלה הבאה מפורטים האלגוריתמים הזמינים להצפנת מפתחות.

הערך של `<Key>` (אלגוריתם להצפנת מפתחות הצפנה)	נדרש אלמנט מרכזי
dir	`<DirectKey>`
RSA-OAEP-256	‫`<PublicKey>` (שחייב להיות מפתח RSA ציבורי)
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	‫`<PublicKey>` (שחייב להיות מפתח ציבורי של עקומה אליפטית)

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

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

האלגוריתמים הבאים (סימטריים, מבוססי AES) זמינים להצפנת תוכן:

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

מידע נוסף על כל האלגוריתמים האלה זמין ב-RFC7518.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

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

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

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

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

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

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

‫name – (חובה) שם התלונה.
הערה: אל תשתמשו באף אחד משמות הטענות הרשומים ברכיב הזה. ההצהרות הרשומות מפורטות ב-RFC7519. הם כוללים: iss,‏ sub,‏ aud,‏ iat,‏ exp,‏ nbf ו-jti.
‫ref – (אופציונלי) השם של משתנה של זרימת נתונים. אם המשתנה הזה קיים, המדיניות תשתמש בערך שלו כמאפיין. אם מציינים גם מאפיין ref וגם ערך הצהרה מפורש, ערך ברירת המחדל הוא הערך המפורש, והמערכת משתמשת בו אם משתנה הזרימה שאליו מתבצעת ההפניה לא נפתר.
אזהרה: כשמשתמשים ב-ref עם type=map וכשהמשתנה מכיל קלט לא מהימן (לדוגמה, מכותרות של בקשות או מפרמטרים של שאילתות), תוקף יכול להזריק ביטויי תבנית. לדוגמה, תוקף יכול להשתמש ב-{private.secret} כדי לחלץ מידע אישי רגיש מההקשר של ההודעה. הגנה מפני הסיכון הזה. מידע נוסף זמין במאמר מניעת הזרקת תבניות כשמשתמשים ב-JWS וב-JWT.
‫type – (אופציונלי) אחד מהערכים הבאים: string (ברירת מחדל), number,‏ boolean או map
‫array – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: false.

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

לדוגמה:

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

ה-JWT שנוצר כולל את כל ההצהרות באובייקט ה-JSON.

חשוב לשים לב להתנהגות הבאה כשמשתמשים גם בהפניה למשתנה וגם בערך הצהרה מפורש ברכיב Claim:

‫Apigee לא ייצור תלונה בתנאים הבאים:

אם יש הפניה למשתנה, אבל היא לא נפתרה, ו
אם לא תציינו ערך מפורש (ערך ברירת מחדל), ו
אם מאפיין המדיניות IgnoreUnresolvedVariables הוא true.

אם IgnoreUnresolvedVariables הוא false, מערכת Apigee תציג שגיאה בהתאם לתנאים שלמעלה.

‫Apigee יפיק הצהרה בתנאים הבאים:

אם יש הפניה למשתנה, אבל היא לא נפתרה, ו
אם מציינים ערך מפורש (ערך ברירת מחדל), וגם
אם IgnoreUnresolvedVariables הוא true או 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> תומך בתכונה של החלפת מחרוזות דינמית שנקראת תבניות הודעות כשמגדירים type=map.

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

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

‫name – (חובה) שם התלונה.
הערה: אל תשתמשו באף אחד משמות הטענות הרשומים ברכיב הזה. ההצהרות הרשומות מפורטות ב-RFC7519. הם כוללים: iss,‏ sub,‏ aud,‏ iat,‏ exp,‏ nbf ו-jti.
‫ref – (אופציונלי) השם של משתנה של זרימת נתונים. אם המשתנה הזה קיים, המדיניות תשתמש בערך שלו כמאפיין. אם מציינים גם מאפיין ref וגם ערך הצהרה מפורש, ערך ברירת המחדל הוא הערך המפורש, והמערכת משתמשת בו אם משתנה הזרימה שאליו מתבצעת ההפניה לא נפתר.
אזהרה: כשמשתמשים ב-ref עם type=map וכשהמשתנה מכיל קלט לא מהימן (לדוגמה, מכותרות של בקשות או מפרמטרים של שאילתות), תוקף יכול להזריק ביטויי תבנית. לדוגמה, תוקף יכול להשתמש ב-{private.secret} כדי לחלץ מידע אישי רגיש מההקשר של ההודעה. הגנה מפני הסיכון הזה. מידע נוסף זמין במאמר מניעת הזרקת תבניות כשמשתמשים ב-JWS וב-JWT.
‫type – (אופציונלי) אחד מהערכים הבאים: string (ברירת מחדל), number,‏ boolean או map
‫array – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: false.

<Compress>

<Compress>true</Compress>

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

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

{
  "typ": "...",
  "alg" : "...",
  "crit" : [ "a", "b", "c" ],
}

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

הערה: ה-<CriticalHeaders> לא מוסיף את הכותרות ל-JWT. היא מגדירה רק את התוכן של הכותרת crit. אפשר להשתמש ב<AdditionalHeader/Claims> כדי להוסיף את הכותרות.

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

<CustomClaims>

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

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

מציין מפתח ישיר להצפנת JWT כשהאלגוריתם להצפנה הוא dir ("הצפנה ישירה").

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

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

רכיב צאצא	חובה?	תיאור
מזהה	אופציונלי	מזהה המפתח
ערך	חובה	מציינים הפניה למשתנה באמצעות המאפיין `ref`. התוכן של המשתנה שאליו יש הפניה חייב להיות מחרוזת שמקודדת מערך של בייטים, בקידוד hex (base16),‏ base64 או base64url.

בהצפנה ישירה של מפתחות, אתם יכולים לספק ישירות סדרה של בייטים שישמשו כמפתח להצפנת תוכן (CEK). חובה לציין את מערך הבייטים כמחרוזת מקודדת. האורך הנדרש של מערך הבייטים תלוי בעוצמה של אלגוריתם ההצפנה של התוכן שנבחר. לדוגמה, עבור A256CBC-HS512, צריך לספק מפתח של בדיוק 512 ביט, או 64 בייט.

התוכן של המשתנה private.directkey חייב להיות מחרוזת מקודדת, באמצעות הקסדצימלי (base16),‏ base64 או base64url. לדוגמה, הנה מפתח של 32 בייט שמקודד בפורמט הקסדצימלי:

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

בקידוד הקסדצימלי, רווחים מתקבלים אבל לא נדרשים, ואפשר להשתמש באותיות רישיות או קטנות (B7 זהה ל-b7).

הקידוד המקביל ב-base64url הוא:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

בגרסאות base64* ‎, רווחים לא מתקבלים והאותיות קטנות או גדולות משנות. אם לא מציינים קידוד, המדיניות מניחה שהקידוד הוא base64.

בהמשך מפורטת אורך המפתחות הנדרש:

אלגוריתם להצפנת תוכן	דרישה לגבי אורך המפתח
A128CBC-HS256	‫256 ביטים (32 בייטים)
A192CBC-HS384	‫384 (48)
A256CBC-HS512	‫512 (64)
A128GCM	‫128 (16)
A192GCM	‫192 (24)
A256GCM	‫256 (32)

הערה: אורך מפתח ההצפנה של התוכן שמוגדר באמצעות רכיב <DirectKey> חייב להיות בדיוק האורך הנכון לאלגוריתם ההצפנה של התוכן שצוין. לכל אלגוריתם אחר להצפנת מפתח מלבד dir, המדיניות יוצרת CEK אקראי באורך הנכון, אבל לגבי dir, ההגדרה צריכה לספק מפתח בגודל הנכון באופן מפורש.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

or:

<ExpiresIn ref='time-value-here'/>

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

ברירת מחדל	`N/A`
נוכחות	אופציונלי
סוג	מספר שלם
ערכים אפשריים	ערך או הפניה למשתנה של זרימת נתונים שמכיל את הערך. אפשר לציין את יחידות הזמן באופן הבא: ms = אלפיות שנייה (ברירת מחדל) s = שניות m = minutes h = hours d = days לדוגמה, `ExpiresIn`=10d שווה ל-`ExpiresIn` של 864000s.

<Id>

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

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

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

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

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

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

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

ערכי זמן תקינים לרכיב NotBefore עבור ערכי זמן מוחלטים

שם	אופן הלימוד	דוגמה
ניתן למיון	`yyyy-MM-dd'T'HH:mm:ss.SSSZ`	2017-08-14T11:00:21.269-0700
RFC 1123	`EEE, dd MMM yyyy HH:mm:ss zzz`	‫Mon, 14 Aug 2017 11:00:21 PDT
RFC 850	`EEEE, dd-MMM-yy HH:mm:ss zzz`	יום שני, 14 באוגוסט 2017 בשעה 11:00:21 PDT
ANCI-C	`EEE MMM d HH:mm:ss yyyy`	Mon Aug 14 11:00:21 2017

לערכי זמן יחסיים, מציינים מספר שלם ותקופת זמן, לדוגמה:

‫10 שניות
‫60 מ'
‫12 שעות

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

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

ברירת מחדל	`jwt.POLICYNAME.generated_jwt`
נוכחות	אופציונלי
סוג	מחרוזת (שם של משתנה בתהליך)

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

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

PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW

עבור כל אחד מאלגוריתמי המפתחות האלה, צריך לספק סיסמה שממנה נגזר מפתח הצפנת המפתח, באמצעות המשתנה private.password ברכיב <Value ref="private.password"/>.

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

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

רכיב צאצא	נוכחות	תיאור
מזהה	אופציונלי	מזהה המפתח
ערך	חובה	מציינת את הסיסמה שמשמשת ליצירת המפתח להצפנת מפתחות הצפנה. משתמשים במאפיין `ref` ומציינים משתנה, כמו `private.password` .
SaltLength	אופציונלי	אורך המלח. ברירת מחדל: 8 בייט.
PBKDF2Iterations	אופציונלי	מספר האיטרציות של PBKDF2: ברירת מחדל: 10,000.

<PrivateKey>

<PrivateKey>
  <Id ref="privatekey-id"/>
  <Value ref="private.pem-encoded-privatekey"/>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

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

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

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

רכיב צאצא נוכחות תיאור

מזהה

אופציונלי

רכיב צאצא	נוכחות	תיאור
מזהה	אופציונלי	מזהה המפתח. הערך יכול להיות כל מחרוזת. אפשר לציין את הערך כערך טקסט מילולי, או באופן עקיף, באמצעות הפניה למשתנה, באמצעות המאפיין `ref`. המדיניות תכלול את מזהה המפתח הזה כטענה `kid` בכותרת של ה-JWT שנוצר.
ערך	חובה	מפתח פרטי בקידוד PEM. מציין את המפתח הפרטי שמשמש לחתימה על מטען הייעודי. משתמשים במאפיין `ref` ומציינים משתנה, כמו `private.private-key` . אם הרכיב `<Algorithm>` מכיל וריאציה של RSA, אחת מהאפשרויות RS256/RS384/RS512 או PS256/PS384/PS512, צריך לספק מפתח פרטי של RSA מוצפן. אם רכיב `<Algorithm>` מכיל וריאציה של EC, אחת מהאפשרויות ES256/ES384/ES512, צריך לספק מפתח פרטי של עקומה אליפטית לעקומה המתאימה.
סיסמה	אופציונלי	הסיסמה שבה המדיניות צריכה להשתמש כדי לפענח את המפתח הפרטי, אם יש צורך. משתמשים במאפיין `ref` כדי להעביר את הסיסמה באמצעות משתנה של זרימת עבודה. הערה: צריך לציין משתנה של זרימת נתונים. ‫Apigee ידחה הגדרת מדיניות שבה הסיסמה מצוינת בטקסט לא מוצפן, כי היא לא תקינה. למשתנה של התהליך חייבת להיות הקידומת 'private'. לדוגמה, `private.mypassword`.

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

המדיניות תכלול את מזהה המפתח הזה כטענה kid בכותרת של ה-JWT שנוצר.

ערך

חובה

מפתח פרטי בקידוד PEM. מציין את המפתח הפרטי שמשמש לחתימה על מטען הייעודי. משתמשים במאפיין ref ומציינים משתנה, כמו private.private-key .

אם הרכיב <Algorithm> מכיל וריאציה של RSA, אחת מהאפשרויות RS256/RS384/RS512 או PS256/PS384/PS512, צריך לספק מפתח פרטי של RSA מוצפן. אם רכיב <Algorithm> מכיל וריאציה של EC, אחת מהאפשרויות ES256/ES384/ES512, צריך לספק מפתח פרטי של עקומה אליפטית לעקומה המתאימה.

סיסמה

אופציונלי

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

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

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

מציין את המפתח הציבורי שבו יש להשתמש כשיוצרים JWT מוצפן, ואת Keyהאלגוריתם שהוא וריאציה של RSA או של עקומה אליפטית (EC) – RSA-OAEP-256,‏ ECDH-ES,‏ ECDH-ES+A128KW,‏ ECDH-ES+A192KW או ECDH-ES+A256KW.

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

צריך לציין בדיוק אחד מהערכים Value, Certificate או JWKS. אם מציינים את JWKS, צריך לציין גם את Id. בטבלה הבאה מפורטים רכיבי הצאצא של <PublicKey>:

רכיב צאצא	תיאור
ערך	מפתח ציבורי בקידוד PEM. מציין את המפתח הציבורי שהמדיניות צריכה להשתמש בו כדי להצפין את המפתח להצפנת התוכן. אפשר לציין את המפתח באופן מילולי או באופן עקיף באמצעות הפניה למשתנה. <PublicKey> <Value ref="public.publickey"/> </PublicKey> או <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> המפתח הציבורי המקודד צריך לציין מפתח RSA אם משתמשים באלגוריתם RSA-OAEP-256, או מפתח EC של העקומה המתאימה אם משתמשים באלגוריתם EC.
אישור	אישור X.509 בקידוד PEM, שעוטף מפתח ציבורי. מערכת Apigee תחלץ את המפתח הציבורי מהאישור, ואז תשתמש במפתח הזה כדי להצפין את המפתח להצפנת תוכן. אפשר לציין את האישור באופן מילולי או באופן עקיף באמצעות הפניה למשתנה. <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> או <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> המפתח הציבורי המקודד צריך לציין מפתח RSA אם משתמשים באלגוריתם RSA-OAEP-256, או מפתח EC של העקומה המתאימה אם משתמשים באלגוריתם EC. הערה:‏ Apigee לא מאמת את תאריכי התוקף של האישור שאתם מספקים, ולא מאמת את שרשרת המהימנות של האישור. מערכת Apigee מתייחסת לכל האישורים שאתם מציינים ברכיב הזה כאל אישורים תקפים ומהימנים.
JWKS	מקור JWKS של מפתחות ציבוריים. זו תהיה רשימת מפתחות בפורמט שמתואר ב-IETF RFC 7517 – JSON Web Key (JWK). אפשר לציין את JWKS באחת מארבע דרכים: ממש ככה, כערך טקסט: <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> באופן עקיף, באמצעות המאפיין `ref`, שבו מציינים משתנה של זרימה: <PublicKey> <JWKS ref="variable-containing-jwks-content"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> המשתנה שאליו מתבצעת ההפניה צריך להכיל מחרוזת שמייצגת JWKS. באופן עקיף באמצעות URI סטטי, עם המאפיין `uri`: <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> באופן עקיף באמצעות URI שנקבע באופן דינמי, עם המאפיין `uriRef`: <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> בכל המקרים, כשמציינים רכיב `JWKS` בתוך GenerateJWT כדי ליצור JWT מוצפן, צריך לציין גם את הרכיב `PublicKey/Id`. <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey>
מזהה	מחרוזת שמייצגת את מזהה המפתח. בזמן הריצה, Apigee מאחזר מפתח מ-JWKS שיש לו שדה `kid` שתואם לערך הזה. חובה להשתמש ברכיב `Id` אם משתמשים ברכיב `JWKS` בתוך GenerateJWT.

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

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

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

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

צאצא נוכחות תיאור

קידוד (מאפיין)

אופציונלי

צאצא	נוכחות	תיאור
קידוד (מאפיין)	אופציונלי	מציין איך המפתח מקודד במשתנה שאליו מתבצעת ההפניה. כברירת מחדל, אם לא מצוין מאפיין `encoding`, הקידוד של המפתח נחשב ל-UTF-8. הערכים התקינים של המאפיין הם: hex,‏ base16,‏ base64 או base64url. הערכים hex ו-base16 הם מילים נרדפות. <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> בדוגמה שלמעלה, כשמאפיין הקידוד הוא `hex` והתוכן של המשתנה `private.secretkey` הוא `494c6f766541504973`, המפתח יפוענח כקבוצה של 9 בייטים, שיוצגו בפורמט הקסדצימלי כ-`49 4c 6f 76 65 41 50 49 73`. לעומת זאת, אם מאפיין הקידוד הוא `base64`, והתוכן של המשתנה `private.secretkey` הוא `VGhpcy1pcy1hLXNlY3JldA`, המפתח יפוענח כקבוצה של 16 בייטים, בפורמט הקסדצימלי: `54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74`. הערה: ב-Apigee יש דרישה לחוזק מפתח מינימלי. לפרטים נוספים, אפשר לעיין במסמכי התיעוד של רכיב `Value`.
‫Id (רכיב)	אופציונלי	מזהה המפתח. הערך יכול להיות כל מחרוזת. אפשר לציין את הערך כערך טקסט מילולי, או באופן עקיף, באמצעות הפניה למשתנה, באמצעות המאפיין `ref`. <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> המדיניות תכלול את מזהה המפתח הזה כטענה `kid` בכותרת של ה-JWT שנוצר.
ערך (רכיב)	חובה	מפתח סודי מוצפן. מציין את המפתח הסודי שמשמש לחתימה על מטען הייעודי (payload). אפשר להשתמש במאפיין `ref` כדי לספק את המפתח באופן עקיף באמצעות משתנה, כמו `private.secret-key` . <SecretKey> <Id ref="flow-variable-name-here"/> <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="VALUE_HERE" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.secretkey"/>
</SecretKey>

בדוגמה שלמעלה, כשמאפיין הקידוד הוא hex והתוכן של המשתנה private.secretkey הוא 494c6f766541504973, המפתח יפוענח כקבוצה של 9 בייטים, שיוצגו בפורמט הקסדצימלי כ-49 4c 6f 76 65 41 50 49 73. לעומת זאת, אם מאפיין הקידוד הוא base64, והתוכן של המשתנה private.secretkey הוא VGhpcy1pcy1hLXNlY3JldA, המפתח יפוענח כקבוצה של 16 בייטים, בפורמט הקסדצימלי: 54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74.

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

‫Id (רכיב)

אופציונלי

<SecretKey>
  <Id ref="flow-variable-name-here"/>
 <Value ref="private.variable-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

המדיניות תכלול את מזהה המפתח הזה כטענה kid בכותרת של ה-JWT שנוצר.

ערך (רכיב)

חובה

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

<SecretKey>
 <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

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

<Subject>

‫

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

או

<Subject ref="flow_variable" />

לדוגמה:

<Subject ref="apigee.developer.email"/>

המדיניות יוצרת JWT שמכיל הצהרה מסוג sub, שמוגדרת לערך שצוין.ההצהרה הזו מזהה את הנושא של ה-JWT או מצהירה עליו. זו אחת מהטענות הסטנדרטיות שמוזכרות ב- IETF RFC 7519.

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

<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

המדיניות Generate JWT לא מגדירה משתני זרימה.

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מתרחש כאשר
`steps.jwt.AlgorithmInTokenNotPresentInConfiguration`	`401`	השגיאה מתרחשת כשבמדיניות האימות יש כמה אלגוריתמים.
`steps.jwt.AlgorithmMismatch`	`401`	האלגוריתם שצוין במדיניות Generate לא תאם לזה שצוין במדיניות Verify. האלגוריתמים שצוינו צריכים להיות זהים.
`steps.jwt.EncryptionFailed`	`401`	היצירה של JWT מוצפן נכשלה מסיבה לא ספציפית
`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.InvalidJsonFormat`	`401`	נמצא JSON לא תקין בכותרת או במטען הייעודי (payload).
`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`	מדיניות האימות משתמשת ב-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 לאלגוריתם של עקומות אליפטיות, או מפתח עקומה לאלגוריתם 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`.
`InvalidConfigurationForActionAndAlgorithm`	אם משתמשים באלמנט `<PrivateKey>` עם אלגוריתמים של HS Family או באלמנט `<SecretKey>` עם אלגוריתמים של RSA Family, הפריסה תיכשל.
`InvalidValueForElement`	אם הערך שצוין ברכיב `<Algorithm>` הוא לא ערך נתמך, הפריסה תיכשל.
`MissingConfigurationElement`	השגיאה הזו תתרחש אם לא משתמשים באלמנט `<PrivateKey>` עם אלגוריתמים של משפחת RSA, או אם לא משתמשים באלמנט `<SecretKey>` עם אלגוריתמים של משפחת HS.
`InvalidKeyConfiguration`	אם רכיב הבן `<Value>` לא מוגדר ברכיבים `<PrivateKey>` או `<SecretKey>`, הפריסה תיכשל.
`EmptyElementForKeyConfiguration`	אם מאפיין ההפניה ref של רכיב הבן `<Value>` של הרכיבים `<PrivateKey>` או `<SecretKey>` ריק או לא צוין, הפריסה תיכשל.
`InvalidVariableNameForSecret`	השגיאה הזו מתרחשת אם שם משתנה הזרימה שצוין במאפיין ref של רכיב הבן `<Value>` של הרכיבים `<PrivateKey>` או `<SecretKey>` לא מכיל את הקידומת הפרטית `(private.)`.
`InvalidSecretInConfig`	השגיאה הזו מתרחשת אם רכיב הצאצא `<Value>` של הרכיבים `<PrivateKey>` או `<SecretKey>` לא מכיל את הקידומת הפרטית `(private.)`.
`InvalidTimeFormat`	אם הערך שצוין ברכיב `<NotBefore>` לא משתמש בפורמט נתמך, הפריסה תיכשל.

משתני תקלות

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

משתנים	כאשר:	דוגמה
`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>

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

יצירת JWT חתום

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

אלגוריתם HS256

אלגוריתם RS256

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

יצירת JWT מוצפן

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

RSA-OAEP-256

A128KW

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

הפניה לרכיב Generate JWT

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

<DisplayName>

<Algorithm>

<Algorithms>

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

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

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

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<Compress>

<CriticalHeaders>

<CustomClaims>

<DirectKey>

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

<ExpiresIn>

<Id>

<IgnoreUnresolvedVariables>

<Issuer>

<NotBefore>

<OutputVariable>

<PasswordKey>

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

<PrivateKey>

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

<PublicKey>

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

<SecretKey>

ילדים של <SecretKey>

<Subject>

<Type>

משתני Flow

הפניה לשגיאה

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

שגיאות פריסה

משתני תקלות

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

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

מדיניות GenerateJWT

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

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

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

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

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

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