מדיניות 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 זמין במאמר חלקים של JWS/JWT.

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

header..signature

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

<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 - (אופציונלי) אחד מהערכים הבאים: מחרוזת (ברירת מחדל), מספר, בוליאני או מפה
• 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> של המדיניות ValidJWS מפרט גם את הכותרת הזו. כל כותרת שמדיניות verificationJWS מוצאת ב-crit שלא מופיעה גם ב-<KnownHeaders> תגרום למדיניות verificationJWS להיכשל.

<DetachContent>

<DetachContent>true|false</DetachContent>

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

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

header.payload.signature

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

header..signature

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

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