도메인 전체 위임으로 승인

Mail Admin Quarantine API는 보안 파이프라인, SIEM 또는 SOAR 통합과 같은 서버 측 자동화를 위해 설계되었습니다. 이러한 자동화는 도메인 전체 위임을 사용하여 필요한 관리자 권한을 보유한 Google Workspace 관리자를 대신하는 Google Cloud 서비스 계정으로 인증합니다.

이 페이지에서는 API에 필요한 OAuth 2.0 범위와 서비스 계정을 구성하고 액세스 토큰을 가져오는 방법을 설명합니다.

OAuth2 범위

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는 ACCESS_TOKEN_SCOPE_INSUFFICIENT 이유와 함께 403 오류를 반환합니다.

서비스 계정 만들기

  1. Google Cloud 콘솔에서 IAM 및 관리자 > 서비스 계정으로 이동하고 API를 사용 설정한 Google Cloud 프로젝트를 선택합니다.
  2. 서비스 계정 만들기를 클릭하고 quarantine-api-service-account과 같은 이름을 입력한 후 만들고 계속하기를 클릭합니다. 서비스 계정에 IAM 역할을 부여할 필요가 없습니다. 완료를 클릭합니다.
  3. 서비스 계정을 열고 세부정보 탭에서 OAuth 2 클라이언트 ID를 복사합니다. 21자리 숫자입니다(예: 109876543210987654321). 다음 섹션에서 이 ID가 필요합니다.
  4. 키 탭에서 키 추가 > 새 키 만들기를 클릭하고 JSON을 선택한 후 만들기를 클릭합니다. 다운로드한 JSON 키 파일을 안전하게 저장합니다.

자세한 내용은 서비스 계정의 사용자 인증 정보 만들기를 참조하세요.

도메인 전체 위임 승인

Google Workspace 계정에서 관리자 스팸 격리 저장소 API 범위에 액세스하도록 서비스 계정을 승인합니다.

  1. 최고 관리자로 Google 관리 콘솔에 로그인합니다.
  2. 보안 > 액세스 및 데이터 관리 > API 관리로 이동합니다.
  3. 도메인 전체 위임에서 도메인 전체 위임 관리를 클릭합니다.
  4. 새로 추가를 클릭합니다.
  5. 클라이언트 ID 필드에 서비스 계정의 OAuth 2.0 클라이언트 ID를 입력합니다. 서비스 계정의 이메일 주소를 입력하지 마세요.

  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 헤더가 누락되었거나 토큰의 형식이 잘못되었거나 만료되었습니다. 새 액세스 토큰을 가져와 Bearer 토큰으로 포함합니다.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT 토큰에 메서드가 허용하는 범위가 포함되어 있지 않습니다. release 및 deny 메서드에 대해 https://www.googleapis.com/auth/gmail.admin.quarantine 범위를 요청하고 관리 콘솔에서 범위가 승인되었는지 확인합니다.
403 PERMISSION_DENIED 명의를 도용당한 관리자에게 관리 스팸 격리 저장소 권한이 없거나 메일이 보관된 스팸 격리 저장소에 액세스할 수 없습니다. 관리자에게 관리 스팸 격리 저장소 액세스 또는 제한된 스팸 격리 저장소에 액세스 권한을 부여합니다.
모든 메서드에 403 SERVICE_DISABLED 또는 404 NOT_FOUND Cloud 프로젝트에서 API가 사용 설정되지 않았거나 프로젝트가 개발자 프리뷰 프로그램에 등록되지 않았습니다. API를 사용 설정하고 Google Workspace 개발자 프리뷰 프로그램에 등록되어 있는지 확인합니다.

다음 단계