סקירה כללית על אימות API מבוסס-IAM

הדף הזה מתייחס ל-Apigee, אבל לא ל-Apigee Hybrid.

‫Apigee תומך באימות ובהרשאה מבוססי IAM לשרתי proxy של API. כדי להשתמש בתכונה הזו, צריך לכלול את VerifyIAM policy בתהליך הבקשה של ה-proxy, ולהגדיר את מזהה המשתמש (בדרך כלל כתובת האימייל) של צרכן ה-API כך שיהיו לו ההרשאות או תפקיד ה-IAM הנדרשים Google Cloud להפעלת ממשקי Apigee API. בקשת ה-API צריכה להעביר טוקן גישה תקף של Google Cloud עבור המשתמש הזה.

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

שימוש בבקרת גישה מבוססת-IAM

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

הוספת ניהול הרשאות גישה

כדי להגדיר ניהול הרשאות גישה ל-proxy של API:

  1. מוסיפים את VerifyIAM policy ל-proxy ל-API של Apigee או ל-proxies כחלק מתהליך הבקשה.
  2. האדמין ב-Cloud של פרויקט Apigee:
    1. מעניק את תפקיד ה-IAM‏ deploymentInvoker (או תפקיד בהתאמה אישית עם הרשאת ה-IAM‏ apigee.deployments.invoke) לחשבון המשתמש Google Cloud של צרכן ה-API ברמת הפרויקט. כך צרכן ה-API מקבל גישה להפעלת כל ממשקי ה-API המתארחים בארגון Apigee המשויך.

      או

    2. משתמש בפעולה SetIamPolicy כדי להעניק את התפקיד או ההרשאה ל- Google Cloud principle של צרכן ה-API בפריסה מסוימת או באופן איטרטיבי בכמה פריסות. אפשר להשתמש בפעולת הרשימה במשאב הפריסה כדי לראות את כל הפריסות בסביבה, כולל שרתי proxy של API ורכיבי Shared Flow. שם הפריסה הוא השם של שרת ה-Proxy של ה-API או של הרכיב המשותף.
  3. מפנים את צרכן ה-API אל יצירת אסימון גישה, שהוא יעביר בתוך בקשת Apigee API לבדיקת ההרשאה. ל-token שנוצר צריך להיות https://www.googleapis.com/auth/cloud-platform היקף ההרשאה.

Admin Operations

בקטע הזה מפורטות פעולות שאדמינים של API (מפיקי API) מבצעים כשמנהלים הרשאות שמבוססות על IAM.

תיעוד של פעולות מבוססות API שמשמשות לניהול גישה מבוססת IAM נמצא בתיעוד עזר של ה-API של organizations.environments ושל organizations.environments.deployments, וכולל את הפעולות SetIamPolicy,‏ GetIamPolicy,‏ TestIamPermissions ו-GetDeployment.

בטבלה הזו מפורטות הפעולות וההרשאות שנדרשות לביצוע שלהן:

פעולת אדמין פעולה נדרשת הרשאת IAM משאב IAM שנדרשת לגביו הרשאה*
GetDeployment אחזור מידע על פריסה בסביבת Apigee apigee.deployments.get פרויקט ב-Google Cloud או סביבת Apigee
ListDeployments הצגת רשימה של הפריסות בסביבת Apigee apigee.deployments.list פרויקט או סביבת Apigee
SetIamPolicy הגדרת גישת הפעלה לצרכני API מסוימים בפריסת API מסוימת apigee.deployments.setIamPolicy פרויקט ב-Google Cloud או סביבת Apigee
GetIamPolicy שליפת קבוצת ההגדרות של הרשאות הגישה להפעלה של פריסת API apigee.deployments.getIamPolicy פרויקט ב-Google Cloud או סביבת Apigee
TestIamPermissions בודקים אם למשתמש שקורא ל-API הזה יש את ההרשאה שמוזכרת במטען הייעודי (payload) לא נדרשת הרשאת IAM לא רלוונטי
‫* Google Cloud הפרויקט הוא הפרויקט שמשמש להקצאת Apigee. ההרשאות ברמת הסביבה ב-Apigee מוגדרות בסביבה באמצעות setIAMPolicy.

בדיקת גישה בזמן ריצה

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

הסרת הגישה

כדי להסיר גישה ברמת הפרויקט: כדי להסיר גישה לצרכן API שמנוהל ברמת הפרויקט, אדמין Cloud בפרויקט Apigee מבטל את תפקיד IAM‏ deploymentInvoker (או את התפקיד בהתאמה אישית עם הרשאת IAM‏ apigee.deployments.invoke) מהחשבון הראשי של צרכן ה-API‏ Google Cloud בפרויקט Google Cloud .

אם הגישה ניתנה לפריסות ספציפיות באמצעות setIamPolicy, מסירים את התפקיד או ההרשאה מהפריסות באמצעות פעולה אחרת של setIamPolicy.

מאפיינים ומגבלות של בקרת גישה מבוססת-IAM

