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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

מבוא

JWS ו-JWT משמשים בדרך כלל לשיתוף טענות או טענות נכונות בין אפליקציות מקושרות. מדיניות 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

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

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

header..signature

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

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

• JWT: IETF RFC7519
• JWS: IETF RFC7515

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

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

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

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

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

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

   <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' עושה את כל השאר:

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

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