סקירה כללית של מדיניות JWS ו-JWT

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

הנושא הזה מספק מידע כללי על JWT (JSON Web Token) ו-JWS (JSON Web Signature) ומדיניות Apigee JWS/JWT שאולי יעניינו מפתחי proxy של Apigee.

מבוא

בדרך כלל משתמשים ב-JWS וגם ב-JWT כדי לשתף הצהרות או טענות נכונות (assertions) בין תרגום מכונה. המדיניות של JWS/JWT מאפשרת לשרתי proxy של Edge API:

• יצירה של JWT חתום או JWS.
• אימות JWT חתום או JWS והצהרות בתוך ה-JWS/JWT.
• פענוח של JWT חתום או JWS ללא אימות החתימה.

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

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

סרטונים

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

סרטון קצר שבו תמצאו מידע נוסף על המבנה של JWT.

תרחישים לדוגמה

אפשר להשתמש במדיניות של JWS/JWT כדי:

• ליצור JWS/JWT חדש בשרת ה-proxy או בצד היעד של נקודת הקצה של שרת proxy של Edge. עבור לדוגמה, אפשר ליצור תהליך של בקשת proxy שיוצר JWS/JWT ומחזיר אותו ללקוח. לחלופין, אפשר לתכנן שרת proxy כך שיוצר JWS/JWT בתהליך בקשת היעד, וגם מצרף אותו לבקשה שנשלחה ליעד. לאחר מכן התלונות האלה יהיו זמינות להפעלה לשירותים לקצה העורפי כדי להחיל עיבוד אבטחה נוסף.
• אימות וחילוץ של הצהרות מ-JWS/JWT שהתקבלו מבקשות נכנסות של לקוחות, מיעד תשובות משירות, מתשובות למדיניות בנושא יתרונות מרכזיים של שירות או ממקורות אחרים. דפדפן Edge לאמת את החתימה ב-JWS/JWT, אם ה-JWS/JWT נוצר על ידי צד שלישי או על ידי Edge. עצמו, באמצעות אלגוריתמים של RSA או HMAC.
• מפענחים JWS/JWT. פענוח הקוד שימושי במיוחד כשמשתמשים בו בשילוב עם המדיניות לאימות JWS/JWT, כאשר הערך של הצהרה (JWT) או כותרת (JWS/JWT) מתוך ה-JWS/JWT חייב להיות ידוע לפני האימות ה-JWS/JWT.

חלקים של JWS/JWT

מסמך JWS/JWT חתום מקודד מידע בשלושה חלקים ומופרדים בנקודות: הכותרת, המטען הייעודי (payload) חתימה:

header.payload.signature

• המדיניות Create JWS/JWT יוצרת את כל שלושת החלקים.
• המדיניות לאימות JWS/JWT בוחנת את כל שלושת החלקים.
• המדיניות של 'פענוח קוד של JWS/JWT' בודקת את הכותרת והמטען הייעודי (payload) בלבד.

JWS תומך גם בפורמט מנותק שמשמיט את המטען הייעודי (payload) מה-JWS:

header..signature

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

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

• JWT: IETF RFC7519
• JWS: IETF RFC7515

ההבדלים בין JWS לבין JWT

אתם יכולים להשתמש ב-JWT או ב-JWS כדי לשתף הצהרות או טענות נכונות (assertions) בין אפליקציות מקושרות. ההבדל העיקרי בין השניים הוא ייצוג של המטען הייעודי (Payload):

• JWT
  • המטען הייעודי (Payload) הוא תמיד אובייקט JSON
  • המטען הייעודי תמיד מצורף ל-JWT
  • הכותרת typ של האסימון תמיד מוגדרת ל-JWT
• JWS
  • המטען הייעודי (Payload) יכול להיות מיוצג על ידי כל פורמט, כמו אובייקט JSON, זרם של בייטים, רצף octet ואחרים
  • המטען הייעודי (Payload) לא חייב להיות מצורף ל-JWS.

