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

‫OpenAPI   |  gRPC

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

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

‫ESP מאמת JWT בצורה יעילה באמצעות המפתחות הציבוריים של מנפיק ה-JWT. ספק ה-ESP שומר במטמון את המפתחות הציבוריים למשך חמש דקות. בנוסף, שרת ה-ESP שומר במטמון אסימוני JWT מאומתים למשך חמש דקות או עד לתפוגה של ה-JWT, לפי המוקדם מביניהם.

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

• מוסיפים קוד אימות לאפליקציית הלקוח, בהתאם למדריך השילוב של Okta עם Google Cloud Endpoints.

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

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

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

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

OpenAPI 2.0

1. מוסיפים את הקוד הבא למפרט OpenAPI:

   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. מוסיפים את הקוד הבא למפרט OpenAPI:

   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
           # Optional.
           audiences:
             - YOUR_OKTA_CLIENT_ID

   כאשר:

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

   security:
     - okta_jwt: []

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

השדה x-google-audiences או audiences הוא לא חובה. פלטפורמת ESP מקבלת את כל אסימוני ה-JWT עם שם שירות לקצה העורפי בפורמט https://SERVICE_NAME בטענת aud. כדי לאפשר למזהי לקוח נוספים לגשת לשירות לקצה העורפי, אפשר לציין את מזהי הלקוח המורשים בשדה x-google-audiences או audiences באמצעות ערכים מופרדים בפסיקים. לאחר מכן, ה-ESP מקבל את אסימוני ה-JWT עם כל אחד ממזהי הלקוח שצוינו בטענת aud.

אפשר גם להתאים אישית את המיקומים של JWT על ידי הוספת x-google תוספים. לפרטים נוספים, ראו תוספים של OpenAPI 2.0 או תוספים של OpenAPI 3.x.

ביצוע קריאה מאומתת ל-Endpoints API

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

curl -H "Authorization: Bearer <var>TOKEN</var>" "<var>ENDPOINTS_HOST</var>/echo"

מחליפים את המשתנים ENDPOINTS_HOST ו-TOKEN בשם המארח של ה-API ובאסימון האימות, בהתאמה. דוגמאות קוד לשליחת בקשה באמצעות הכותרת Authorization:Bearer מופיעות במאמר שליחת בקשה מאומתת ל-Endpoints API.

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

curl "<var>ENDPOINTS_HOST</var>/echo?access_token=<var>TOKEN</var>"

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

בדרך כלל ספקי ESP מעבירים את כל הכותרות שהם מקבלים. עם זאת, הוא מחליף את הכותרת המקורית Authorization כשכתובת ה-Backend מצוינת על ידי x-google-backend במפרט OpenAPI או על ידי BackendRule בהגדרת שירות gRPC.

ספק ה-ESP ישלח את תוצאת האימות ב-X-Endpoint-API-UserInfo ל-API של השרת העורפי. מומלץ להשתמש בכותרת הזו במקום בכותרת המקורית Authorization. הכותרת הזו היא מחרוזת שbase64urlמקודדת אובייקט JSON. פורמט אובייקט ה-JSON שונה בין ESPv2 לבין ESP. ב-ESPv2, אובייקט ה-JSON הוא בדיוק המטען הייעודי (payload) המקורי של ה-JWT. ב-ESP, אובייקט ה-JSON משתמש בשמות שדות שונים ומציב את מטען ה-JWT המקורי בשדה claims. מידע נוסף על הפורמט זמין במאמר בנושא טיפול ב-JWT בשירות לקצה העורפי.

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

• פתרון בעיות באימות JWT
• אימות בין שירותים