서비스 계정을 사용하여 Apps Script 프로젝트로 인증

이 가이드에서는 Apps Script에서 API를 호출할 때 서비스 계정으로 인증하는 방법을 설명합니다.

서비스 계정은 사용자가 아닌 애플리케이션에서 사용하는 특별한 유형의 계정입니다. 서비스 계정을 사용하여 로봇 계정으로 데이터에 액세스하거나 작업을 실행하거나 Google Workspace 또는 Cloud ID 사용자를 대신하여 데이터에 액세스할 수 있습니다. 자세한 내용은 서비스 계정 이해를 참조하세요.

Google Workspace API 인증에 대한 개요는 액세스 사용자 인증 정보 만들기를 참고하세요.

Apps Script에서 서비스 계정을 사용해야 하는 경우

ScriptApp.getOAuthToken()와 같은 다른 인증 방법 대신 서비스 계정 인증을 사용하는 것이 좋은 몇 가지 이유는 다음과 같습니다.

Google Cloud API 및 서비스의 성능 향상: 많은 Google Cloud API가 서비스 계정 인증을 위해 설계되었습니다. 서비스 계정은 대부분의 API와 상호작용하는 더 통합되고 안정적이며 안전한 방법을 제공할 수도 있습니다.
분리된 권한: 서비스 계정에는 사용자로부터 분리된 자체 권한이 있습니다. 다른 사용자와 Apps Script 프로젝트를 공유하면 ScriptApp.getOAuthToken() 인증 방법이 실패할 수 있습니다. 서비스 계정을 사용하면 스크립트를 공유하고 Google Workspace 부가기능으로 게시할 수 있습니다.
자동화된 스크립트 및 장기 실행 작업: 서비스 계정을 사용하면 사용자 입력 없이 자동화된 스크립트, 일괄 처리 또는 백그라운드 작업을 실행할 수 있습니다.
보안 강화 및 최소 권한의 원칙: 서비스 계정에 특정 권한을 부여하여 필요한 리소스에만 액세스할 수 있습니다. 이는 보안 위험을 낮추는 최소 권한의 원칙을 따릅니다. ScriptApp.getOAuthToken()를 사용하면 스크립트에 모든 사용자 권한이 부여되는 경우가 많으며 이는 너무 광범위할 수 있습니다.
중앙 집중식 액세스 관리: 서비스 계정은 Google Cloud의 Identity and Access Management (IAM)를 사용하여 관리됩니다. IAM을 사용하면 Google Workspace 조직에서 Apps Script 프로젝트 내 인증된 서비스에 대한 액세스를 관리할 수 있습니다.

기본 요건

Google Cloud 프로젝트
Cloud 프로젝트에서 서비스 계정 사용자 인증 정보를 사용하여 인증하려는 API를 사용 설정합니다.
서비스 계정에 역할을 할당하려면 최고 관리자 권한이 있어야 합니다.

서비스 계정 만들기

Cloud 프로젝트에서 서비스 계정을 만듭니다.

Google Cloud 콘솔

Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.
서비스 계정으로 이동
서비스 계정 만들기를 클릭합니다.
서비스 계정 세부정보를 입력한 다음 만들고 계속하기를 클릭합니다.
참고: 기본적으로 Google은 고유한 서비스 계정 ID를 만듭니다. ID를 변경하려면 서비스 계정 ID 필드에서 ID를 수정하세요.
선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
계속을 클릭합니다.
선택사항: 이 서비스 계정으로 작업을 관리하고 수행할 수 있는 사용자 또는 그룹을 입력합니다. 자세한 내용은 서비스 계정 명의 도용 관리를 참고하세요.
완료를 클릭합니다. 서비스 계정의 이메일 주소를 기록해 둡니다.

gcloud CLI

서비스 계정을 만듭니다.

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

선택사항: 서비스 계정에 역할을 할당하여 Google Cloud 프로젝트의 리소스에 대한 액세스 권한을 부여합니다. 자세한 내용은 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.

서비스 계정에 역할 할당

최고 관리자 계정으로 사전 설정된 역할 또는 맞춤 역할을 서비스 계정에 할당해야 합니다.

Google 관리 콘솔에서 메뉴 > 계정 > 관리자 역할로 이동합니다.