מכיוון שפורמט ה-JWT תמיד משתמש באובייקט JSON כדי לייצג את המטען הייעודי (Payload), מפתח ה-Edge Generate JWT משתמש ואימות שכללי המדיניות של JWT כוללים תמיכה בטיפול בשמות נפוצים של הצהרות רשומות, כמו aud, iss, sub ואחרים. כלומר אפשר להשתמש באלמנטים יוצרים מדיניות JWT כדי להגדיר את ההצהרות האלה במטען הייעודי (payload) ואלמנטים של מדיניות אימות JWT כדי לאמת את הערכים שלהן. לעיון בשמות התביעות הרשומות במפרט של JWT.

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

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

מידע על אלגוריתמים של חתימות

כללי המדיניות של אימות JWS/JWT ו-JWS/JWT Generation תומכים באלגוריתמים RSA, RSASSA-PSS, ECDSA ו-HMAC, באמצעות SHA2 סיכומי ביקורת בעוצמה של 256, 384 או 512. המדיניות של JWS/JWT פענוח קוד פועלת בלי קשר ששימש לחתימה על ה-JWS/JWT.

אלגוריתם HMAC

אלגוריתם HMAC מסתמך על סוד משותף, שנקרא 'מפתח סודי', כדי ליצור את (שנקראת גם חתימה על ה-JWS/JWT) ולצורך אימות החתימה.

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

• HS256: אורך מפתח מינימלי של 32 בייטים
• HS386: אורך מפתח מינימלי של 48 בייטים
• HS512: אורך מפתח מינימלי של 64 בייטים

אלגוריתם RSA

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

אלגוריתם RSASSA-PSS

אלגוריתם RSASSA-PSS הוא עדכון לאלגוריתם ה-RSA. בדומה ל-RSS, גם RSASSA-PSS משתמש ב-RSA זוג מפתחות ציבורי/פרטי בשביל החתימה הקריפטוגרפית. הפורמט של המפתח זהה לפורמט של מפתח ה-RSS. הצד החותם משתמש במפתח פרטי כדי לחתום על ה-JWS/JWT, והצד המאמת משתמש בהתאמה מפתח ציבורי לאימות החתימה ב-JWS/JWT. אין דרישות גודל למפתחות.

אלגוריתם ECDSA

האלגוריתם של Elliptic Curve Digital Signature Algorithm (ECDSA) הוא הצפנה המבוססת על עקומים אליפטיים עם עקומה P-256, P-384 ו-P-521. כשמשתמשים באלגוריתמים של ECDSA, האלגוריתם קובע סוג המפתח הציבורי והמפתח הפרטי שצריך לציין:

אלגוריתם	עקומה	דרישות עיקריות
ES256	P-256	מפתח שנוצר מעקומת P-256 (נקרא גם secp256r1 או prime256v1).
ES384	P-384	מפתח שנוצר מעקומת P-384 (נקרא גם secp384r1)
ES512	P-521	מפתח שנוצר מעקומת P-521 (שנקרא גם secp521r1)

אלגוריתמים להצפנת מפתחות

כללי המדיניות של JWS/JWT תומכים בכל האלגוריתמים להצפנת מפתחות שנתמכים על ידי OpenSSL.

שימוש ב-JSON Web Key Set (JWKS) לאימות JWS/JWT

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

• להשתמש בערך המפתח הציבורי בפועל (שמופיע בדרך כלל במשתנה זרימה), או
• להשתמש במפתח ציבורי שמוקף ב-JWKS.

מידע על JWKS

JWKS הוא מבנה של JSON שמייצג קבוצה של מפתחות אינטרנט מסוג JSON (JWK). JWK הוא נתוני JSON שמייצג מפתח קריפטוגרפי. JWK ו-JWKS מתוארים ב-RFC7517. דוגמאות ל-JKWS זמינות בכתובת נספח א'. דוגמאות לערכות של מפתחות אינטרנט בפורמט JSON

מבנה ה-JWKS

החלק RFC7517 מתאר את רכיבי המפתח של JWKS לכל סוג מפתח, למשל RSA או EC. לדוגמה, בהתאם לסוג המפתח, הפרמטרים האלה יכולים לכלול:

