מדיניות CREATEJWS

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

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

לקבלת מידע על החלקים של JWS ועל אופן ההצפנה והחתימה שלהם, עיינו ב RFC7515.

וידאו

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

דוגמאות

• ליצור מסמך JWS מצורף חתום עם אלגוריתם HS256
• ליצור JWS נפרד שחתום עם אלגוריתם RS256

יצירת JWS מצורף חתום באמצעות HS256 אלגוריתם

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

קובץ JWS מצורף מכיל את הכותרת, המטען הייעודי (payload) והחתימה המקודדים:

header.payload.signature

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

משתמשים ברכיב <Payload> כדי לציין את המטען הייעודי (payload) של ה-JWS הגולמי ללא הקידוד. בדוגמה הזו, משתנה מכיל את המטען הייעודי (Payload). כשפעולת המדיניות הזו מופעלת, Edge מקודד את הכותרת ואת המטען הייעודי (payload) של ה-JWS ואז מוסיף את החתימה המקודדת כדי לחתום על ה-JWS באופן דיגיטלי.

בהגדרת המדיניות שבהמשך, נוצר JWS ממטען ייעודי (payload) שכלול במשתנה. private.payload

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

יצירה של JWS מנותק החתום באמצעות RS256 אלגוריתם

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

JWS מנותק משמיט את המטען הייעודי (payload) מה-JWS:

header..signature

משתמשים ברכיב <Payload> כדי לציין את המטען הייעודי (payload) של ה-JWS הגולמי ללא הקידוד. כשהמדיניות הזו מופעלת, Edge מקודד את הכותרת ואת המטען הייעודי (payload) של ה-JWS. ואז משתמש בהם כדי ליצור את החתימה המקודדת. עם זאת, ה-JWS שנוצר משמיט את המטען הייעודי (payload). באחריותך להעביר את המטען הייעודי (payload) למדיניות VerifyJWS באמצעות רכיב <DetachedContent> של מדיניות VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

הגדרת הרכיבים העיקריים

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

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

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

חומר עזר של רכיב ליצירת JWS

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

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

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

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

מציינת את אלגוריתם ההצפנה לצורך חתימה על האסימון.

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

הוספת הצמדים הנוספים של שם/ערך להצהרה בכותרת של ה-JWS.

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

• name – (חובה) שם התלונה.
• ref - (אופציונלי) השם של משתנה זרימה. אם השדה הזה קיים, המדיניות תשתמש בערך בתור ההצהרה. אם ציינתם גם מאפיין ref וגם ערך הצהרה מפורש, הערך של הפרמטר ערך מפורש הוא ברירת המחדל, ויש להשתמש בו אם משתנה הזרימה המופנה לא מפוענח.
• type – (אופציונלי) אחת מהאפשרויות: מחרוזת (ברירת מחדל), מספר, ערך בוליאני או מפה
• מערך – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: לא נכון.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

המדיניות מציינת אם ליצור את ה-JWS עם מטען ייעודי (payload) מנותק, <DetachContent>true</DetachContent>, או לא, <DetachContent>false</DetachContent>.

אם מציינים False, ברירת המחדל, ה-JWS שנוצר מופיע בצורה הבאה:

header.payload.signature

אם מציינים True כדי ליצור מטען ייעודי (payload) מנותק, ה-JWS שנוצר משמיט את המטען הייעודי (Payload) והוא מופיע בפורמט הבא:

header..signature

אם משתמשים במטען ייעודי (payload) מנותק, באחריותך להעביר את המטען הייעודי (payload) המקורי שאינו מקודד למדיניות בנושא VerifyJWS. באמצעות הרכיב <DetachedContent> של המדיניות VerifyJWS.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

מציינת איפה למקם את ה-JWS שנוצר באמצעות המדיניות הזו. כברירת מחדל הוא ממוקם משתנה הזרימה jws.POLICYNAME.generated_jws.

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

מציינת את המטען הייעודי (payload) הגולמי של ה-JWS, ללא קידוד. מציינים משתנה שמכיל את המטען הייעודי (payload) או מחרוזת.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

מציינת את מזהה המפתח (ילד) שצריך לכלול בכותרת ה-JWS. שימוש בלבד כשהאלגוריתם הוא RS256/RS384/RS512, PS256/PS384/PS512, או ES256/ES384/ES512.

<PrivateKey/Password>

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

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

<PrivateKey/Value>

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

מציינת מפתח פרטי בקידוד PEM שמשמש לחתימה על ה-JWS. השתמשו במאפיין ref כדי להעביר את במשתנה הזרימה. יש להשתמש רק כאשר האלגוריתם הוא אחד מהערכים RS256/RS384/RS512, PS256/PS384/PS512, או ב-ES256/ES384/ES512.

<SecretKey/Id>

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

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

מציינת את מזהה המפתח (ילד) שצריך לכלול בכותרת ה-JWS של מסמך JWS שנחתם באמצעות HMAC באלגוריתם כלשהו. יש להשתמש באפשרות הזו רק כאשר האלגוריתם הוא אחד מהפרמטרים הבאים: HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

מספקת את המפתח הסודי המשמש לאימות אסימונים או לחתימה עליהם באמצעות אלגוריתם HMAC. שימוש בלבד כשהאלגוריתם הוא אחד משדות HS256/HS384/HS512. שימוש במאפיין ref כדי להעביר את המפתח במשתנה זרימה.

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

משתני זרימה

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

התייחסות לשגיאות

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

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

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

שגיאות בפריסה

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

משתני כשל

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

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

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

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

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