פתרון בעיות באימות 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 של המפתח הציבורי שצוין בפרמטר השני של האובייקט endpoints.Issuer נכון ותקף.

שגיאה: Issuer not allowed

  • בודקים שההצהרה "iss" (המנפיק) באסימון JWT תואמת לפרמטר הראשון של האובייקט endpoints.Issuer.

שגיאה: Audience not allowed

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

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

  • בודקים שההצהרה "aud" ב-JWT תואמת לאחד מהערכים בארגומנט audiences בדקורטור @endpoints.api.