Alan genelinde yetkiyle yetkilendirme

Mail Admin Quarantine API, güvenlik ardışık düzenleri ve SIEM veya SOAR entegrasyonları gibi sunucu tarafı otomasyonlar için tasarlanmıştır. Bu otomasyonlar, gerekli yönetici ayrıcalığına sahip bir Google Workspace yöneticisi adına işlem yapmak için alan genelinde yetki kullanan bir Google Cloud hizmet hesabıyla kimlik doğrulaması yapar.

Bu sayfada, API'nin hangi OAuth 2.0 kapsamlarını gerektirdiği, hizmet hesabının nasıl yapılandırılacağı ve erişim jetonunun nasıl alınacağı açıklanmaktadır.

OAuth 2.0 kapsamları

Admin Quarantine API, aşağıdaki OAuth 2.0 kapsamlarını kullanır:

Kapsam Anlamı
https://www.googleapis.com/auth/gmail.admin.quarantine Karantinaya alınan iletileri görüntüleme ve yönetme İletileri tek tek veya toplu olarak yayınlamak ya da reddetmek için gereklidir.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Karantinaya alınan iletileri görüntüleme İletileri listelemek, aramak ve almak, karantinaları listelemek ve almak, toplu işlemlerin durumunu öğrenmek için yeterlidir.

Aşağıdaki tabloda, her yöntemin kabul ettiği kapsam gösterilmektedir:

Yöntem 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 ✓

En az ayrıcalık ilkesine uyun: Yalnızca karantinayı izleyen entegrasyonlar için salt okuma kapsamını isteyin.

Bir istek, kabul edilen bir kapsam içermeyen jeton kullanıyorsa API, ACCESS_TOKEN_SCOPE_INSUFFICIENT nedeniyle 403 hatası döndürür.

Hizmet hesabı oluşturma

  1. Google Cloud Console'da IAM & Admin > Service Accounts (IAM ve Yönetici > Hizmet Hesapları) bölümüne gidin ve API'yi etkinleştirdiğiniz Google Cloud projesini seçin.
  2. Hizmet hesabı oluştur'u tıklayın, quarantine-api-service-account gibi bir ad girin ve Oluştur ve devam et'i tıklayın. Hizmet hesabına herhangi bir IAM rolü atamanız gerekmez. Bitti'yi tıklayın.
  3. Hizmet hesabını açın ve Ayrıntılar sekmesinde OAuth 2 istemci kimliğini kopyalayın. 21 haneli bir sayıdır (ör. 109876543210987654321). Bu kimliğe bir sonraki bölümde ihtiyacınız olacak.
  4. Keys (Anahtarlar) sekmesinde Add key > Create new key'i (Anahtar ekle > Yeni anahtar oluştur) tıklayın, JSON'u seçin ve Create'i (Oluştur) tıklayın. İndirilen JSON anahtar dosyasını güvenli bir şekilde saklayın.

Daha fazla bilgi için Hizmet hesabı için kimlik bilgileri oluşturma başlıklı makaleyi inceleyin.

Alan genelinde yetki verme

Hizmet hesabını, Google Workspace hesabınızdaki Yönetici Karantinası API kapsamlarına erişmesi için yetkilendirin:

  1. Google Yönetici Konsolu'nda süper yönetici olarak oturum açın.
  2. Güvenlik > Erişim ve veri denetimi > API denetimleri'ne gidin.
  3. Alan genelinde yetki bölümünde Alan genelinde yetkiyi yönet'i tıklayın.
  4. Yeni ekle'yi tıklayın.
  5. İstemci Kimliği alanına hizmet hesabının OAuth 2.0 istemci kimliğini girin. Hizmet hesabının e-posta adresini girmeyin.

  6. OAuth kapsamları alanına aşağıdaki kapsamlardan birini girin:

    • Okuma ve yazma erişimi için: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Salt okuma erişimi için: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Yetkilendir'i tıklayın.

Ayrıntılı bilgi için Alan genelinde yetkiyle API erişimini kontrol etme başlıklı makaleyi inceleyin.

Erişim jetonu alma

Hizmet hesabı, API'yi çağırmak için jeton isteğinin subject (sub) talebini yöneticinin e-posta adresine ayarlayarak yönetici kimliğine bürünür. Yöneticinin gerekli yönetici ayrıcalığına sahip olması gerekir.

Aşağıdaki Python örneğinde, erişim jetonu almak için google-auth kitaplığı kullanılmaktadır:

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

Jetonu her isteğin Authorization üstbilgisinde gönderin:

Authorization: Bearer ACCESS_TOKEN

Erişim jetonlarının süresi bir saat sonra dolar. Jetonları uzun süre önbelleğe almak yerine her istek grubundan önce kimlik bilgilerini yenileyin.

Yetkilendirme hatalarını giderme

HTTP durumu Neden Çözünürlük
401 UNAUTHENTICATED Authorization üstbilgisi eksik veya jeton hatalı biçimlendirilmiş ya da jetonun süresi dolmuş. Yeni bir erişim jetonu alın ve bunu hamiline ait jeton olarak ekleyin.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Jeton, yöntemin kabul ettiği bir kapsam içermiyor. Yayınlama ve reddetme yöntemleri için https://www.googleapis.com/auth/gmail.admin.quarantine kapsamını isteyin ve kapsamın Yönetici Konsolu'nda yetkilendirildiğinden emin olun.
403 PERMISSION_DENIED Kimliğine bürünülen yöneticinin yönetici karantinası ayrıcalığı yok veya iletiyi barındıran karantinaya erişimi yok. Yöneticiye Yönetici Karantinasına erişim veya Kısıtlı karantinalara erişim ayrıcalığı verin.
Her yöntemde 403 SERVICE_DISABLED veya 404 NOT_FOUND API, Cloud projesinde etkinleştirilmemiş veya proje, Geliştirici Önizleme Programı'na kayıtlı değil. API'yi etkinleştirin ve Google Workspace Geliştirici Önizleme Programı'na kaydınızı onaylayın.

Sonraki adımlar