Apps Script 자동화: Apps Script 권한 오류 해결 방법

어제까지 잘 작동하던 Apps Script 자동화가 갑자기 ‘Authorization is required to perform that action’ 오류를 내뱉으며 멈출 때가 있습니다. 이 메시지는 스크립트가 구글 시트, Gmail, 드라이브 같은 다른 서비스에 접근하는 데 필요한 ‘허가’를 받지 못했다는 명확한 신호입니다. 코드를 아무리 수정해도 해결되지 않는 이 문제는 대부분 권한 설정에 원인이 있습니다.

바쁜 분들을 위한 3줄 요약

오류 메시지를 정확히 파악하고, 매니페스트 파일(appsscript.json)의 OAuth 스코프 선언을 최우선으로 검토하세요.
스크립트를 실행하는 사용자 계정과 배포 유형에 따라 권한 승인 절차를 다시 수행해야 할 수 있습니다.
고급 Google 서비스 사용 시에는 스코프 추가 외에 해당 서비스 활성화 여부도 반드시 확인하십시오.

바쁜 분들을 위해 핵심 해결 순서를 먼저 요약합니다.

오류 메시지를 정확히 파악하고, 매니페스트 파일(appsscript.json)의 OAuth 스코프 선언을 최우선으로 검토하세요.
스크립트를 실행하는 사용자 계정과 배포 유형에 따라 권한 승인 절차를 다시 수행해야 할 수 있습니다.
고급 Google 서비스(Gmail, Drive API 등) 사용 시에는 스코프 추가 외에 해당 서비스 활성화 여부도 반드시 확인해야 합니다.

Apps Script 자동화 핵심 정리

왜 Apps Script는 ‘권한 오류’를 뱉어낼까요?

Apps Script는 보안을 위해 사용자의 데이터를 마음대로 접근할 수 없습니다. 스프레드시트 수정, 메일 발송, 드라이브 파일 생성 같은 민감한 작업을 하려면, 사용자에게 “이런 작업을 실행해도 될까요?”라고 명시적으로 물어보고 허락(권한 승인)을 받아야 합니다. 이 허락의 범위를 ‘스코프(Scope)’라고 부릅니다.

예를 들어, ‘스프레드시트 읽기’ 권한만 부여받은 스크립트가 특정 셀에 값을 ‘쓰려고’ 시도하면 권한 범위를 벗어났기 때문에 오류가 발생합니다. 권한 오류의 일반적인 원인은 다음과 같습니다.

필요한 스코프 누락: 스크립트 기능에 필요한 권한(스코프)이 매니페스트 파일에 선언되지 않았습니다.
사용자 권한 미승인: 스크립트를 실행하는 사용자가 권한 요청 화면에서 ‘거부’를 눌렀거나 창을 닫았습니다.
잘못된 계정으로 실행: 여러 구글 계정에 로그인된 상태에서, 권한을 부여한 계정이 아닌 다른 계정으로 스크립트가 실행되었습니다.
배포 설정 문제: 웹 앱으로 배포 시 ‘실행 주체’나 ‘액세스 권한’ 설정이 실제 사용 환경과 맞지 않습니다.

권한 오류, 어디서부터 찾아야 할까요?

문제를 해결하는 가장 빠른 길은 오류 기록을 직접 확인하는 것입니다. 막연하게 추측하기보다 로그를 먼저 확인하세요.

실행 로그 (Execution Logs) 확인: Apps Script 편집기 왼쪽 메뉴에서 ‘실행’ (시계 모양 아이콘)을 클릭하세요. 최근 실행 기록 목록이 나타나며, ‘실패’ 상태인 항목을 클릭하면 어떤 함수, 몇 번째 줄에서 어떤 오류가 발생했는지 바로 볼 수 있습니다. ‘Authorization is required…’ 메시지가 보인다면 100% 권한 문제입니다.
Cloud Logging 활용: 단순한 권한 오류가 아니거나, 웹 앱처럼 복잡한 환경에서 발생하는 문제는 ‘Google Cloud Platform(GCP)’ 프로젝트에 연결된 ‘Cloud Logging’에서 더 상세한 원인을 추적할 수 있습니다. 스크립트 편집기의 ‘프로젝트 설정’에서 GCP 프로젝트 번호를 확인할 수 있습니다.

5단계로 해결하는 Apps Script 권한 오류

오류를 확인했다면, 아래 5단계 순서에 따라 체계적으로 문제를 해결할 수 있습니다.

