הגבלת הגישה ל-API באמצעות מפתחות API

‫OpenAPI   |  gRPC

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

‫Extensible Service Proxy (ESP) משתמש ב-Service Control API כדי לאמת מפתח API ואת השיוך שלו לממשק API שהופעל בפרויקט. אם הגדרתם דרישה למפתח API ב-API שלכם, בקשות לשיטה, למחלקה או ל-API המוגנים יידחו אלא אם יש להן מפתח שנוצר בפרויקט שלכם או בפרויקטים אחרים ששייכים למפתחים שהענקתם להם גישה להפעלת ה-API. הפרויקט שבו נוצר מפתח ה-API לא מתועד ולא מתווסף לכותרת הבקשה. עם זאת, אפשר לראות את הפרויקט שאליו משויך לקוח מסוים בנקודות קצה > שירותים, כמו שמתואר במאמר סינון לפי פרויקט צרכן ספציפי. Google Cloud

במאמר שיתוף ממשקי API שמוגנים באמצעות מפתח API מוסבר באיזה פרויקט Google Cloud צריך ליצור מפתח API.

הגבלת הגישה לכל שיטות ה-API

כדי לדרוש מפתח API לגישה לכל ה-methods של API:

OpenAPI 2.0

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. בקטע securityDefinitions:, מוסיפים את הערכים api_key:, apiKey, key, query כמו שמופיע בדוגמה של קטע הקוד:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

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

3. ברמה העליונה של הקובץ (לא מוזח או מקונן), מוסיפים api_key: [] להנחיית security. יכול להיות שתצטרכו להוסיף את ההנחיה security או שהיא כבר תהיה קיימת:

   security:
     - api_key: []

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

‫OpenAPI 3.x

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. בקטע components.securitySchemes:, מוסיפים את הפרטים הבאים:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

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

3. ברמה העליונה של הקובץ (לא מוזח או מקונן), מוסיפים api_key: [] להנחיית security:

   security:
     - api_key: []

   ההנחיה הזו מחילה את תוכנית האבטחה api_key על כל השיטות בקובץ.

הגבלת הגישה לשיטות ספציפיות של API

כדי לדרוש מפתח API לשימוש בשיטה ספציפית:

OpenAPI 2.0

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. ברמה העליונה של הקובץ (לא מוזח או מקונן), מוסיפים הנחיית אבטחה ריקה כדי להחיל אותה על ה-API כולו:

   security: []

3. בקטע securityDefinitions:, מוסיפים את הערכים api_key:, apiKey, key, query כמו שמופיע בדוגמה של קטע הקוד:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

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

4. מוסיפים את api_key: [] להוראה security בהגדרה של השיטה:

   ...
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         produces:
         ...

   ההנחיה הזו מחילה את תוכנית האבטחה api_key על השיטה. אל תכניסו שום דבר בין הסוגריים. במפרט OpenAPI נדרשת רשימה ריקה עבור תוכניות אבטחה שלא משתמשות ב-OAuth.

‫OpenAPI 3.x

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. ברמה העליונה של הקובץ (לא מוזח או מקונן), מוסיפים הנחיית אבטחה ריקה כדי להחיל אותה על ה-API כולו:

   security: []

3. בקטע components.securitySchemes:, מוסיפים את הפרטים הבאים:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

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

4. מוסיפים את api_key: [] להוראה security בהגדרה של השיטה:

   ...
   paths:
     /echo:
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         requestBody:
         ...

   ההנחיה הזו מחילה את תוכנית האבטחה api_key על השיטה.

הסרת הגבלה של מפתח API משיטה

כדי להשבית את האימות של מפתח API לשיטה מסוימת, גם אם הגבלתם את הגישה ל-API:

OpenAPI 2.0

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. מוסיפים הוראה ריקה security בהגדרה של השיטה:

     ...
     paths:
       "/echo":
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           produces:
           ...

‫OpenAPI 3.x

1. פותחים את הקובץ openapi.yaml של הפרויקט בכלי לעריכת טקסט.
2. מוסיפים הוראה ריקה security בהגדרה של השיטה:

     ...
     paths:
       /echo:
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           requestBody:
           ...

שליחת קריאה ל-API באמצעות מפתח API

אם API או method של API דורשים מפתח API, צריך לספק את המפתח באמצעות פרמטר שאילתה בשם key, כמו בדוגמה הבאה של curl:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

כאשר ENDPOINTS_HOST ו-ENDPOINTS_KEY הם משתני סביבה שמכילים את שם המארח של ה-API ואת מפתח ה-API, בהתאמה.

שיתוף ממשקי API שמוגנים באמצעות מפתח API

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

• האם אתם צריכים להבחין בין המתקשרים לממשק ה-API כדי שתוכלו להשתמש בתכונות של Endpoints כמו מכסות?
• האם לכל מי שמתקשר עם ה-API יש פרויקט משלו ב- Google Cloud ?
• צריך להגדיר הגבלות שונות על מפתחות API?

עץ ההחלטות הבא יעזור לכם להחליט באיזה פרויקט ליצור את מפתח ה-API. Google Cloud

אישור הרשאה להפעלת ה-API

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

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

כדי לאפשר למשתמשים ליצור מפתח API משלהם:

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

ליצור Google Cloud פרויקט נפרד לכל מתקשר

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

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

כדי ליצור Google Cloud פרויקט ומפתח API נפרדים לכל מתקשר:

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

יצירת מפתח API לכל מתקשר

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

כדי ליצור מפתח API לכל קורא באותו פרויקט:

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

יצירת מפתח API אחד לכל המתקשרים

אם אתם לא צריכים להבחין בין מי שקורא ל-API שלכם, ואתם לא צריכים להוסיף הגבלות ל-API, אבל אתם עדיין רוצים לדרוש מפתח API (למשל כדי למנוע גישה אנונימית), אתם יכולים ליצור מפתח API אחד שכל מי שקורא ל-API יוכל להשתמש בו.

כדי ליצור מפתח API אחד לכל המתקשרים:

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

הגבלות על אפליקציות

הגבלות על אפליקציות מציינות אילו כתובות IP, אפליקציות ואתרים יכולים להשתמש במפתח ה-API. מידע נוסף זמין במאמר הוספת הגבלות על אפליקציות.

הערה: אם משתמשים בHTTP referrers (websites) כהגבלת אפליקציה, צריך לכלול סכימה (לדוגמה, https://) כשמוסיפים את הגבלת האתר. לדוגמה, https://example.com/* היא הגבלה תקינה, אבל example.com/* היא לא.

שיטות מומלצות

אם אתם מסתמכים על מפתחות API כדי להגן על הגישה ל-API ולנתוני המשתמשים, הקפידו להגדיר את הדגל --service_control_network_fail_policy לערך close כשאתם מגדירים את אפשרויות ההפעלה של Extensible Service Proxy V2‏ (ESPv2). ערך ברירת המחדל של הדגל הוא open.

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

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

• מתי וכדאי להשתמש במפתחות API
• אבטחת מפתח API