Groups API 설정

이 페이지에서는 Cloud Identity Groups API를 설정하는 방법을 설명합니다.

시작하기 전에

Enable the Cloud Identity API.

Enable the API

클라이언트 라이브러리 설치

클라이언트 라이브러리를 설치하려면 다음 명령어를 실행합니다.

Python

Python 개발 환경 설정에 관한 자세한 내용은 Python 개발 환경 설정 가이드를 참조하세요.

pip install --upgrade google-api-python-client google-auth \
  google-auth-oauthlib google-auth-httplib2

Groups API를 사용하여 인증

Groups API에서 최종 사용자로 인증, 도메인 전체 위임 없이 서비스 계정 그룹 관리자로 인증 또는 도메인 전체 위임을 사용하여 서비스 계정으로 인증을 수행할 수 있습니다. 다음 섹션에서는 각 메서드에 대해 설명합니다.

최종 사용자로 인증

관리자가 아니거나 관리자가 아닌 사용자를 대신하여 앱을 빌드하는 경우 웹 서버 애플리케이션용 OAuth 2.0 사용을 참조한 다음 아래의 클라이언트 인스턴스화 섹션을 참조하세요.

도메인 전체 위임 없이 서비스 계정으로 인증

서비스 계정을 사용하고 이를 사용하여 그룹 관리자로 그룹을 관리하려면 아래 단계를 완료하세요. 이 인증 방법은 서비스 계정의 작업을 감사 로그에 서비스 계정으로 등록하려는 경우에 사용해야 합니다.

서비스 계정에 관리자 역할 할당

먼저 Admin SDK Roles 및 Role Assignment API를 사용하여 위임할 서비스 계정에 Google Workspace 그룹 관리자 역할(그룹 관리자)을 할당해야 합니다. 이 단계를 통해 서비스 계정에 도메인 그룹에 대한 액세스 권한을 부여하지만 다른 리소스는 부여하지 않습니다.

Admin SDK API를 사용하여 역할 관리에 대한 일반적인 정보는 역할 관리 가이드를 참조하세요. 아래 단계에 따라 서비스 계정에 대해 그룹 관리자 역할을 할당합니다.

  1. Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

    서비스 계정으로 이동

  2. Groups API에 사용할 서비스 계정의 이름을 클릭합니다.

  3. 서비스 계정의 고유 ID를 복사합니다.

  4. Admin SDK Roles API를 호출하여 그룹 관리자의 roleId를 식별합니다. Admin SDK 문서의 API 탐색기를 사용하여 이를 수행할 수 있습니다.

  5. 다음 요청 본문으로 Role Assignments API를 호출합니다.

    {
      "assignedTo": "SERVICE_ACCOUNT_UNIQUE_ID"
      "roleId": "ROLE_ID"
      "scopeType": "CUSTOMER"
      "kind": "admin#directory#roleAssignment"
    }
    

서비스 계정 인증 및 승인

이제 서비스 계정에 그룹 관리자 역할이 지정되었습니다. 두 번째 단계는 서비스 계정의 OAuth 인증 프로세스를 완료하는 것입니다.

  • Google Cloud에서 앱을 개발하고 서비스 계정이 프로젝트의 소유자인 경우 애플리케이션 기본 사용자 인증 정보를 대신 사용할 수 있습니다. 그러면 프로세스가 간소화됩니다. 자세한 내용은 서비스 계정으로 인증을 참조하세요.

  • 서비스 계정이 프로젝트의 소유자가 아닌 경우 아래 안내를 따르세요.

어느 경우든 Cloud Identity Groups API의 적용 범위는 https://www.googleapis.com/auth/cloud-identity.groups입니다.

  1. 방금 만든 사용자 인증 정보를 사용하여 액세스 토큰을 생성합니다.

    자바

    GoogleCredential credential = new GoogleCredential.Builder()
        .setTransport(httpTransport)
        .setJsonFactory(JSON_FACTORY)
        .setServiceAccountId(emailAddress)
        .setServiceAccountPrivateKeyFromP12File(new File("MyProject.p12"))
        .setServiceAccountScopes(ImmutableList.of("https://www.googleapis.com/auth/cloud-identity.groups"))
        .build();
    

    생성된 액세스 토큰을 보관합니다.

서비스 계정의 액세스 토큰을 생성하는 전체 코드

자바

GenerateServiceAccountOauth2Token.java

package com.google.tools;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.common.collect.ImmutableList;
import java.io.FileInputStream;

