‫GenerateJWT policy

אתם צופים במסמכי התיעוד של 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>

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

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

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

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

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

הערה: בשלב הזה, כשמוסיפים מדיניות GenerateJWT חדשה דרך ממשק המשתמש, מוכנס רכיב CustomClaims. האלמנט הזה לא פונקציונלי והמערכת מתעלמת ממנו. במקום זאת, צריך להשתמש ברכיב הנכון <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 הספציפית. אם ערך הטקסט ומאפיין ההפניה ריקים, המדיניות תיצור jti שמכיל UUID אקראי. המאפיין של מזהה ה-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>

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

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