التفويض باستخدام التفويض على مستوى النطاق

تم تصميم Mail Admin Quarantine API لعمليات التشغيل الآلي من جهة الخادم، مثل مسارات الأمان وعمليات دمج SIEM أو SOAR. تتم مصادقة عمليات التشغيل الآلي هذه باستخدام حساب خدمة Google Cloud الذي يستخدم التفويض على مستوى النطاق للعمل نيابةً عن مشرف حسابات Google Workspace الذي يمتلك امتياز المشرف المطلوب.

توضّح هذه الصفحة نطاقات OAuth 2.0 التي تتطلّبها واجهة برمجة التطبيقات وكيفية إعداد حساب خدمة والحصول على رمز الدخول.

نطاقات 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 ✓

اتّباع مبدأ الحدّ الأدنى من الأذونات المميّزة: اطلب نطاق إذن القراءة فقط لعمليات الدمج التي تراقب وحدة العزل فقط.

إذا كان الطلب يستخدم رمزًا مميزًا لا يتضمّن نطاقًا مقبولاً، ستعرض واجهة برمجة التطبيقات الخطأ 403 مع السبب ACCESS_TOKEN_SCOPE_INSUFFICIENT.

إنشاء حساب خدمة

  1. في وحدة تحكّم Google Cloud، انتقِل إلى المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة واختَر مشروع على السحابة الإلكترونية من Google Cloud الذي فعّلت فيه واجهة برمجة التطبيقات.
  2. انقر على إنشاء حساب خدمة، وأدخِل اسمًا مثل quarantine-api-service-account، ثم انقر على إنشاء ومتابعة. ليس عليك منح حساب الخدمة أي أدوار في "إدارة الهوية وإمكانية الوصول". انقر على تم.
  3. افتح حساب الخدمة، وفي علامة التبويب التفاصيل، انسخ معرّف عميل OAuth 2. وهو رقم مكوّن من 21 رقمًا، على سبيل المثال 109876543210987654321. ستحتاج إلى رقم التعريف هذا في القسم التالي.
  4. في علامة التبويب المفاتيح، انقر على إضافة مفتاح > إنشاء مفتاح جديد، واختَر JSON، ثم انقر على إنشاء. خزِّن ملف مفتاح JSON الذي تم تنزيله في مكان آمن.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء بيانات اعتماد لحساب خدمة.

تفويض التفويض على مستوى النطاق

فوِّض حساب الخدمة للوصول إلى نطاقات Admin Quarantine API في حسابك على Google Workspace:

  1. سجِّل الدخول إلى وحدة تحكّم المشرف في Google بصفتك مشرفًا متميزًا.
  2. انتقِل إلى الأمان > التحكّم في البيانات والوصول > عناصر تحكّم واجهة برمجة التطبيقات.
  3. ضمن التفويض على مستوى النطاق، انقر على إدارة التفويض على مستوى النطاق.
  4. انقر على إضافة جديد.
  5. في حقل معرّف العميل، أدخِل معرّف عميل OAuth 2.0 لحساب الخدمة. لا تُدخِل عنوان البريد الإلكتروني لحساب الخدمة.

  6. في حقل نطاقات OAuth، أدخِل أحد النطاقات التالية:

    • للوصول إلى القراءة والكتابة: https://www.googleapis.com/auth/gmail.admin.quarantine
    • للوصول إلى الملفات للقراءة فقط: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. انقر على تفويض.

لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة التحكّم في الوصول إلى واجهة برمجة التطبيقات من خلال التفويض على مستوى النطاق.

الحصول على رمز دخول

لاستدعاء واجهة برمجة التطبيقات، ينتحل حساب الخدمة صفة مشرف من خلال ضبط المطالبة 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 لطريقتَي الإصدار والرفض، وتأكَّد من تفويض النطاق في "وحدة تحكّم المشرف".
403 PERMISSION_DENIED لا يملك المشرف الذي تم انتحال هويته امتياز وحدة عزل المشرف، أو لا يمكنه الوصول إلى وحدة العزل التي تحتوي على الرسالة. امنح المشرف إذن الوصول إلى وحدة عزل المشرف أو الوصول إلى وحدات عزل محدّدة.
‫403 SERVICE_DISABLED أو 404 NOT_FOUND في كل طريقة لم يتم تفعيل واجهة برمجة التطبيقات في مشروع على السحابة الإلكترونية، أو لم يتم تسجيل المشروع في "برنامج معاينة المطوّر". فعِّل واجهة برمجة التطبيقات وأكِّد تسجيلك في برنامج معاينة المطوّر في Google Workspace.

الخطوات التالية