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

הדף הזה רלוונטי ל-Apigee, אבל לא ל-Apigee Hybrid.

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

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

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

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

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

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

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

      או

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

Admin Operations

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

במאמרי העזרה של API בנושא organizations.environments ו-organizations.environments.deployments מוסבר על פעולות מבוססות API שמשמשות לניהול גישה מבוססת IAM, כולל הפעולות 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) מהחשבון הראשי Google Cloud של צרכן ה-API בפרויקט 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 תקף.
  • הגישה לפריסה נמחקת כשמבטלים את הפריסה של ה-proxy התואם מהסביבה או כשמוחקים אותו. צריך להוסיף מחדש את הגישה כשפורסים מחדש.
  • בשלב הזה, אימות והרשאה מבוססי IAM לא זמינים בפריסה היברידית.

דוגמאות

בקטע הזה מופיעות דוגמאות להענקת גישה לממשקי API ולביטול הגישה לממשקי API שמבוססת על IAM. כל הדוגמאות האלה מניחות ש-VerifyIAM כבר נוסף לפרוקסי המתאים של 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.