שימוש ב-JWT לאימות משתמשים

בדף הזה מוסבר איך לתמוך באימות משתמשים ב-API Gateway.

כדי לאמת משתמש, אפליקציית לקוח צריכה לשלוח אסימון אינטרנט מסוג JSON‏ (JWT) בכותרת ההרשאה של בקשת ה-HTTP אל ה-API של הבק-אנד. ‫API Gateway מאמת את הטוקן בשם ה-API שלכם, כך שלא צריך להוסיף קוד ל-API כדי לעבד את האימות. עם זאת, צריך להגדיר את תצורת ה-API של השער כדי לתמוך בשיטות האימות שבחרתם.

‫API Gateway מאמת JWT בצורה יעילה באמצעות JSON Web Key Set (JWKS) של מנפיק ה-JWT. המיקום של JWKS מצוין בהגדרות ה-API של השער. ה-JWKS נשמר במטמון של API Gateway למשך חמש דקות ומתעדכן כל חמש דקות.

לפני שמתחילים

  • מוסיפים קוד אימות לאפליקציית הלקוח, בהתאם לתיעוד של ספק האימות.

  • כשיישום הלקוח שולח בקשת HTTP, כותרת ההרשאה בבקשה חייבת להכיל את הטענות הבאות של JWT:
    • iss (מנפיק)
    • sub (נושא)
    • aud (קהל)
    • iat (הונפק ב-)
    • exp (תאריך התפוגה)

הגדרת API Gateway לתמיכה באימות לקוח

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

כדי לתמוך באימות JWT:

OpenAPI 2.0

  1. מוסיפים את ההגדרות הבאות להגדרות ה-API: 
    securityDefinitions:
  your_custom_auth_id:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # The issuer value should be unique
    x-google-issuer: "ISSUER"
    x-google-jwks_uri: "URL_PUBLIC_KEY"
    # Optional.
    x-google-audiences: "CLIENT_ID"

    כאשר:

    • ‫ISSUER הוא המנפיק של האסימון.
    • ‫URL_PUBLIC_KEY היא כתובת ה-URL של המפתח הציבורי.
    • ‫CLIENT_ID הוא מזהה הלקוח.
  2. מוסיפים קטע אבטחה ברמת ה-API כדי להחיל אותו על ה-API כולו, או ברמת ה-method כדי להחיל אותו על method ספציפית. 
    security:
  - your_custom_auth_id: []

‫OpenAPI 3.x

  1. מוסיפים את ההגדרות הבאות להגדרות ה-API: 
    components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: ISSUER
        jwksUri: URL_PUBLIC_KEY
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

    כאשר:

    • ‫ISSUER הוא המנפיק של האסימון.
    • ‫URL_PUBLIC_KEY היא כתובת ה-URL של המפתח הציבורי.
    • ‫CLLIENT_ID היא רשימה של מזהי לקוחות כמחרוזות.
  2. מוסיפים קטע אבטחה ברמת ה-API כדי להחיל אותו על ה-API כולו, או ברמת ה-method כדי להחיל אותו על method ספציפית. 
    security:
  - SCHEME_NAME: []

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

השדה x-google-audiences (OpenAPI 2.0) או השדה audiences (OpenAPI 3.x) לא נדרש. ‫API Gateway מקבל את כל אסימוני ה-JWT עם שם שירות הקצה העורפי בצורה https://SERVICE_NAME בהצהרה aud.

כדי לאפשר למזהי לקוח נוספים לגשת לשירות לקצה העורפי, אפשר לציין את מזהי הלקוח המורשים בשדה audiences הרלוונטי. ב-OpenAPI 2.0, אפשר לציין כמה קהלים מופרדים בפסיקים, וב-OpenAPI 3.x אפשר לציין אותם כרשימה. לאחר מכן, API Gateway מקבל את אסימוני ה-JWT עם כל אחד ממזהי הלקוח שצוינו בתביעת aud.

השדה x-google-jwks_uri (OpenAPI 2.0) או jwksUri (OpenAPI 3.x) הוא חובה. ‫API Gateway תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוסף הזה של OpenAPI:

  • פורמט של קבוצת JWK. לדוגמה:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    ‫OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • ‫X509. לדוגמה:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    ‫OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

אם משתמשים בפורמט של מפתח סימטרי, מגדירים את x-google-jwks_uri (OpenAPI 2.0) או את jwksUri (OpenAPI 3.x) ל-URI של קובץ שמכיל את מחרוזת המפתח המקודדת ב-base64url.

שליחת קריאה מאומתת ל-API של API Gateway

כששולחים בקשה באמצעות טוקן אימות, מומלץ להוסיף את הטוקן לכותרת Authorization:Bearer. לדוגמה:

curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"

כאן, צריך להחליף את GATEWAY_URL ואת TOKEN בכתובת ה-URL של השער ובאסימון האימות שפרסתם, בהתאמה. במאמר שליחת בקשה מאומתת ל-API של API Gateway יש קוד לדוגמה לשליחת בקשה באמצעות הכותרת Authorization:Bearer.

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

curl "GATEWAY_URL/hello?access_token=TOKEN"

קבלת תוצאות מאומתות ב-API

בדרך כלל, API Gateway מעביר את כל הכותרות שהוא מקבל. עם זאת, הוא מחליף את הכותרת המקורית Authorization כשכתובת ה-backend מצוינת על ידי x-google-backend בהגדרת ה-API.

‫API Gateway ישלח את תוצאת האימות ב-X-Apigateway-Api-Userinfo אל ה-API של הבק-אנד. מומלץ להשתמש בכותרת הזו במקום בכותרת המקורית Authorization. הכותרת הזו היא base64url מקודדת ומכילה את המטען הייעודי של ה-JWT.

המאמרים הבאים