שימוש בשיטה מותאמת אישית לאימות משתמשים

‫OpenAPI   |  gRPC

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

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

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

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

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

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

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

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

כדי לתמוך באימות בהתאמה אישית:

OpenAPI 2.0

1. מוסיפים את השורות הבאות להגדרת האבטחה במסמך OpenAPI:

   securityDefinitions:
     your_custom_auth_id:
       authorizationUrl: ""
       flow: "implicit"
       type: "oauth2"
       # The value below should be unique
       x-google-issuer: "issuer of the token"
       x-google-jwks_uri: "url to the public key"
       # Optional. Replace YOUR_CLIENT_ID with your client ID
       x-google-audiences: "YOUR_CLIENT_ID"

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

   security:
     - your_custom_auth_id: []

‫OpenAPI 3.x

1. מוסיפים את השורות הבאות להגדרת האבטחה במסמך OpenAPI:

   components:
     securitySchemes:
       your_custom_auth_id:
         type: oauth2
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "issuer of the token"
           jwksUri: "url to the public key"
           audiences:
             - "YOUR_CLIENT_ID"

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

   security:
     - your_custom_auth_id: []

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

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

‫ESP תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוספים x-google-jwks_uri ו-jwksUri של OpenAPI:

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

  OpenAPI 2.0

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

  ‫OpenAPI 3.x

  x-google-auth:
    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/[e-mail]"
  

  ‫OpenAPI 3.x

  x-google-auth:
    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/[e-mail]"
  

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

אם לא מציינים את x-google-jwks_uri או jwksUri, ‏ ESP יפעל לפי פרוטוקול OpenID Connect Discovery כדי לגלות באופן אוטומטי את מזהה ה-URI של JWKS עבור ספק OpenID שצוין. ה-ESP ישלח בקשה אל x-google-issuer/.well-known/openid-configuration, ינתח את תגובת ה-JSON ויקרא את ה-URI של JWKS מהשדה jwks_uri ברמה העליונה.

שימו לב: אם לא תציינו את x-google-jwks_uri או jwksUri, זמני ההפעלה במצב התחלתי (cold start) יהיו ארוכים יותר, כי ה-ESP יצטרך לבצע קריאה נוספת מרחוק בהפעלה. לכן, מומלץ להשמיט את השדה הזה רק אם ה-URI של JWKS משתנה לעיתים קרובות. לרוב ספקי OpenID המוסמכים (כמו Google,‏ Auth0 ו-Okta) יש כתובות URI יציבות של JWKS.

אפשר גם להתאים אישית את המיקומים של 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
• אימות בין שירותים