פתרון בעיות באימות JWT

כשבקשה שנשלחת מאפליקציית לקוח ל-API כוללת אסימון JWT‏ (JSON Web Token),‏ Extensible Service Proxy (ESP) מאמת את ה-JWT לפני שהוא שולח את הבקשה אל קצה העורף של ה-API. בדף הזה מוסבר איך לפתור בעיות אם אימות ה-JWT נכשל ו-ESP מחזיר שגיאה בתשובה ללקוח. מידע נוסף על JWT זמין ב-RFC 7519.

שגיאה: 401: Jwt issuer is not configured

מצב כזה יכול לקרות כשפורסים את ESPv2 ב-Cloud Run, והדגל --allow-unauthenticated לא נמצא בפקודה gcloud run deploy. אם לא משתמשים בדגל, אסימון ה-JWT נחטף ומאומת על ידי שרת IAM של בקרת הגישה של Cloud Run ולא על ידי ESPv2. יכול להיות ש-IAM ישתמש במנפיק שונה מזה של ESPv2. </a=">

שגיאה: BAD_FORMAT

כדאי לבדוק את הדברים הבאים:

  • מוודאים ש-JWT מכיל JSON תקין.
  • בודקים שלכותרת ה-JWT יש את השדה "alg" והוא מוגדר לאחד מהערכים הבאים: "RS256",‏ "HS256",‏ "RS384",‏ "HS384",‏ "RS512" או "HS512".
  • בודקים את סוג הנתונים של השדות הבאים (אם הם קיימים) במטען הייעודי של ה-JWT:
    • ההצהרות "iat" (זמן ההנפקה), "exp" (זמן התפוגה) ו-"nbf"(לא לפני) הן מספרים גדולים מ-0 ולא מחרוזות.
    • השדות "sub" (נושא), "iss" (מונפק על ידי) ו"jti" (מזהה JWT) הם מחרוזות.
    • הטענה "aud" (קהל) היא מחרוזת או מערך של מחרוזות.
  • מוודאים שההצהרות הבאות מופיעות במטען הייעודי (payload) של JWT: "sub" (נושא), "iss" (מנפיק) ו-"aud" (קהל).

הנה דוגמה לאסימון JWT מפוענח שתקף:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a"
}

Payload:
{
  "iss": "myservice@myproject.iam.gserviceaccount.com",
  "iat": 1493833746,
  "aud": "myservice.appspot.com",
  "exp": 1493837346,
  "sub": "myservice@myproject.iam.gserviceaccount.com"
}
שגיאה: TIME_CONSTRAINT_FAILURE

משתמשים ב-jwt.io כדי לפענח את ה-JWT ולוודא ש:

  • ההצהרה "exp" (זמן התפוגה) קיימת.
  • ערך הטענה "exp" (זמן התפוגה) הוא תאריך ושעה בעתיד. התאריך והשעה הנוכחיים צריכים להיות לפני תאריך התפוגה והשעה שמופיעים בתביעה "exp".
  • הטענה "nbf" (לא לפני) (אם היא קיימת) היא תאריך ושעה בעבר. התאריך והשעה הנוכחיים צריכים להיות מאוחרים או שווים לתאריך ולשעה שמופיעים בתביעת זכויות היוצרים "nbf".
שגיאה: UNKNOWN

משתמשים ב-jwt.io כדי לפענח את ה-JWT ולוודא ש:

  • אם טענת "iss" (המנפיק) היא כתובת אימייל, טענות "sub" (הנושא) ו-"iss" צריכות להיות זהות. כך אפשר לוודא שיוצרי האימיילים ינפיקו את אסימון ה-JWT בעצמם.

שגיאה: KEY_RETRIEVAL_ERROR

  • צריך לוודא שה-URI של המפתח הציבורי שצוין ב-jwksUri בהערה ApiIssuer נכון ותקין.

שגיאה: Issuer not allowed

  • בודקים שההצהרה "iss" (מנפיק) באסימון JWT תואמת לערך issuer בהערה ApiIssuer.

שגיאה: Audience not allowed

אם ההצהרה "aud" (קהל) באסימון JWT תואמת לשם השירות של Endpoints, אז Cloud Endpoints Frameworks מאמת את הקהל ומתעלם מהערכים שהוגדרו ברכיב audiences בהערה ApiIssuerAudience. לדוגמה, אם שם השירות הוא "myservice.appspot.com", אז JWT עם "aud" שמוגדר ל-"myservice.appspot.com" או ל-"https://myservice.appspot.com" הוא קהל תקף.

אם טענת ה-"aud" לא זהה לשם השירות של Endpoints:

  • בודקים שההצהרה "aud" ב-JWT תואמת לאחד מהערכים ברכיב audiences בהערה ApiIssuerAudience.