관리자 역할로 이동
할당하려는 역할을 가리킨 다음 관리자 할당을 클릭합니다.
서비스 계정 할당을 클릭합니다.
서비스 계정의 이메일 주소를 입력합니다.
추가> 역할 할당을 클릭합니다.

서비스 계정의 사용자 인증 정보 만들기

공개/비공개 키 쌍 형식의 사용자 인증 정보를 획득해야 합니다. 이 사용자 인증 정보는 코드에서 앱 내 서비스 계정 작업을 승인하는 데 사용됩니다.

서비스 계정의 사용자 인증 정보를 가져오려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 서비스 계정으로 이동합니다.
서비스 계정으로 이동
서비스 계정을 선택합니다.
키 > 키 추가 > 새 키 만들기를 클릭합니다.
JSON을 선택한 다음 만들기를 클릭합니다.
새 공개 키/비공개 키 쌍이 생성되어 새 파일로 기기에 다운로드됩니다. 다운로드한 JSON 파일을 작업 디렉터리에 credentials.json로 저장합니다. 이 파일은 이 키의 유일한 사본입니다. 키를 안전하게 저장하는 방법을 자세히 알아보려면 서비스 계정 키 관리를 참고하세요.
닫기를 클릭합니다.

클라우드 프로젝트 번호 복사

Google Cloud 콘솔에서 메뉴 > IAM 및 관리자 > 설정으로 이동합니다.
IAM & 관리자 설정으로 이동
프로젝트 번호 필드에서 값을 복사합니다.

Apps Script 프로젝트에서 서비스 계정 인증 설정

이 섹션에서는 Cloud 프로젝트의 서비스 계정 사용자 인증 정보를 Apps Script 프로젝트에 추가하는 방법을 설명합니다.

Apps Script에서 Cloud 프로젝트 설정

Apps Script로 이동하여 프로젝트를 열거나 만듭니다.

Apps Script 열기
Apps Script 프로젝트에서 프로젝트 설정 을 클릭합니다.
Google Cloud Platform(GCP) 프로젝트에서 프로젝트 변경을 클릭합니다.
GCP 프로젝트 번호에 Google Cloud 프로젝트 번호를 붙여넣습니다.
프로젝트 설정을 클릭합니다.

사용자 인증 정보를 스크립트 속성으로 저장

Apps Script 프로젝트 설정에 스크립트 속성으로 저장하여 서비스 계정 사용자 인증 정보를 안전하게 저장합니다.

이전 섹션에서 만든 서비스 계정 JSON 파일 (credentials.json)의 콘텐츠를 복사합니다.
Apps Script 프로젝트에서 프로젝트 설정 으로 이동합니다.
프로젝트 설정 페이지에서 스크립트 속성으로 이동하여 스크립트 속성 추가를 클릭하고 다음을 입력합니다.
- 속성 필드에 SERVICE_ACCOUNT_KEY를 입력합니다.
- 값 필드에 JSON 키 파일의 콘텐츠를 붙여넣습니다.
스크립트 속성 저장을 클릭합니다.

OAuth2 라이브러리 추가

OAuth2 인증 흐름을 처리하려면 Apps Script 라이브러리 apps-script-oauth2를 사용하면 됩니다.

Apps Script 프로젝트에 라이브러리를 추가하려면 다음 단계를 따르세요.

Apps Script 편집기에서 왼쪽의 라이브러리 옆에 있는 라이브러리 추가 를 클릭합니다.
스크립트 ID 필드에 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF를 입력합니다.
조회를 클릭합니다.
최신 버전을 선택한 다음 추가를 클릭합니다.

서비스 계정 사용자 인증 정보를 사용하여 API 호출

Apps Script 프로젝트의 서비스 계정 인증 정보를 사용하려면 다음 함수 getServiceAccountService()를 사용하면 됩니다.

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

SCOPE를 API를 호출하는 데 필요한 승인 범위로 바꿉니다. 스크립트는 이전 단계에서 SERVICE_ACCOUNT_KEY 스크립트 속성으로 저장한 서비스 계정 사용자 인증 정보를 사용합니다.

그런 다음 UrlFetch 서비스의 다음 예와 같이 이러한 사용자 인증 정보를 사용하여 API를 호출할 수 있습니다.

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

API_URL를 호출하는 HTTP 엔드포인트로 바꿉니다.