• kty – סוג המפתח, למשל RSA. או EC.
• kid (מזהה המפתח) – יכול להיות כל ערך שרירותי (ללא כפילויות במפתח). הוגדרה). אם ה-JWT הנכנס נושא מזהה מפתח שקיים בקבוצה של JWKS, המדיניות תשתמש במפתח הציבורי הנכון כדי לאמת את החתימה של ה-JWS/JWT.

לפניכם דוגמאות לרכיבים אופציונליים והערכים שלהם:

• alg - אלגוריתם המפתחות. היא חייבת להתאים לאלגוריתם החתימה ב-JWS/JWT.
• use – אם קיים, חייב להיות sig.

ה-JWKS הבאים כוללים את הרכיבים והערכים הנדרשים והם יהיו חוקיים ב-Edge ( https://www.googleapis.com/oauth2/v3/certs):

{  
   "keys":[  
      {  
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

תכנון שרת ה-proxy שלך משתמשים ב-JWKS

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

לדוגמה, נניח שמנפיק חותם על אסימון JWT באמצעות מפתח פרטי. השדה 'מזהה מפתח' מזהה את מפתח ציבורי תואם שישמש לאימות ה-JWT. רשימת המפתחות הציבוריים זמינה בדרך כלל בכתובת נקודת קצה ידועה, למשל: https://www.googleapis.com/oauth2/v3/certs.

זהו הרצף הבסיסי ש-Edge (או כל פלטפורמה שפועלת עם JWKS) צריכה לבצע לעבוד עם JWS/JWT שיש לו JWKS:

1. בודקים את הכותרת JWS/JWT כדי לאתר את מזהה המפתח (ילד).
2. בודקים את כותרת ה-JWS/JWT כדי למצוא את אלגוריתם החתימה (alg), כמו RS256.
3. מאחזרים את רשימת המפתחות והמזהים מה-JWKS של נקודת הקצה הידועה של מנפיק נתון.
4. מחלצים את המפתח הציבורי מרשימת המפתחות עם מזהה המפתח שמצוין בכותרת של ה-JWS/JWT ועם אלגוריתם ההתאמה, אם מפתח ה-JWKS מציין את האלגוריתם.
5. משתמשים במפתח הציבורי הזה כדי לאמת את החתימה ב-JWS/JWT.

בתור מפתחי proxy ל-Edge API, אתם צריכים לבצע את הפעולות הבאות כדי לבצע אימות של JWS/JWT:

1. מאחזרים את רשימת המפתחות והמזהים מנקודת הקצה המוכרת של מנפיק נתון. אפשר צריך להשתמש במדיניות בנושא יתרונות מרכזיים של שירות בשלב הזה.
2. במדיניות לאימות JWS/JWT, צריך לציין את המיקום של ה-JWS/JWT ב<Source>. ואת המטען הייעודי (payload) של ה-JWKS ברכיב <PublicKey/JWKS>. לדוגמה, עבור המדיניות VerifyJWT:

   <VerifyJWT name="JWT-Verify-RS256">
       <Algorithm>RS256</Algorithm>
       <Source>json.jwt</Source>
       <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
       <PublicKey>
           <JWKS ref="public.jwks"/>
       </PublicKey>
       <Subject>apigee-seattle-hatrack-montage</Subject>
       <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
       <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
       <AdditionalClaims>
           <Claim name="show">And now for something completely different.</Claim>    
       </AdditionalClaims>
   </VerifyJWT>
   

המדיניות של אימות JWT כוללת את כל שאר הפרטים:

• אם מפתח עם מזהה מפתח שתואם למזהה המפתח (ילד) שהצהרת עליו ב-JWT לא נמצא ה-JWKS, מדיניות האימות מסוג JWT גורמת לשגיאה ולא מאמתת את ה-JWT.
• אם ה-JWT הנכנס לא כולל מזהה מפתח (kid) בכותרת, המיפוי הזה של אי אפשר להשתמש ב-Keyid-to-verification-key.

כמעצב של שרת proxy, באחריותכם לקבוע את המפתח שבו יש להשתמש. במקרים מסוימים, יכול להיות מפתח קבוע בתוך הקוד.