GenerateJWS policy

אתם קוראים את מאמרי העזרה של Apigee Edge.
אפשר לעיין במסמכי התיעוד של Apigee X. מידע

מה

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

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

וידאו

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

דוגמאות

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

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

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

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

header.payload.signature

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

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

הפניה לרכיב של Generate JWS

ההפניה למדיניות מתארת את האלמנטים והמאפיינים של מדיניות Generate 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 – (אופציונלי) אחד מהערכים הבאים: string (ברירת מחדל), number,‏ boolean או map
• ‫array – (אופציונלי) מגדירים את הערך true כדי לציין אם הערך הוא מערך של סוגים. ברירת מחדל: ‫false.

<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 כדי ליצור מטען ייעודי מנותק, מטען הייעודי לא נכלל ב-JWS שנוצר והוא בפורמט הבא:

header..signature

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

מציין את מזהה המפתח (kid) שייכלל בכותרת ה-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>

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

משתני Flow

המדיניות 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>