1단계: 오류 메시지 정확히 파악하기
실행 로그에서 오류가 발생한 코드 라인을 확인합니다. 예를 들어 `GmailApp.sendEmail()` 함수에서 오류가 났다면 Gmail 발송 관련 권한 문제일 가능성이 매우 높습니다. 문제의 원인을 특정하는 첫 단추입니다.
2단계: 매니페스트 파일(appsscript.json) 검토
편집기 왼쪽 ‘프로젝트 설정’ (톱니바퀴 아이콘)에서 ‘편집기에 “appsscript.json” 매니페스트 파일 표시’를 체크합니다. 편집기 파일 목록에 `appsscript.json` 파일이 나타나면 열어보세요. `oauthScopes` 목록 안에 스크립트 실행에 필요한 모든 권한이 문자열 형태로 들어있는지 확인하고, 없다면 추가합니다.

“oauthScopes”: [
“https://www.googleapis.com/auth/spreadsheets”,
“https://www.googleapis.com/auth/gmail.send”,
“https://www.googleapis.com/auth/drive.file”
]
3단계: 스크립트 재승인
코드를 수정했거나 스코프를 변경했다면 권한을 다시 받아야 합니다. 편집기 상단 툴바에서 함수를 선택하고 ‘실행’ 버튼을 누르세요. 권한 승인이 필요한 경우, 팝업창이 뜨며 다시 승인 절차를 진행할 수 있습니다. 이때, 반드시 올바른 구글 계정으로 로그인했는지 확인하고 ‘허용’을 클릭해야 합니다.
4단계: 사용자 계정 및 실행 주체 확인
스크립트를 웹 앱으로 배포했다면 ‘배포’ > ‘배포 관리’ 메뉴에서 현재 배포 버전을 클릭해 설정을 확인하세요. ‘실행 주체’가 ‘나(개발자 계정)’로 되어 있다면 스크립트는 항상 개발자 권한으로 실행됩니다. 만약 ‘웹 앱에 액세스하는 사용자’로 설정했다면, 해당 웹 앱을 사용하는 모든 팀원이 각자 처음 접속할 때 권한 승인 절차를 거쳐야 합니다.
5단계: 고급 Google 서비스 및 GCP 프로젝트 확인
Drive API, Calendar API, Gmail API 등 ‘고급 Google 서비스’를 사용한다면 스코프 추가만으로는 부족할 수 있습니다. 먼저 편집기 왼쪽 ‘서비스’ 메뉴에서 해당 서비스를 추가했는지 확인하고, 연결된 GCP 프로젝트의 ‘API 및 서비스’ 대시보드에서 해당 API가 ‘사용 설정’ 상태인지 반드시 확인해야 합니다.

흔히 저지르는 실수와 실제 해결 사례

이론을 알아도 실제 상황에서는 실수하기 쉽습니다. 자주 발생하는 실수와 해결 사례를 통해 실패를 예방하세요.

실수 1: 스코프 잘못 이해하기
상황: 처음엔 시트 데이터 조회만 하려고 `spreadsheets.readonly` 스코프만 추가했습니다. 이후 기능을 확장해 `appendRow()` 함수로 데이터를 추가하는 코드를 넣자마자 오류가 발생했습니다.
해결: `appsscript.json` 파일의 스코프를 읽기/쓰기가 모두 가능한 `https://www.googleapis.com/auth/spreadsheets`로 변경하고 스크립트를 다시 실행해 권한을 재승인했습니다.
실수 2: 모든 사용자가 자동으로 권한을 가질 거라 착각하기
상황: 팀원들이 사용할 업무 요청 웹 앱을 만들어 공유했습니다. 실행 주체를 ‘웹 앱에 액세스하는 사용자’로 설정했는데, 팀원들이 접속할 때마다 권한 오류가 난다며 문의가 빗발쳤습니다.
해결: 웹 앱은 각 사용자 브라우저에서 실행되므로, 모든 사용자가 처음 접속 시 나타나는 권한 승인 화면에서 직접 ‘허용’을 클릭해야 정상 작동한다고 안내했습니다.
실수 3: ‘고급 서비스’ 활성화 누락
상황: `DriveApp` 기본 함수 대신, 더 세밀한 제어를 위해 Drive API의 `Drive.Files.insert()` 코드를 사용했습니다. 하지만 ‘Drive is not defined’ 또는 권한 관련 오류가 발생했습니다.
해결: Apps Script 편집기 ‘서비스’ 메뉴에서 ‘Drive API’를 추가하고, 연결된 GCP 프로젝트에서 ‘Google Drive API’를 검색하여 ‘사용 설정’ 버튼을 눌러 API를 활성화했습니다.