설치 매뉴얼
인증 방식 선택
구글 워크스페이스 앱은 서비스 계정과 도메인 전체 위임을 사용합니다. 아래 절차는 전체 위임 방식에 대한 설명입니다.
감사 로그 수집을 사용하지 않고 구글 스프레드시트 읽기·쓰기 기능만 사용하는 경우에는 사용자 계정 OAuth 방식으로 접속 프로파일을 구성할 수 있습니다. 이 경우 Admin SDK 활성화, 관리자 역할 생성, 도메인 전체 위임이 모두 필요하지 않습니다. 설정 절차는 사용자 계정 OAuth 방식으로 스프레드시트 연동 섹션을 참고하십시오.
서비스 계정 방식(전체 기능)
구글 워크스페이스 설정
고객 ID 확인
구글 워크스페이스 앱의 접속 프로파일을 구성하려면 구글 워크스페이스에서 고객 ID 정보가 필요합니다.
-
구글 워크스페이스 관리 콘솔에 로그인하세요.
-
계정 > 계정 설정으로 이동해 고객 ID를 확인해둡니다.
관리자 역할 생성
구글 워크스페이스 앱의 확장 명령어들은 관리자 권한이 필요합니다. 구글 워크스페이스 앱에 필요한 권한이 부여된 관리자 역할을 생성해 사용하세요.
-
계정 > 관리자 역할에서 새 역할 만들기 버튼을 클릭하세요.
-
역할 정보를 입력하세요. 이름(필수)과 설명(선택)은 사용자가 임의로 지정할 수 있습니다. 입력을 마친 후 계속 버튼을 클릭하세요.
-
부여할 권한을 체크하고 계속 버튼을 클릭하세요.
필요한 권한은 다음 표를 참고하세요.
권한 관련 확장 명령어 관리 콘솔 권한 > 서비스 > 알림 센터 > 전체 권한 > 보기 액세스 google-workspace-alerts 관리 콘솔 권한 > 도메인 설정 google-workspace-domains 관리 콘솔 권한 > 보고서 google-workspace-logs, google-workspace-meet-logs, google-workspace-sheets-values, google-workspace-write-values, google-workspace-admin-logs, google-workspace-login-logs Admin API 권한 > 도메인 관리 google-workspace-domains Admin API 권한 > 사용자 > 읽기 google-workspace-users Note위에 제시된 권한을 선택하면 부가적으로 다음 권한들도 자동으로 선택됩니다.
- (관리 콘솔 권한) 도메인 설정
- (Admin API 권한) 고객 관리 > 고객 읽기 > 고객 브랜딩 설정 읽기, 고객 온보딩 설정 읽기, 고객 프로필 설정 읽기, 고객 지원 설정 읽기, 고객 시간대 설정 읽기
- (Admin API 권한) 고객 관리 > 고객 업데이트 > 고객 브랜딩 설정 업데이트, 고객 온보딩 설정 업데이트, 고객 프로필 설정 업데이트, 고객 지원 설정 업데이트, 고객 시간대 설정 업데이트
(Admin API 권한) 결제 관리 > 청구서 읽기 권한
-
부여된 권한을 확인하고, 역할 만들기 버튼을 클릭하세요.
-
권한을 부여할 계정을 검색해 선택한 다음, 역할 저장 버튼을 클릭하세요.
Logpresso app 프로젝트 생성
구글 클라우드에서 앱과 연동할 새 프로젝트를 생성하고, 필요한 정보를 입력하세요.
-
구글 클라우드 콘솔에 접속하여 상단 도구 모음에서 조직명을 클릭하세요.
-
대화 상자에서 새 프로젝트 버튼을 클릭하세요.
-
프로젝트 이름을 입력하고 만들기 버튼을 클릭하세요.
Admin SDK
구글 워크스페이스 앱은 구글이 제공하는 API를 이용해 구글 워크스페이스와 연동합니다. 이제 Logpresso app이 Admin SDK를 사용하도록 구성할 차례입니다.
-
상단 도구 모음에서 프로젝트를 새로 만든 Logpresso app으로 전환하세요.
-
상단 검색 창에 'Admin SDK API'를 입력하고 클릭하면 아래의 화면이 표시됩니다. 이 화면에서 사용 버튼을 클릭하세요.
Google Workspace Alert Center API
구글 워크스페이스 앱은 구글이 제공하는 API를 이용해 구글 워크스페이스 알림 센터와 연동합니다. 이제 Logpresso app이 Google Workspace Alert Center API를 사용하도록 구성할 차례입니다.
-
상단 도구 모음에서 프로젝트를 새로 만든 Logpresso app으로 전환하세요.
-
상단 검색 창에 'Google Workspace Alert Center API'를 입력하고 클릭하면 아래의 화면이 표시됩니다. 이 화면에서 사용 버튼을 클릭하세요.
서비스 계정
이제 Logpresso app 프로젝트를 위한 계정을 생성합니다.
-
검색 창에 'IAM'을 입력한 다음, IAM 및 관리자를 클릭하세요.
-
왼쪽 메뉴에서 서비스 계정을 클릭한 다음, 서비스 계정 화면에서 서비스 계정 만들기 버튼을 클릭하세요.
-
서비스 계정 이름에 logpresso를 입력하고 완료 버튼을 클릭하세요.
키
서비스 계정으로 구글 API를 호출해 이용하려면 키가 필요합니다.
-
서비스 계정 목록에서 새로 생성된 서비스 계정 logpresso의 이메일을 클릭하여 상세 화면으로 이동하세요.
-
상단 메뉴에서 키를 클릭한 다음, 키 추가를 클릭하면 메뉴가 나타납니다. 메뉴에서 새 키 만들기를 클릭하세요.
-
'…'용 비공개 키 만들기 대화상자에서 키 유형으로 JSON을 선택하고 만들기 버튼을 클릭하세요.
-
구글 클라우드 콘솔에서 키 파일이 생성되면 웹 브라우저가 자동으로 키 파일을 다운로드합니다. 이 파일을 안전한 곳에 보관하세요.
도메인 차원 위임
이제 Logpresso app이 조직의 데이터에 접근할 수 있도록 도메인 차원 위임을 설정합니다.
-
상단 메뉴에서 세부사항을 클릭하고, 고급 설정 섹션을 클릭해 화면을 펼치세요.
-
클라이언트 ID 오른쪽에 있는 복사하기 아이콘을 클릭해 클립보드에 복사하세요. 이 클라이언트 ID는 도메인 전체 위임 관리 설정할 때 필요합니다.
-
클라이언트 ID 아래에 있는 GOOGLE WORKSPACE 관리 콘솔 보기 버튼을 클릭해 구글 워크스페이스 관리 콘솔로 이동하세요.
-
구글 워크스페이스 관리 콘솔에서 보안 > 액세스 및 데이터 관리 > API 관리로 이동하세요.
-
화면 하단에서 도메인 전체 위임 관리를 클릭하세요.
-
도메인 전체 위임 화면에서 상단 메뉴에 있는 새로 추가 버튼을 클릭하고, 새 클라이언트 ID 추가 대화 상자에서 다음 항목을 입력하세요.
-
클라이언트 ID에 클립보드 복사해둔 클라이언트 ID를 붙여넣으세요.
-
OAuth 범위에 아래 문자열을 복사해 붙여넣으세요.
https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/drive.activity.readonly,https://www.googleapis.com/auth/contacts.readonly,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/apps.alerts,https://www.googleapis.com/auth/drive.apps.readonly위 문자열은 다음과 같은 OAuth 범위 주소로 구성되어 있습니다.
- https://www.googleapis.com/auth/admin.directory.user
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.domain.readonly
- https://www.googleapis.com/auth/admin.reports.audit.readonly
- https://www.googleapis.com/auth/drive.activity.readonly
- https://www.googleapis.com/auth/contacts.readonly
- https://www.googleapis.com/auth/spreadsheets (1.1.2309.0 이후)
- https://www.googleapis.com/auth/apps.alerts (1.4.2411.0 이후)
- https://www.googleapis.com/auth/drive.apps.readonly (1.5.2501.0 이후)
-
접속 프로파일 설정 시 추가되는 위임된 계정 정보는 아래 이미지와 같이 확인이 가능합니다. (최고 관리자 계정만 연동이 가능합니다.)

