אישור באמצעות הענקת גישה ברמת הדומיין

‫Mail Admin Quarantine API מיועד לאוטומציות בצד השרת, כמו צינורות עיבוד נתונים לאבטחה ושילובים של SIEM או SOAR. האוטומציות האלה מבצעות אימות באמצעות חשבון שירות ב-Google Cloud, שמשתמש בהענקת גישה ברמת הדומיין כדי לפעול בשם אדמין ב-Google Workspace שיש לו את הרשאת האדמין הנדרשת.

בדף הזה מוסבר אילו היקפי הרשאות של OAuth 2.0 נדרשים ל-API, ואיך מגדירים חשבון שירות ומקבלים אסימון גישה.

היקפי ההרשאות של OAuth 2.0

ה-Admin Quarantine API משתמש בהיקפי ההרשאות הבאים של OAuth 2.0:

היקף משמעות
https://www.googleapis.com/auth/gmail.admin.quarantine לראות ולנהל הודעות שנמצאות בהסגר. נדרשת כדי לשחרר או לדחות הודעות, בנפרד או בקבוצות.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly לראות את ההודעות שבהסגר. מספיקה כדי להציג, לחפש ולקבל הודעות, להציג ולקבל הסגרים ולקבל את הסטטוס של פעולות באצווה.

בטבלה הבאה מפורט היקף ההרשאות שכל שיטה מקבלת:

שיטה gmail.admin.quarantine gmail.admin.quarantine.readonly
customers.quarantinedMessages.list ✓ ✓
customers.quarantinedMessages.search ✓ ✓
customers.quarantinedMessages.get ✓ ✓
customers.quarantines.list ✓ ✓
customers.quarantines.get ✓ ✓
customers.operations.get ✓ ✓
customers.quarantinedMessages.release ✓
customers.quarantinedMessages.deny ✓
customers.quarantinedMessages.batchRelease ✓
customers.quarantinedMessages.batchDeny ✓

פעלו לפי העיקרון של הרשאות מינימליות: בקשו את היקף ההרשאות לקריאה בלבד לשילובים שרק עוקבים אחרי ההסגר.

אם בבקשה נעשה שימוש בטוקן שלא כולל היקף הרשאות מקובל, ה-API מחזיר שגיאה מסוג 403 עם הסיבה ACCESS_TOKEN_SCOPE_INSUFFICIENT.

יצירה של חשבון שירות

  1. במסוף Google Cloud, נכנסים לדף IAM & Admin > Service Accounts ובוחרים את פרויקט הענן שבו הפעלתם את ה-API.
  2. לוחצים על Create service account, מזינים שם כמו quarantine-api-service-account ולוחצים על Create and continue. לא צריך להקצות לחשבון השירות תפקידים ב-IAM. לוחצים על סיום.
  3. פותחים את חשבון השירות ובכרטיסייה Details מעתיקים את OAuth 2 Client ID. זה מספר בן 21 ספרות, לדוגמה 109876543210987654321. תצטרכו את המזהה הזה בקטע הבא.
  4. בכרטיסייה Keys, לוחצים על Add key > Create new key, בוחרים באפשרות JSON ולוחצים על Create. שומרים את קובץ ה-JSON שהורדתם במקום בטוח.

מידע נוסף זמין במאמר יצירת פרטי כניסה לחשבון שירות.

אישור הענקת גישה ברמת הדומיין

נותנים לחשבון השירות הרשאה לגשת להיקפי ההרשאות של Admin Quarantine API בחשבון Google Workspace:

  1. נכנסים למסוף Google Admin כסופר-אדמין.
  2. עוברים אל אבטחה > שליטה בגישה ובנתונים > אמצעי בקרה לממשקי API.
  3. בקטע הענקת גישה ברמת הדומיין, לוחצים על ניהול הענקת גישה ברמת הדומיין.
  4. לוחצים על הוספה.
  5. בשדה Client ID, מזינים את מזהה הלקוח ב-OAuth 2.0 של חשבון השירות. אל תזינו את כתובת האימייל של חשבון השירות.

  6. בשדה היקפי הרשאות של OAuth, מזינים אחד מהיקפי ההרשאות הבאים:

    • כדי לקבל גישת קריאה וכתיבה: https://www.googleapis.com/auth/gmail.admin.quarantine
    • להרשאת קריאה בלבד: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. לוחצים על Authorize.

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

קבלת טוקן גישה

כדי לשלוח קריאה ל-API, חשבון השירות מתחזה לאדמין על ידי הגדרת הטענה (claim) subject (sub) של בקשת האסימון לכתובת האימייל של האדמין. לאדמין צריכה להיות הרשאת האדמין הנדרשת.

בדוגמה הבאה ב-Python משתמשים בספרייה google-auth כדי לקבל אסימון גישה:

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

שולחים את הטוקן בכותרת Authorization של כל בקשה:

Authorization: Bearer ACCESS_TOKEN

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

פתרון בעיות שקשורות לשגיאות הרשאה

סטטוס HTTP סיבה רזולוציה
401 UNAUTHENTICATED הכותרת Authorization חסרה, או שהאסימון לא תקין או שפג תוקפו. משיגים טוקן גישה חדש וכוללים אותו כטוקן למוכ"ז.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT האסימון לא כולל היקף שהשיטה מקבלת. צריך לבקש את ההיקף https://www.googleapis.com/auth/gmail.admin.quarantine לשיטות השחרור והדחייה, ולוודא שההיקף מאושר במסוף Admin.
403 PERMISSION_DENIED לאדמין שמתחזה למשתמש אחר אין הרשאת אדמין להסגר, או שאין לו גישה להסגר שבו נמצאת ההודעה. נותנים לאדמין את ההרשאה גישת אדמינים להסגר או גישה לאימיילים מוגבלים שהועברו להסגר.
‫403 SERVICE_DISABLED או 404 NOT_FOUND בכל שיטה ה-API לא מופעל בפרויקט בענן, או שהפרויקט לא רשום לתוכנית תצוגה מקדימה למפתחים. מפעילים את ה-API ומאשרים את ההרשמה לתוכנית של Google Workspace לתצוגה מקדימה למפתחים.

השלבים הבאים