Package google.iam.v1

אינדקס

• ‫IAMPolicy (ממשק)
• ‫Binding (הודעה)
• ‫GetIamPolicyRequest (הודעה)
• ‫GetPolicyOptions (הודעה)
• ‫Policy (הודעה)
• ‫SetIamPolicyRequest (הודעה)
• ‫TestIamPermissionsRequest (הודעה)
• ‫TestIamPermissionsResponse (הודעה)

IAMPolicy

סקירה כללית על API

ניהול כללי המדיניות של ניהול זהויות והרשאות גישה (IAM).

כל הטמעה של API שמציע תכונות של בקרת גישה מטמיעה את הממשק google.iam.v1.IAMPolicy.

מודל נתונים

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

מבנה המדיניות

‫See google.iam.v1.Policy

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

GetIamPolicy
rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy) מקבלת את מדיניות בקרת הגישה למשאב. אם המשאב קיים ולא מוגדרת לו מדיניות, הפונקציה מחזירה מדיניות ריקה. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

SetIamPolicy
rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy) הגדרת מדיניות בקרת הגישה במשאב שצוין. היא מחליפה כל מדיניות קיימת. יכול להחזיר שגיאות NOT_FOUND, INVALID_ARGUMENT ו-PERMISSION_DENIED. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse) הפונקציה מחזירה את ההרשאות שיש למבצע הקריאה במשאב שצוין. אם המשאב לא קיים, הפונקציה תחזיר קבוצה ריקה של הרשאות, ולא שגיאה מסוג NOT_FOUND. הערה: הפעולה הזו מיועדת ליצירת ממשקי משתמש מבוססי הרשאות וכלים של שורת הפקודה, ולא לבדיקת הרשאות. יכול להיות שהפעולה הזו תיכשל בלי התראה. היקפי הרשאות נדרש אחד מהיקפי ההרשאות הבאים של OAuth: https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/notebooks ניתן למצוא מידע נוסף כאן: Authentication Overview.

קישור

משייכים members או מנהלים עם role.