/** Command line tool to generate Oauth2 token for a given service account
/** without domain wide delegation. */
public final class GenerateServiceAccountOauth2Token {

  private static final ImmutableList<String> API_SCOPES =
      ImmutableList.of(
          "https://www.googleapis.com/auth/cloud-identity.groups",
          "https://www.googleapis.com/auth/admin.directory.group",
          "https://www.googleapis.com/auth/admin.directory.group.member",
          "https://www.googleapis.com/auth/apps.groups.settings");

  public static void main(final String[] args) throws Exception {
    String accessToken = getTokenFromJsonKey();
    System.out.println("Token: " + accessToken);
  }

  private static String getTokenFromJsonKey() throws Exception {
    GoogleCredential credential =
        GoogleCredential.fromStream(
            new FileInputStream(
                "<path for json file>"),
            new NetHttpTransport(),
            GsonFactory.getDefaultInstance());
    System.out.println("ServiceAccountId=" + credential.getServiceAccountId());

    HttpTransport httpTransport = new NetHttpTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    GoogleCredential.Builder builder =
        new GoogleCredential.Builder()
            .setServiceAccountPrivateKey(credential.getServiceAccountPrivateKey())
            .setServiceAccountPrivateKeyId(credential.getServiceAccountPrivateKeyId())
            .setServiceAccountId(credential.getServiceAccountId())
            .setTransport(httpTransport)
            .setJsonFactory(jsonFactory)
            .setServiceAccountScopes(API_SCOPES)
            .setClock(credential.getClock());
    credential = builder.build();
    if (!credential.refreshToken()) {
      throw new Exception("Failed to fetch access token.");
    }
    return credential.getAccessToken();
  }
}

빌드 규칙

java_binary(
  name = "generate_oauth2_token",
  srcs = ["GenerateServiceAccountOauth2Token.java"],
  main_class = "com.google.tools.GenerateServiceAccountOauth2Token",
  deps = [
      "//java/com/google/api/client/googleapis/auth/oauth2",
      "//java/com/google/api/client/googleapis/javanet",
      "//java/com/google/api/client/http",
      "//java/com/google/api/client/http/javanet",
      "//java/com/google/common/base",
      "//java/com/google/common/collect",
      "//third_party/java/google_http_java_client:gson",
      "//third_party/java/google_http_java_client:json",
  ],
)

서비스 계정 테스트

  1. 그룹을 만들고 사용자를 추가하고 그룹 설정을 업데이트하는 등 서비스 계정 사용자 인증 정보로 Groups API 호출을 시도해 봅니다.

  2. Google 관리 콘솔 보고서 섹션에서 감사 로그를 확인합니다. 서비스 계정이 그룹 관련 변경사항의 작업 수행자로 표시되어야 합니다. 자세한 내용은 이벤트 로깅을 참조하세요.

    또는 API를 사용하여 감사 로그에 액세스할 수 있습니다. Reports API 탐색기를 사용하여 확인하려면 관리자 OAuth 사용자 인증 정보를 사용해야 합니다.

도메인 전체 위임을 사용하여 서비스 계정으로 인증

ID 그룹을 관리하는 관리자이거나 관리자를 대신하여 Google 그룹스를 관리할 수 있는 도메인 전체 권한을 계정에 제공하려면 서비스 계정으로 인증해야 합니다.

도메인 전체 위임 설정에 대한 자세한 내용은 도메인 전체 위임으로 API 액세스 제어를 참조하세요.

서비스 계정으로 인증하려면 서버 애플리케이션에 서버용 OAuth 2.0 사용을 참조하세요. 코드에서 사용자 인증 정보를 초기화할 때 사용자 인증 정보의 with_subject()를 호출하여 서비스 계정이 작동할 이메일 주소를 지정합니다. 예를 들면 다음과 같습니다.

Python

credentials = service_account.Credentials.from_service_account_file(
  SERVICE_ACCOUNT_FILE, scopes=SCOPES).with_subject(delegated_email)

클라이언트 인스턴스화

다음 예시에서는 서비스 계정 사용자 인증 정보를 사용하여 클라이언트를 인스턴스화하는 방법을 보여줍니다. 대신 최종 사용자로 인증하려면 credential 객체는 서비스 계정의 웹 서버 애플리케이션용 OAuth 2.0 사용에서 획득한 credential 획득을 교체합니다.

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.groups']
SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
  delegated_credentials = credentials.with_subject('user@example.org')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service

이제 Groups API를 호출할 수 있습니다.