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

בדף הזה מוסבר איך לתמוך באימות משתמשים ב-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 שבה אתם משתמשים.

כמו שמוסבר במדריך לשילוב Okta עם Cloud Endpoints של Google Cloud, צריך לבצע את השינויים הבאים במסמך OpenAPI:

OpenAPI 2.0

  1. מוסיפים את ההגדרות הבאות להגדרות ה-API: 
    securityDefinitions:
  okta_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://YOUR_OKTA_TENANT_NAME.com"
    x-google-jwks_uri: "https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys"
    x-google-audiences: "YOUR_OKTA_CLIENT_ID"

    כאשר:

    • ‫YOUR_OKTA_TENANT_NAME הוא השם של הדייר שלכם ב-Okta.
    • ‫YOUR_OKTA_CLIENT_ID הוא מזהה הלקוח שיצרתם בדייר Okta.
  2. מוסיפים קטע אבטחה ברמת ה-API כדי להחיל אותו על ה-API כולו, או ברמת השיטה כדי להחיל אותו על שיטה ספציפית. 
    security:
   -   okta_jwt: []

‫OpenAPI 3.x

  1. מוסיפים את ההגדרות הבאות להגדרות ה-API: 
    components:
  securitySchemes:
    okta_jwt:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: https://YOUR_OKTA_TENANT_NAME.com
        jwksUri: https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys
        audiences:
          - YOUR_OKTA_CLIENT_ID

    כאשר:

    • ‫YOUR_OKTA_TENANT_NAME הוא השם של הדייר שלכם ב-Okta.
    • ‫YOUR_OKTA_CLIENT_ID הוא מזהה הלקוח שיצרתם בדייר Okta.
  2. מוסיפים קטע אבטחה ברמת ה-API כדי להחיל אותו על ה-API כולו, או ברמת ה-method כדי להחיל אותו על method ספציפית. 
    security:
  - okta_jwt: []

אפשר להגדיר כמה הגדרות אבטחה בהגדרת ה-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.

שליחת קריאה מאומתת ל-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.

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