ให้สิทธิ์ด้วยการมอบสิทธิ์ทั่วทั้งโดเมน

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 และผู้ดูแลระบบ > บัญชีบริการ แล้วเลือกโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google ที่คุณเปิดใช้ API
  2. คลิกสร้างบัญชีบริการ ป้อนชื่อ เช่น quarantine-api-service-account แล้วคลิกสร้างและดำเนินการต่อ คุณไม่จำเป็นต้องให้บทบาท IAM ใดๆ แก่บัญชีบริการ คลิกเสร็จสิ้น
  3. เปิดบัญชีบริการ และในแท็บรายละเอียด ให้คัดลอกรหัสไคลเอ็นต์ OAuth 2 ซึ่งเป็นตัวเลข 21 หลัก เช่น 109876543210987654321 คุณจะต้องใช้รหัสนี้ในส่วนถัดไป
  4. ในแท็บคีย์ ให้คลิกเพิ่มคีย์ > สร้างคีย์ใหม่ เลือก JSON แล้วคลิกสร้าง จัดเก็บไฟล์คีย์ JSON ที่ดาวน์โหลดไว้อย่างปลอดภัย

ดูข้อมูลเพิ่มเติมได้ที่หัวข้อสร้างข้อมูลเข้าสู่ระบบสำหรับบัญชีบริการ

ให้สิทธิ์การมอบสิทธิ์ทั่วทั้งโดเมน

ให้สิทธิ์บัญชีบริการเข้าถึงขอบเขต Admin Quarantine API ในบัญชี Google Workspace โดยทำดังนี้

  1. ลงชื่อเข้าใช้คอนโซลผู้ดูแลระบบของ Google ในฐานะผู้ดูแลระบบขั้นสูง
  2. ไปที่ความปลอดภัย > การเข้าถึงและการควบคุมข้อมูล > การควบคุม API
  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. คลิกให้สิทธิ์

ดูรายละเอียดได้ที่หัวข้อควบคุมการเข้าถึง API ด้วยการมอบสิทธิ์ทั่วทั้งโดเมน

รับโทเค็นเพื่อการเข้าถึง

หากต้องการเรียก API บัญชีบริการจะแอบอ้างเป็นผู้ดูแลระบบโดยตั้งค่าการอ้างสิทธิ์ 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

โทเค็นเพื่อการเข้าถึงจะหมดอายุหลังจากผ่านไป 1 ชั่วโมง รีเฟรชข้อมูลเข้าสู่ระบบก่อนคำขอแต่ละชุดแทนที่จะแคชโทเค็นเป็นเวลานาน

แก้ปัญหาข้อผิดพลาดในการให้สิทธิ์

สถานะ HTTP เหตุผล ความละเอียด
401 UNAUTHENTICATED ไม่มีส่วนหัว Authorization หรือโทเค็นมีรูปแบบไม่ถูกต้องหรือหมดอายุแล้ว รับโทเค็นเพื่อการเข้าถึงใหม่และรวมไว้เป็นโทเค็นสำหรับผู้ถือ
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT โทเค็นไม่มีขอบเขตที่เมธอดรองรับ ขอขอบเขต https://www.googleapis.com/auth/gmail.admin.quarantine สำหรับเมธอด release และ deny และตรวจสอบว่าขอบเขตได้รับสิทธิ์ในคอนโซลผู้ดูแลระบบ
403 PERMISSION_DENIED ผู้ดูแลระบบที่ถูกแอบอ้างไม่มีสิทธิ์ในเขตกักเก็บของผู้ดูแลระบบ หรือไม่มีสิทธิ์เข้าถึงเขตกักเก็บที่มีข้อความดังกล่าว ให้สิทธิ์เข้าถึงเขตกักเก็บของผู้ดูแลระบบหรือเข้าถึงเขตกักเก็บที่ถูกจำกัดแก่ผู้ดูแลระบบ
403 SERVICE_DISABLED หรือ 404 NOT_FOUND ในทุกเมธอด ไม่ได้เปิดใช้ API ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ หรือโปรเจ็กต์ไม่ได้ลงทะเบียนในโปรแกรมเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ เปิดใช้ API และยืนยันการลงทะเบียนในโปรแกรมเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ Google Workspace

ขั้นตอนถัดไป