המדיניות של CREATEJWT

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

מה

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

וידאו

כדאי לצפות בסרטון קצר כדי ללמוד איך יוצרים אסימון JWT חתום.

דוגמאות

• יוצרים JWT חתום עם אלגוריתם HS256
• יוצרים JWT חתום עם אלגוריתם RS256

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

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

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

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

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <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-edge-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-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

הערך של ההצהרות iat, exp ו-jti הוא עשוי להשתנות.

יצירת JWT חתום עם ה-RS256 אלגוריתם

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

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

<GenerateJWT name="JWT-Generate-RS256">
    <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-edge-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>

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

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

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

מסמך עזר לרכיב ליצירת JWT

בחומר העזר בנושא המדיניות מתוארים הרכיבים והמאפיינים של המדיניות Generate JWT.

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<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> לוקח את המאפיינים הבאים:

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

כשכוללים את הרכיב <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.

<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> לוקח את המאפיינים הבאים:

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

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

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

<CustomClaims>

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

<ExpiresIn>

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

מציינת את משך החיים של ה-JWT באלפיות שנייה, שניות, דקות, שעות או ימים.

<Id>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

יש להגדיר את הערך כ-False אם רוצים שהמדיניות תגרור שגיאה כשמצוין משתנה כלשהו שאליו יש הפניה במדיניות לא ניתן לפתור. יש להגדיר את הערך כ-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>

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

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

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

• 10 שנ'
• 60 דקות
• 12 שע'

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

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

<PrivateKey/Id>

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

or

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

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

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

<Subject>

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

<Subject ref="flow_variable" />

לדוגמה:

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

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

משתני זרימה

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

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

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

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

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

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

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

משתני כשל

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

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

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

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

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