Memberikan otorisasi dengan delegasi tingkat domain

Mail Admin Quarantine API dirancang untuk otomatisasi sisi server seperti pipeline keamanan dan integrasi SIEM atau SOAR. Otomatisasi ini melakukan autentikasi dengan akun layanan Google Cloud yang menggunakan delegasi tingkat domain untuk bertindak atas nama administrator Google Workspace yang memiliki hak istimewa administrator yang diperlukan.

Halaman ini menjelaskan cakupan OAuth 2.0 yang diperlukan API dan cara mengonfigurasi akun layanan serta mendapatkan token akses.

Cakupan OAuth 2.0

Admin Quarantine API menggunakan cakupan OAuth 2.0 berikut:

Cakupan Arti
https://www.googleapis.com/auth/gmail.admin.quarantine Melihat dan mengelola pesan yang dikarantina. Diperlukan untuk merilis atau menolak pesan, satu per satu atau dalam batch.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Melihat pesan yang dikarantina. Cukup untuk mencantumkan, menelusuri, dan mendapatkan pesan, mencantumkan dan mendapatkan karantina, serta mendapatkan status operasi batch.

Tabel berikut menunjukkan cakupan yang diterima setiap metode:

Metode 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 ✓

Ikuti prinsip hak istimewa terendah: minta cakupan hanya baca untuk integrasi yang hanya memantau karantina.

Jika permintaan menggunakan token yang tidak menyertakan cakupan yang diterima, API akan menampilkan error 403 dengan alasan ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Membuat akun layanan

  1. Di Konsol Google Cloud, buka IAM & Admin > Service Accounts dan pilih project Google Cloud tempat Anda mengaktifkan API.
  2. Klik Create service account, masukkan nama seperti quarantine-api-service-account, lalu klik Create and continue. Anda tidak perlu memberikan peran IAM apa pun ke akun layanan. Klik Done.
  3. Buka akun layanan dan, di tab Details, salin OAuth 2 Client ID. Nomor ini terdiri dari 21 digit, misalnya 109876543210987654321. Anda akan memerlukan ID ini di bagian berikutnya.
  4. Di tab Keys, klik Add key > Create new key, pilih JSON, dan klik Create. Simpan file kunci JSON yang didownload dengan aman.

Untuk mengetahui informasi selengkapnya, lihat Membuat kredensial untuk akun layanan.

Memberikan otorisasi delegasi tingkat domain

Beri otorisasi akun layanan untuk mengakses cakupan Admin Quarantine API di akun Google Workspace Anda:

  1. Login ke konsol Google Admin sebagai administrator super.
  2. Buka Keamanan > Kontrol data dan akses > Kontrol API.
  3. Di bagian Delegasi tingkat domain, klik Kelola delegasi tingkat domain.
  4. Klik Tambahkan baru.
  5. Di kolom Client ID, masukkan Client ID OAuth 2.0 akun layanan. Jangan masukkan alamat email akun layanan.

  6. Di kolom OAuth scopes, masukkan salah satu cakupan berikut:

    • Untuk akses baca dan tulis: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Untuk akses hanya baca: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Klik Otorisasi.

Untuk mengetahui detailnya, lihat Mengontrol akses API dengan delegasi tingkat domain.

Mendapatkan token akses

Untuk memanggil API, akun layanan meniru identitas administrator dengan menetapkan klaim subject (sub) dari permintaan token ke alamat email administrator. Administrator harus memiliki hak istimewa administrator yang diperlukan.

Contoh Python berikut menggunakan library google-auth untuk mendapatkan token akses:

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

Kirim token di header Authorization setiap permintaan:

Authorization: Bearer ACCESS_TOKEN

Masa berlaku token akses akan berakhir setelah satu jam. Perbarui kredensial sebelum setiap batch permintaan, bukan meng-cache token untuk jangka waktu yang lama.

Memecahkan masalah error otorisasi

Status HTTP Alasan Resolusi
401 UNAUTHENTICATED Header Authorization tidak ada, atau token salah format atau sudah tidak berlaku. Dapatkan token akses baru dan sertakan sebagai token pemilik.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Token tidak menyertakan cakupan yang diterima metode. Minta cakupan https://www.googleapis.com/auth/gmail.admin.quarantine untuk metode rilis dan tolak, serta pastikan cakupan diotorisasi di konsol Admin.
403 PERMISSION_DENIED Administrator yang ditiru tidak memiliki hak istimewa karantina admin, atau tidak memiliki akses ke karantina yang menyimpan pesan. Berikan Mengakses Karantina Admin atau Mengakses karantina yang dibatasi kepada administrator.
403 SERVICE_DISABLED atau 404 NOT_FOUND di setiap metode API tidak diaktifkan di project Cloud, atau project tidak terdaftar dalam Program Pratinjau Developer. Aktifkan API dan konfirmasi pendaftaran Anda di Program Pratinjau Developer Google Workspace.

Langkah berikutnya