Autoryzacja za pomocą przekazywania dostępu w całej domenie

Interfejs Mail Admin Quarantine API jest przeznaczony do automatyzacji po stronie serwera, takich jak potoki zabezpieczeń i integracje z systemami SIEM lub SOAR. Te automatyzacje uwierzytelniają się za pomocą konta usługi Google Cloud, które używa przekazywania dostępu w całej domenie, aby działać w imieniu administratora Google Workspace, który ma wymagane uprawnienia administratora.

Na tej stronie dowiesz się, jakich zakresów OAuth 2.0 wymaga interfejs API oraz jak skonfigurować konto usługi i uzyskać token dostępu.

Zakresy OAuth 2.0

Interfejs Admin Quarantine API używa tych zakresów protokołu OAuth 2.0:

Zakres Znaczenie
https://www.googleapis.com/auth/gmail.admin.quarantine Wyświetlanie wiadomości w kwarantannie i zarządzanie nimi. Wymagane do zatwierdzania i odrzucania wiadomości, pojedynczo lub zbiorczo.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Wyświetlanie wiadomości w kwarantannie. Wystarczająca do wyświetlania, wyszukiwania i pobierania wiadomości, wyświetlania i pobierania kwarantann oraz uzyskiwania stanu operacji zbiorczych.

W tabeli poniżej znajdziesz zakresy akceptowane przez poszczególne metody:

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

Zastosuj zasadę jak najmniejszych uprawnień: poproś o zakres tylko do odczytu w przypadku integracji, które tylko monitorują kwarantannę.

Jeśli żądanie używa tokena, który nie zawiera akceptowanego zakresu, interfejs API zwraca błąd 403 z powodem ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Tworzenie konta usługi

  1. W konsoli Google Cloud otwórz Uprawnienia i administracja > Konta usługi i wybierz projekt w chmurze Google Cloud, w którym interfejs API został włączony.
  2. Kliknij Utwórz konto usługi, wpisz nazwę, na przykład quarantine-api-service-account, i kliknij Utwórz i kontynuuj. Nie musisz przypisywać do konta usługi żadnych ról uprawnień. Kliknij Gotowe.
  3. Otwórz konto usługi i na karcie Szczegóły skopiuj identyfikator klienta OAuth 2. Jest to 21-cyfrowy numer, np. 109876543210987654321. Będzie on potrzebny w następnej sekcji.
  4. Na karcie Klucze kliknij Dodaj klucz > Utwórz nowy klucz, wybierz JSON i kliknij Utwórz. Pobrany plik klucza JSON przechowuj w bezpiecznym miejscu.

Więcej informacji znajdziesz w artykule Tworzenie danych logowania do konta usługi.

Autoryzowanie przekazywania dostępu w całej domenie

Autoryzuj konto usługi, aby uzyskać dostęp do zakresów interfejsu Admin Quarantine API na koncie Google Workspace:

  1. Zaloguj się w konsoli administracyjnej Google jako superadministrator.
  2. Otwórz Bezpieczeństwo > Dostęp do danych i kontrola nad nimi > Dostęp do interfejsów API.
  3. W sekcji Przekazywanie dostępu w całej domenie kliknij Zarządzaj przekazywaniem dostępu w całej domenie.
  4. Kliknij Dodaj domenę.
  5. W polu Identyfikator klienta wpisz identyfikator klienta OAuth 2.0 konta usługi. Nie wpisuj adresu e-mail konta usługi.

  6. W polu Zakresy protokołu OAuth wpisz jeden z tych zakresów:

    • Dostęp do odczytu i zapisu: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Dostęp tylko do odczytu: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Kliknij Autoryzuj.

Więcej informacji znajdziesz w artykule Kontrola dostępu do interfejsów API przy użyciu przekazywania dostępu w całej domenie.

Uzyskiwanie tokena dostępu

Aby wywołać interfejs API, konto usługi przyjmuje tożsamość administratora, ustawiając parametr subject (sub) żądania tokena na adres e-mail administratora. Administrator musi mieć wymagane uprawnienia administratora.

Poniższy przykład w Pythonie używa biblioteki google-auth do uzyskania tokena dostępu:

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

Wyślij token w nagłówku Authorization każdego żądania:

Authorization: Bearer ACCESS_TOKEN

Tokeny dostępu wygasają po godzinie. Odświeżaj dane logowania przed każdą partią żądań, zamiast przechowywać tokeny w pamięci podręcznej przez dłuższy czas.

Rozwiązywanie problemów z błędami autoryzacji

Stan HTTP Przyczyna Rozdzielczość
401 UNAUTHENTICATED Brakuje nagłówka Authorization lub token jest nieprawidłowy albo wygasł. Uzyskaj nowy token dostępu i dołącz go jako token okaziciela.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Token nie zawiera zakresu akceptowanego przez metodę. Poproś o zakres https://www.googleapis.com/auth/gmail.admin.quarantine dla metod zwalniania i odrzucania oraz upewnij się, że zakres jest autoryzowany w konsoli administracyjnej.
403 PERMISSION_DENIED Administrator, pod którego podszywa się użytkownik, nie ma uprawnień administratora kwarantanny lub nie ma dostępu do kwarantanny, w której znajduje się wiadomość. Przyznaj administratorowi uprawnienie Dostęp do kwarantanny administracyjnej lub Dostęp do kwarantann objętych ograniczeniami.
403 SERVICE_DISABLED lub 404 NOT_FOUND w przypadku każdej metody Interfejs API nie jest włączony w projekcie w chmurze lub projekt nie jest zarejestrowany w programie wersji przedpremierowej dla programistów. Włącz interfejs API i potwierdź rejestrację w programie wersji przedpremierowej Google Workspace dla deweloperów.

Dalsze kroki