이제 구글 워크스페이스에서 해야 할 모든 설정이 끝났습니다.
앱 설치
먼저 앱 설치하기 문서를 참고해 구글 워크스페이스 앱을 설치하세요. 앱 설치 후 진행할 설정은 다음과 같습니다.
- 접속 프로파일 설정
- 수집기 설정
- Google Workspace Admin Activity
- Google Workspace Login
- Google Drive Activity
- Google Meet Activity
- Google Chat Activity
- Google Workspace Alert Center
접속 프로파일 설정
접속 프로파일 문서를 참고해 접속 프로파일을 추가하세요.
다음은 접속 프로파일 설정 중 필수 입력 항목입니다.
- 이름: 접속 프로파일을 식별할 고유한 이름
- 식별자: 로그프레소 쿼리 등에서 사용할 접속 프로파일의 고유 식별자
- 유형:
구글 워크스페이스선택 - 고객 ID: 구글 워크스페이스 관리 콘솔에서 확인한 고객 ID
- 위임된 계정: 로그프레소 소나용 관리자 역할이 부여된 사용자 계정의 이메일
- 서비스 키: JSON형식 키 파일의 내용
수집기 설정
구글 워크스페이스 앱은 다섯 가지의 수집기가 필요합니다. 수집기 문서를 참고해 수집기를 추가하세요.
Google Workspace Admin Activity
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Workspace Admin Activity선택 - 테이블:
GOOGLE_ADMIN으로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
Google Workspace Login
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Workspace Login선택 - 테이블:
GOOGLE_LOGIN으로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
Google Drive Activity
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Drive Activity선택 - 테이블:
GOOGLE_DRIVE로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
Google Meet Activity
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Meet Activity선택 - 테이블:
GOOGLE_MEET으로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
Google Chat Activity
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Chat Activity선택 - 테이블:
GOOGLE_CHAT으로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
Google Workspace Alert Center
다음은 수집기 설정 중 필수 입력 항목입니다.
- 이름: 수집기를 식별할 고유한 이름
- 주기: 10초(기본값은 5초이나 10초 이상 권장)
- 적재 위치/수집 위치: 로그프레소 플랫폼 구성에 따라 적합한 노드 선택
- 수집 모델:
Google Workspace Alert Center선택 - 테이블:
GOOGLE_ALERT로 시작하는 이름 입력 - 접속 프로파일: 접속 프로파일 구성 시 입력한 식별자
사용자 계정 OAuth 방식으로 스프레드시트 연동
사용자 계정 OAuth 방식으로 접속 프로파일을 구성해 구글 스프레드시트 읽기/쓰기 기능을 사용하는 절차입니다. 감사 로그 수집기는 이 방식으로 사용할 수 없습니다.
제약 사항
인증 정보 수명
리프레시 토큰은 소나가 구글에 접속할 때 사용하는 인증 정보입니다. 아래 조건에서 사용할 수 없게 되며, 그 시점부터 읽기/쓰기 동작이 실패합니다.
- 계정 비밀번호 변경
- 사용자가 구글 계정에서 앱 액세스 권한 철회
- 6개월간 미사용
- 사용자 유형이 외부이고 게시 상태가 테스트인 경우 7일 경과
특정 담당자의 개인 계정 대신 연동 전용 계정으로 동의를 받아두면 담당자 변경·퇴사에 영향받지 않습니다.
스프레드시트 접근 조건
스프레드시트 소유 도메인과 사용 계정 도메인이 다른 경우, 관리 콘솔의 Drive 외부 공유 정책에 따라 접근이 제한될 수 있습니다.
준비 요약
설정 작업은 구글 클라우드 콘솔, OAuth 2.0 Playground, 로그프레소 소나 세 곳에서 진행합니다. 각 단계의 작업 위치와 결과물은 아래와 같습니다.
| 단계 | 작업 위치 | 메뉴 경로 | 결과물 |
|---|---|---|---|
| 1 | 구글 클라우드 콘솔 | 상단 프로젝트 선택기 > 새 프로젝트 | 전용 프로젝트 |
| 2 | 구글 클라우드 콘솔 | API 및 서비스 > 라이브러리 > Google Sheets API | Sheets API 활성화 |
| 3 | 구글 클라우드 콘솔 | Google 인증 플랫폼 > 브랜딩, 대상 | OAuth 동의 화면 |
| 4 | 구글 클라우드 콘솔 | Google 인증 플랫폼 > 클라이언트 | 클라이언트 ID, 클라이언트 보안 비밀번호 |
| 5 | OAuth 2.0 Playground | 톱니바퀴 설정 > Step 1 > Step 2 | 리프레시 토큰 |
| 6 | 로그프레소 소나 | 설정 > 접속 프로파일 | 서비스 키 JSON, 접속 프로파일 |
| 7 | 로그프레소 소나 | 쿼리 | 읽기/쓰기 동작 확인 |
필요한 권한은 아래와 같습니다. 워크스페이스 관리자 권한은 필요하지 않습니다. 표의 'OAuth 범위'는 앱이 구글에 요청하는 권한의 종류를 뜻하며, 이 연동은 스프레드시트 권한 한 가지만 사용합니다.
| 대상 | 필요 권한 | 비고 |
|---|---|---|
| GCP 프로젝트 | 소유자 또는 편집자 | 프로젝트 생성, API 활성화, OAuth 클라이언트 발급에 필요 |
| 구글 계정(OAuth 동의) | 별도 권한 없음. 본인 동의만 필요 | 단계 5에서 동의할 계정. 담당자 개인 계정보다 연동 전용 계정을 권장합니다 |
| 대상 스프레드시트 | 편집자 | |
| OAuth 범위 | https://www.googleapis.com/auth/spreadsheets | 단계 2에서 함께 등록, 단계 5에서 동의 |
| 로그프레소 소나 | 접속 프로파일 생성 권한 |
앱 버전 1.1.2309.0 이상에서 스프레드시트 확장 명령어를 제공합니다. 소나에서 oauth2.googleapis.com과 sheets.googleapis.com으로 HTTPS/443 아웃바운드 통신이 허용되어야 합니다.
서비스 계정 방식과의 차이
앱은 토큰을 발급할 때 감사 로그·계정 조회 등에 필요한 OAuth 범위를 함께 요청합니다. 서비스 계정 방식에서는 요청하는 범위를 도메인 전체 위임에 전부 등록해야 토큰이 발급되므로, 권한을 스프레드시트로만 제한할 수 없습니다.
사용자 계정 방식에서는 앱의 범위 지정이 적용되지 않고, OAuth 동의 시 승인한 범위만 실제로 부여됩니다.
| 항목 | 서비스 계정 | 사용자 계정 |
|---|---|---|
| 권한 범위 제한 | 불가. 매뉴얼 안내 범위 전체 등록 필요 | 가능. 승인한 범위만 부여 |
| 도메인 전체 위임·관리자 역할 | 필요 | 불필요 |
| 사용 가능 기능 | 앱 전체 기능 | 스프레드시트 읽기/쓰기 2종 |
| 인증 정보 수명 | 키 삭제 전까지 유지 | 토큰 만료·취소 가능 |
GCP 설정
단계 1: 전용 GCP 프로젝트 생성
구글 클라우드 콘솔 > 상단 프로젝트 선택기 > 새 프로젝트에서 이 연동 전용 프로젝트를 생성합니다.
기존 프로젝트를 사용해도 기능은 동작합니다. 다만 OAuth 동의 화면은 프로젝트당 하나만 존재하며 그 프로젝트의 모든 클라이언트가 공유하므로, 다른 앱이 구성된 프로젝트를 재사용하면 아래 문제가 발생합니다.
- 동의 화면에 이 연동과 무관한 앱 이름이 표시되어, 사용자가 동의 단계에서 혼란을 겪습니다.
- 사용자 유형(내부·외부)과 게시 상태를 공유합니다. 기존 앱이 테스트 상태이면 이 연동의 리프레시 토큰도 7일 후 만료되고, 반대로 프로덕션으로 전환하면 같은 프로젝트의 다른 앱도 함께 프로덕션 상태가 됩니다.
- 단계 2에서 함께 등록되는 OAuth 범위가 기존 앱의 범위 목록과 합쳐져, 동의 화면에 표시되는 권한이 기존 앱의 권한과 섞입니다.
연동을 종료할 때 프로젝트만 삭제하면 클라이언트와 발급된 토큰이 함께 정리되는 점도 전용 프로젝트를 권장하는 이유입니다.
단계 2: Google Sheets API 활성화
API 및 서비스 > 라이브러리로 이동해 Google Sheets API를 검색합니다. 제품 세부정보 화면에서 사용 버튼을 클릭합니다. 활성화 후 반영까지 시간이 소요될 수 있습니다. API를 활성화하면 Google 인증 플랫폼 > 데이터 액세스에 스프레드시트 범위가 함께 등록되므로, 범위를 따로 추가할 필요가 없습니다.
단계 3: OAuth 동의 화면 구성
Google 인증 플랫폼 > 브랜딩에서 앱 정보를 입력합니다. 앱 이름은 사용자가 동의 화면에서 보게 되는 이름이므로 식별 가능한 이름으로 지정합니다.
대상 단계에서 사용자 유형을 선택합니다. 사용 계정이 조직의 구글 워크스페이스 계정이면 내부를, 조직 외부 계정이나 개인 계정이면 외부를 선택합니다. 외부를 선택한 경우 앱 게시를 눌러 프로덕션으로 전환해야 리프레시 토큰이 7일 후 만료되지 않습니다.
이어서 연락처 정보에 알림 수신 이메일을 입력하고 만들기를 클릭합니다.
단계 4: OAuth 클라이언트 발급
Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기로 이동합니다.
- 애플리케이션 유형: 웹 애플리케이션
- 이름: 콘솔에서 식별할 이름
- 승인된 리디렉션 URI:
https://developers.google.com/oauthplayground
생성 후 표시되는 대화상자에서 클라이언트 ID와 클라이언트 보안 비밀번호를 복사해 안전한 곳에 보관합니다.
단계 5: 리프레시 토큰 발급
리프레시 토큰은 콘솔에서 다운로드할 수 없습니다. 사용자가 브라우저에서 동의 절차를 한 번 거쳐야 발급됩니다. OAuth 2.0 Playground에서 발급합니다.
우측 상단 톱니바퀴를 클릭해 아래와 같이 설정합니다.
| 설정 항목 | 값 |
|---|---|
| OAuth flow | Server-side |
| Access type | Offline |
| Force prompt | Consent Screen |
| Use your own OAuth credentials | 체크 |
| OAuth Client ID | 단계 4의 클라이언트 ID |
| OAuth Client secret | 단계 4의 클라이언트 보안 비밀번호 |
좌측 Step 1 하단의 입력란에 범위 https://www.googleapis.com/auth/spreadsheets를 입력하고 Authorize APIs를 클릭합니다.
계정 선택 후 동의 화면에서 요청 권한을 확인하고 허용을 클릭합니다. 스프레드시트 권한 한 건만 표시되어야 합니다.
Playground로 돌아온 뒤 Step 2의 Exchange authorization code for tokens를 클릭합니다. 응답에서 refresh_token 값과 scope 값을 확인합니다.
refresh_token:1//로 시작하는 값. 접속 프로파일에 사용합니다.scope:https://www.googleapis.com/auth/spreadsheets인지 확인합니다.access_token: 1시간 후 만료되는 값으로, 접속 프로파일에는 사용하지 않습니다.
로그프레소 소나 설정
단계 6: 접속 프로파일 설정
먼저 서비스 키 항목에 입력할 JSON을 작성합니다. 단계 4와 단계 5에서 확보한 값 세 개를 채웁니다.
{
"type": "authorized_user",
"client_id": "클라이언트 ID",
"client_secret": "클라이언트 보안 비밀번호",
"refresh_token": "리프레시 토큰"
}
이어서 시스템 > 접속 프로파일에서 접속 프로파일을 추가합니다.
| 항목 | 입력값 | 설명 |
|---|---|---|
| 이름 | gws-sheets | 접속 프로파일을 식별할 고유한 이름 |
| 식별자 | gws_sheets | 확장 명령어의 profile 옵션에 사용할 식별자 |
| 유형 | 구글 워크스페이스 | |
| 고객 ID | dummy | 스프레드시트 기능에서 사용하지 않습니다. 필수 항목이므로 임의 값을 입력합니다 |
| 위임된 계정 | dummy | 사용자 계정 방식에서는 무시됩니다. 필수 항목이므로 임의 값을 입력합니다 |
| 서비스 키 | 위에서 작성한 JSON | 저장 후 마스킹되어 재확인이 불가하므로 원본을 별도 보관합니다 |
단계 7: 동작 확인
확장 명령어로 읽기/쓰기를 확인합니다. 아래 쿼리는 예시이므로, 스프레드시트 ID와 시트 탭 이름, 필드 이름을 실제 환경에 맞게 바꿔 실행하십시오.
스프레드시트를 읽습니다.
스프레드시트에 값을 씁니다.
json "{}"
| eval email="test@example.com", name="테스트", dept="개발", status="정상"
| google-workspace-sheets-write-values profile="gws_sheets" sheet-id="스프레드시트 ID" sheet-name="Sheet1" key-column="A" fields="+email,name,dept,status"
스프레드시트 ID는 문서 URL의 https://docs.google.com/spreadsheets/d/와 /edit 사이 값입니다.



