כשמשתמשים באימות ובמתן הרשאות שמבוססים על IAM, חשוב לשים לב למאפיינים ולהגבלות הבאים:

  • בדרך כלל, ביצוע המדיניות באמצעות VerifyIAM נמשך בין 10 ל-50 אלפיות השנייה. עם זאת, יכול להיות שיהיו שיחות עם זמני אחזור ארוכים יותר. לדוגמה, באזור asia-east2 ספציפית, זמן האחזור הממוצע יכול לעלות ל-50 אלפיות השנייה, ויכול להיות שחלק מהשיחות יימשכו כ-100 אלפיות השנייה.

    חשוב לזכור שנתוני ההשהיה האלה לא מובטחים.

  • הכללת המדיניות VerifyIAM עבור שרת proxy היא רק בדיקה של מאומת/לא מאומת. התפקידים וההרשאות הספציפיים של צרכן ה-API לא נלקחים בחשבון בתהליכים מאוחרים יותר בזרימת הבקשה או התגובה.
  • בדיקת ההרשאה מתבצעת רק בזמן ההפעלה של מדיניות VerifyIAM, ולכן מדיניות VerifyIAM צריכה להיות המדיניות הראשונה בתהליך הבקשה, אחרי מדיניות ניהול התנועה בלבד.
  • אם אימות ההרשאה מצליח או אם יוצר ה-API סימן את מדיניות VerifyIAM להמשך הפעולה במקרה של שגיאה, זרימת הבקשה ממשיכה להפעיל את המדיניות האחרת, אם יש כזו, עד שהיא מגיעה לשרת היעד. אם בדיקת ההרשאה נכשלת וספק ה-API לא סימן את המדיניות להמשך פעולה במקרה של שגיאה, המשתמש מקבל שגיאה.
  • הוספת גישת הפעלה (apigee.deployments.invoke) ברמת הסביבה לא מעבירה את גישת ההפעלה לכל פריסות ה-API בסביבה.
  • אין תמיכה בתנאי IAM במשאב הפריסה, ואי אפשר להשתמש בהם כדי לשלוט בגישה להפעלת הפונקציה. מידע נוסף זמין במאמר בנושא הוספת תנאי IAM של Apigee למדיניות.
  • בקרת גישה מבוססת-IAM תומכת ב-1,500 קישורי תפקידים לכל היותר במסגרת מדיניות אחת, ויש עוד מגבלות. מכסות ומגבלות ב-IAM
  • בקרת גישה שמבוססת על IAM כפופה לעיכובים בהפצה של IAM.
  • ניסיון לנהל פעולות אחרות של apigee.deployments, כמו apigee.deployments.delete באמצעות setIAMPolicy ברמת הפריסה, לא יהיה יעיל אבל גם לא יחזיר שגיאה. רק apigee.deployements.invoke תקף.
  • הגישה לפריסה נמחקת כשהפרוקסי התואם מבוטל מהסביבה או נמחק. צריך להוסיף מחדש את הגישה לפריסה מחדש.
  • בשלב הזה, אימות והרשאה מבוססי IAM לא זמינים בפתרונות היברידיים.

דוגמאות

בקטע הזה מופיעות דוגמאות להענקת גישה לממשקי API ולביטול הגישה לממשקי API שמבוססת על IAM. כל הדוגמאות האלה מניחות ש-VerifyIAM כבר נוסף ל-proxy ל-API המתאים.

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

הענקת גישה למשתמשים לביצוע קריאות לכל ממשקי ה-API בארגון Apigee וביטול הגישה

כדי להוסיף גישה, צריך להוסיף את התפקיד deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

כדי לבטל את הגישה, מסירים את התפקיד deploymentInvoker:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

הענקה וביטול של גישת משתמשים לפריסות ספציפיות בסביבה

כדי להוסיף את תפקיד ההפעלה למשתמש יחיד בפריסה ספציפית:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
          "user:'"$USER"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

תגובה על הצלחה אמורה להיראות כך:

{
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user-email@example.com"
        ]
      }
    ]
  }

כדי להוסיף את תפקיד ההפעלה למספר משתמשים בפריסה ספציפית:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

כדי לשלוח שאילתה לאובייקט המדיניות שהוגדר קודם:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

אמורה להתקבל תגובה על הצלחה כמו זו שמוצגת למעלה.

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

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

התשובה צריכה לכלול את ההרשאה apigee.deployments.invoke עבור המשתמש.

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

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

תגובת ההצלחה אמורה להיראות בערך כך.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

כדי להסיר את הקישור למשתמש יחיד, משתמשים ב-setIamPolicy ומציינים במטען הייעודי (payload) את המשתמשים שצריכה להיות להם גישה, כמו כשמגדירים גישה ראשונית למשתמשים האלה. בהמשך לדוגמה שלמעלה, אם רוצים להסיר את הגישה של USER1, אבל לשמור את הגישה של USER2 ו-USER3, משתמשים בפקודה הבאה:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

כדי להסיר את הקישור לכל המשתמשים בפריסה ספציפית, מציינים מטען ייעודי ריק:

  curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{}'

כדי לוודא שהקישור הוסר, צריך לוודא שההרשאה apigee.deployments.invoke לא קיימת עבור המשתמש בפריסה:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

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