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 מצורף מכיל את הכותרת, ה-payload והחתימה המקודדים:

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 מנותק, המטען הייעודי מושמט מה-JWS:

header..signature

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

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

משתני זרימה

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