שדות
role	string התפקיד שמוקצה לרשימה של members, או חשבונות משתמשים. לדוגמה, roles/viewer, roles/editor או roles/owner. סקירה כללית של התפקידים וההרשאות ב-IAM זמינה במסמכי ה-IAM. רשימת התפקידים המוגדרים מראש זמינה כאן.
members[]	string מציין את חשבונות המשתמשים שמבקשים גישה למשאב ב-Google Cloud. ‫members יכול לקבל את הערכים הבאים: ‫allUsers: מזהה מיוחד שמייצג את כל מי שמשתמש באינטרנט, עם או בלי חשבון Google. ‫allAuthenticatedUsers: מזהה מיוחד שמייצג את כל מי שאומת באמצעות חשבון Google או חשבון שירות. לא כולל זהויות שמגיעות מספקי זהויות חיצוניים (IdPs) דרך איחוד זהויות. user:{emailid}: כתובת אימייל שמייצגת חשבון Google ספציפי. לדוגמה, [e-mail] . serviceAccount:{emailid}: כתובת אימייל שמייצגת חשבון שירות של Google. לדוגמה, [e-mail]. ‫serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]: מזהה של חשבון שירות של Kubernetes. לדוגמה, my-project.svc.id.goog[my-namespace/my-kubernetes-sa]. ‫group:{emailid}: כתובת אימייל שמייצגת קבוצה ב-Google. לדוגמה, [e-mail]. ‫domain:{domain}: דומיין G Suite (ראשי) שמייצג את כל המשתמשים בדומיין הזה. לדוגמה, google.com או example.com. ‫principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}: זהות יחידה במאגר זהויות של כוח עבודה. ‫principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/group/{group_id}: כל הזהויות של כוח העבודה בקבוצה. ‫principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/attribute.{attribute_name}/{attribute_value}: כל הזהויות של כוח העבודה עם ערך מאפיין ספציפי. ‫principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/*: כל הזהויות במאגר זהויות של כוח עבודה. ‫principal://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/subject/{subject_attribute_value}: זהות אחת במאגר זהויות של עומסי עבודה. ‫principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/group/{group_id}: קבוצה במאגר הזהויות של עומסי העבודה. ‫principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/attribute.{attribute_name}/{attribute_value}: כל הזהויות במאגר זהויות של עומסי עבודה עם מאפיין מסוים. ‫principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/*: כל הזהויות במאגר הזהויות של עומסי העבודה. ‫deleted:user:{emailid}?uid={uniqueid}: כתובת אימייל (בתוספת מזהה ייחודי) שמייצגת משתמש שנמחק לאחרונה. לדוגמה, [e-mail]?uid=123456789012345678901. אם המשתמש ישוחזר, הערך הזה יחזור ל-user:{emailid} והמשתמש המשוחזר ישמור על התפקיד בהתאמה. deleted:serviceAccount:{emailid}?uid={uniqueid}: כתובת אימייל (בתוספת מזהה ייחודי) שמייצגת חשבון שירות שנמחק לאחרונה. לדוגמה, [e-mail]?uid=123456789012345678901. אם מבטלים את המחיקה של חשבון השירות, הערך הזה חוזר ל-serviceAccount:{emailid} וחשבון השירות שבוטלה המחיקה שלו שומר על התפקיד בקישור. ‫deleted:group:{emailid}?uid={uniqueid}: כתובת אימייל (בתוספת מזהה ייחודי) שמייצגת קבוצת Google שנמחקה לאחרונה. לדוגמה, [e-mail]?uid=123456789012345678901. אם הקבוצה משוחזרת, הערך הזה חוזר ל-group:{emailid} והקבוצה המשוחזרת שומרת על התפקיד בהרשאה. deleted:principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}: זהות יחידה שנמחקה במאגר זהויות של כוח עבודה. לדוגמה, deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value.
condition	Expr התנאי שמשויך לקישור הזה. אם התנאי מקבל את הערך true, הקישור הזה חל על הבקשה הנוכחית. אם התנאי מקבל את הערך false, הקישור הזה לא חל על הבקשה הנוכחית. עם זאת, יכול להיות שקישור תפקיד אחר יקצה את אותו תפקיד לאחד או יותר מחשבונות המשתמש בקישור הזה. במאמרי העזרה של IAM מוסבר אילו משאבים תומכים בתנאים במדיניות ה-IAM שלהם.

GetIamPolicyRequest

הודעת בקשה לשיטה GetIamPolicy.

שדות
resource	string חובה: המשאב שעבורו מתבקשת המדיניות. במאמר שמות משאבים מוסבר מהו הערך המתאים לשדה הזה.
options	GetPolicyOptions אופציונלי: אובייקט GetPolicyOptions לציון אפשרויות ל-GetIamPolicy.

GetPolicyOptions

הגדרה שמספקת את ההגדרות ל-GetIamPolicy.

שדות

requested_policy_version

int32 זה שינוי אופציונלי. גרסת המדיניות המקסימלית שתשמש לעיצוב המדיניות. הערכים התקינים הם 0, 1 ו-3. בקשות שבהן צוין ערך לא תקין יידחו. בבקשות למדיניות עם קישורי תפקידים מותנים צריך לציין את גרסה 3. במדיניות ללא קישורי תפקידים מותנים אפשר לציין כל ערך תקין או להשאיר את השדה לא מוגדר. יכול להיות שהמדיניות בתשובה תשתמש בגרסת המדיניות שציינתם, או בגרסת מדיניות נמוכה יותר. לדוגמה, אם מציינים גרסה 3, אבל למדיניות אין קישורי תפקידים מותנים, התשובה משתמשת בגרסה 1. במאמרי העזרה של IAM מוסבר אילו משאבים תומכים בתנאים במדיניות ה-IAM שלהם.

מדיניות

מדיניות ניהול הזהויות והרשאות הגישה (IAM), שמציינת את אמצעי בקרת הגישה למשאבים ב-Google Cloud.

Policy הוא אוסף של bindings. binding מקשרת members אחד או יותר, או חשבונות משתמשים, לrole יחיד. חשבונות ראשיים יכולים להיות חשבונות משתמשים, חשבונות שירות, קבוצות Google ודומיינים (כמו G Suite). role היא רשימה של הרשאות עם שם. כל role יכול להיות תפקיד מוגדר מראש ב-IAM או תפקיד בהתאמה אישית שנוצר על ידי משתמש.

בסוגים מסוימים של משאבים ב-Google Cloud, אפשר גם לציין condition ב-binding. condition הוא ביטוי לוגי שמאפשר גישה למשאב רק אם הערך של הביטוי הוא true. תנאי יכול להוסיף מגבלות על סמך מאפיינים של הבקשה, של המשאב או של שניהם. במאמרי העזרה של IAM מוסבר אילו משאבים תומכים בתנאים במדיניות ה-IAM שלהם.

דוגמה ל-JSON:

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:[e-mail]",
            "group:[e-mail]",
            "domain:google.com",
            "serviceAccount:[e-mail]"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:[e-mail]"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

דוגמה ל-YAML:

    bindings:
    - members:
      - user:[e-mail]
      - group:[e-mail]
      - domain:google.com
      - serviceAccount:[e-mail]
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:[e-mail]
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

למידע על IAM והמאפיינים שלו, תוכלו לעיין במסמכי העזרה של IAM.

שדות
version	int32 מציין את הפורמט של המדיניות. הערכים התקפים הם 0,‏ 1 ו-3. בקשות שמציינות ערך לא תקין נדחות. בכל פעולה שמשפיעה על קישורי תפקידים מותנים צריך לציין את הגרסה 3. הדרישה הזו חלה על הפעולות הבאות: קבלת מדיניות שכוללת קישור תפקיד מותנה הוספה של קישור תפקיד מותנה למדיניות שינוי של קישור תפקיד מותנה במדיניות הסרה של קישור תפקידים, עם או בלי תנאי, ממדיניות שכוללת תנאים חשוב לדעת: אם משתמשים בתנאים של IAM, צריך לכלול את השדה etag בכל קריאה ל-setIamPolicy. אם משמיטים את השדה הזה, IAM מאפשר להחליף את מדיניות גרסה 3 במדיניות גרסה 1, וכל התנאים במדיניות גרסה 3 יימחקו. אם מדיניות לא כוללת תנאים, בפעולות שמתבצעות במדיניות הזו אפשר לציין כל גרסה תקינה או להשאיר את השדה ללא הגדרה. במאמרי העזרה של IAM מוסבר אילו משאבים תומכים בתנאים במדיניות ה-IAM שלהם.
bindings[]	Binding משייך רשימה של members, או חשבונות משתמשים, לrole. אפשר גם לציין condition שקובע איך ומתי יחולו bindings. כל אחד מהתגים bindings חייב להכיל לפחות גורם ראשי אחד. ה-bindings ב-Policy יכול להפנות לעד 1,500 חשבונות משתמשים, ומתוכם עד 250 יכולים להיות קבוצות Google. כל מופע של גורם ראשי נספר במסגרת המגבלות האלה. לדוגמה, אם ההרשאה bindings מעניקה 50 תפקידים שונים ל-user:[e-mail], ולא לחשבון משתמש אחר, תוכלו להוסיף עוד 1,450 חשבונות משתמשים ל-bindings ב-Policy.
etag	bytes ‫etag משמש לבקרת בו-זמניות אופטימית כדי למנוע מצב שבו עדכונים בו-זמניים של מדיניות יחליפו אחד את השני. מומלץ מאוד להשתמש ב-etag במחזור הקריאה-שינוי-כתיבה כדי לבצע עדכונים במדיניות ולמנוע מרוץ תהליכים: ערך etag מוחזר בתגובה ל-getIamPolicy, והמערכות אמורות להוסיף את ערך ה-etag הזה לבקשה ל-setIamPolicy כדי לוודא שהשינוי יוחל על אותה גרסה של המדיניות. חשוב לדעת: אם משתמשים בתנאים של IAM, צריך לכלול את השדה etag בכל קריאה ל-setIamPolicy. אם משמיטים את השדה הזה, IAM מאפשר להחליף את מדיניות גרסה 3 במדיניות גרסה 1, וכל התנאים במדיניות גרסה 3 יימחקו.

SetIamPolicyRequest

הודעת בקשה לשיטה SetIamPolicy.

שדות
resource	string חובה: המשאב שעבורו מציינים את המדיניות. במאמר שמות משאבים מוסבר מהו הערך המתאים לשדה הזה.
policy	Policy חובה: המדיניות המלאה שתחול על resource. גודל המדיניות מוגבל לכמה עשרות קילובייט. מדיניות ריקה היא מדיניות תקינה, אבל יכול להיות ששירותים מסוימים של Google Cloud (כמו פרויקטים) ידחו אותה.

TestIamPermissionsRequest

הודעת בקשה לשיטה TestIamPermissions.

שדות
resource	string חובה: המשאב שעבורו מתבקשים פרטי המדיניות. במאמר שמות משאבים מוסבר מהו הערך המתאים לשדה הזה.
permissions[]	string קבוצת ההרשאות לבדיקה עבור resource. אסור להשתמש בהרשאות עם תווים כלליים לחיפוש (כמו * או storage.*). מידע נוסף מופיע במאמר סקירה כללית על IAM.

TestIamPermissionsResponse

הודעת תגובה לשיטה TestIamPermissions.

שדות
permissions[]	string קבוצת משנה של TestPermissionsRequest.permissions שהמתקשר מורשה להשתמש בה.