Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

סקירה כללית על אימות 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:

מוסיפים את VerifyIAM policy ל-Apigee proxy ל-API או ל-proxies ל-API כחלק מזרימת הבקשה.
האדמין ב-Cloud של פרויקט Apigee:
1. מעניק את תפקיד ה-IAM‏ deploymentInvoker (או תפקיד בהתאמה אישית עם הרשאת ה-IAM‏ apigee.deployments.invoke) לחשבון הראשי Google Cloud של צרכן ה-API ברמת הפרויקט. כך צרכן ה-API מקבל גישה להפעלת כל ממשקי ה-API המתארחים בארגון Apigee המשויך.
  
  או
2. משתמשים בפעולה SetIamPolicy כדי להעניק את התפקיד או ההרשאה ל Google Cloud עיקרון של צרכן ה-API בפריסה מסוימת או באופן איטרטיבי בכמה פריסות. משתמשים בפעולת הרשימה במשאב הפריסה כדי לראות את כל הפריסות בסביבה, כולל פרוקסי API ורכיבי Shared Flow. שם הפריסה הוא שם פרוקסי ה-API או רכיב ה-Shared Flow.
  הערה: הוספת התפקיד או ההרשאה לפריסות של רכיבי Shared Flow לא יוצרת בדיקת מדיניות VerifyIAM ברכיבי ה-Shared Flow. צריך להחיל את ההרשאות רק על פרוקסי. כשפרוקסי קורא לרכיבי Shared Flow, צריך להחיל את ההרשאות על הפרוקסי. כשמשתמשים בשרשור פרוקסי, צריך להעניק את ההרשאה לפרוקסי עם המדיניות. ההרשאה לא נדרשת בפרוקסי אחר שמשתתף בשרשור.
מפנים את צרכן ה-API אל יצירת טוקן גישה, שהוא יעביר בתוך בקשת Apigee API לבדיקת ההרשאה. לטוקן שנוצר צריך להיות היקף ההרשאות 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, מתבצעת בדיקה כדי לראות אם יש לו את טוקן הגישה הדרוש ואת התפקיד או ההרשאה המתאימים ברמת הפרויקט או הפריסה. אם כן, הוא מקבל אישור להמשיך בגישה לשרת ה-proxy. אחרת, הגישה שלו נחסמת.

הסרת הגישה

כדי להסיר גישה ברמת הפרויקט: כדי להסיר גישה לצרכן 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.

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