구글 드라이브 / 메일 연동 설정

기관의 공용 Google 계정을 연결해 Workhub 메시지/태스크에 구글 드라이브 파일을 첨부하고, Gmail 메일함을 Workhub 안에서 열람·발신할 수 있게 합니다.

개요

운영 모델: 기관별로 자체 GCP(Google Cloud Platform) OAuth Client 를 발급받아 등록 — Workhub 가 중간에 자격증명을 보유하지 않는 SaaS 표준 모델
연결 단위: 조직(org) 당 1개. 기관 관리자가 한 번 등록하면 같은 조직의 모든 허가된 사용자가 공유
저장: 자격증명은 모두 AES-256-GCM 으로 암호화되어 DB 에 저장. 평문 secret 은 응답에 노출되지 않음
사전 준비 시간: 약 15~30분 (GCP Console 작업 포함)

전체 흐름:

[GCP 작업]         [Workhub]              [구글 OAuth]
─────────────     ──────────────────     ──────────────
1. 프로젝트 생성   →                       
2. API 활성화      →
3. 동의 화면 설정  →
4. OAuth Client   → 5. 관리자 화면 등록  → 6. 구글 계정 연결
   발급                                       (관리자 OAuth)
                                          ↓
                  ← 7. 모듈 활성화 (드라이브 / 메일)
                  ← 8. 사용자 사용 (첨부 / 메일함)

1. GCP 사전 작업

Google Cloud Console (https://console.cloud.google.com) 에 기관 대표 Gmail 계정으로 로그인한 상태에서 진행합니다.
Google Workspace 도메인(예: 회사 도메인 Gmail) 이면 별도 운영 검토 — 본 문서 끝의 운영 모드 결정 참고.

1-1. 프로젝트 생성 또는 선택

좌측 상단 프로젝트 드롭다운 → "새 프로젝트" 또는 기존 프로젝트 선택
프로젝트 이름 예시: workhub-koavio (기관명 포함 권장)

1-2. API 활성화

좌측 햄버거(≡) 메뉴 → "API 및 서비스" → "라이브러리" 에서 아래 3개 API 검색·활성화:

API	용도	필수
Google Drive API	파일 메타/권한 조회	드라이브 모듈 사용 시 필수
Gmail API	메일 조회/발신	메일 모듈 사용 시 필수
Google Picker API	브라우저 파일 선택 UI	드라이브 첨부 기능 필수

각각 클릭 → "사용 설정" 버튼.

1-3. OAuth 동의 화면 설정

좌측 메뉴 "Google 인증 플랫폼" → "브랜딩" (구 UI 에선 "OAuth 동의 화면"):

항목	값
User Type	External (Workspace 도메인 한정이면 Internal)
앱 이름	사용자 동의 화면에 표시될 이름 (예: "Workhub 통합")
사용자 지원 이메일	기관 관리자 Gmail
개발자 연락처	동일
앱 도메인	(선택) Workhub 운영 도메인

저장 후 좌측 "대상" 메뉴에서:

게시 상태가 "테스트(Testing)" 면 하단 "테스트 사용자" 에 사용할 모든 사용자의 Gmail 주소를 추가 (최대 100명)
"프로덕션" 으로 게시하려면 Google 검증 필요 — 본 문서 끝의 운영 모드 결정 참고

1-4. OAuth 2.0 Client ID 발급

좌측 "클라이언트" 메뉴 → 상단 "+ 클라이언트 만들기" (구 UI 에선 "사용자 인증 정보 만들기 → OAuth 클라이언트 ID"):

항목	값
애플리케이션 유형	웹 애플리케이션
이름	예: `workhub-prod` (식별용)
승인된 리디렉션 URI	다음 단계 참고

승인된 리디렉션 URI 입력값 — Workhub 가 OAuth 콜백을 받을 URL:

https://<Workhub 도메인>/api/modules/google/oauth/callback

운영 예시:

https://workhub.example.com/api/modules/google/oauth/callback

로컬 검증:

http://localhost/api/modules/google/oauth/callback

중요: 끝에 / 가 있고 없고 / 대소문자 / 포트번호 — 1바이트라도 다르면 OAuth 시 redirect_uri_mismatch 오류 발생.

생성 직후 표시되는 Client ID + Client Secret 을 복사 (별도 안전한 곳에 임시 저장). 같은 화면은 다시 열어도 secret 은 마지막 4자만 보임.

1-5. (드라이브 모듈만) Google API Key 발급

드라이브 파일 선택 UI(Google Picker) 가 브라우저에서 추가로 필요로 합니다. 메일 모듈만 사용한다면 이 단계는 건너뛰어도 됩니다.

좌측 "클라이언트" → "+ 사용자 인증 정보 만들기" → "API 키" (위치는 GCP 콘솔 버전에 따라 "API 및 서비스 → 사용자 인증 정보" 일 수도 있음):

키 자동 생성 → 복사
"키 제한" 클릭:
- 애플리케이션 제한: HTTP 리퍼러 → https://<Workhub 도메인>/* 추가
- API 제한: 키 제한 → 선택한 API → Google Picker API + Google Drive API 만 체크

이 API Key 는 Workhub 빌드 시점에 frontend 번들에 박혀 들어가므로 (VITE_GOOGLE_API_KEY), Workhub 시스템 관리자(또는 배포 담당자)에게 전달하여 빌드 환경변수에 추가해야 합니다.

2. Workhub 에서 OAuth Client 등록

GCP 작업이 끝났다면 Workhub 화면으로 이동합니다.

좌측 사이드바 → 관리자 → 모듈 관리 (/app/admin/modules)
화면 최상단의 amber 안내 패널 "기관 Google OAuth Client 미등록" 확인
"등록하기" 버튼 클릭
폼에 다음을 입력:

항목	값
Client ID	1-4 단계에서 발급받은 값 (예: `333933...apps.googleusercontent.com`)
Client Secret	1-4 단계의 secret (예: `GOCSPX-...`)
Redirect URI	1-4 단계에 등록한 값과 정확히 동일

"저장" 클릭

저장 직후 패널이 "등록됨" 상태로 바뀌며 Client ID / 마스킹된 Secret / Redirect URI 가 표시됩니다.

보안 안내: 저장된 client_secret 평문은 다시 표시되지 않습니다. 변경 시 새로 입력해야 합니다. 모든 secret 은 DB 에 AES-256-GCM 으로 암호화 저장됩니다.

3. 구글 계정 연결 (OAuth)

OAuth Client 등록이 끝나면 같은 화면의 구글 드라이브 또는 구글 메일 카드의 amber 배너가 다음으로 바뀝니다:

기관 구글 계정 연결 필요 — [구글 계정 연결] 버튼

카드 안의 [구글 계정 연결] 버튼 클릭
새 창에서 Google 동의 화면이 열림
기관 공용 Gmail 계정 선택 (또는 로그인)
권한 동의:
- Google Drive 파일 보기 및 관리 (드라이브 모듈)
- Gmail 메일 보기 (메일 모듈)
- Gmail 메일 보내기 (발신 기능)
- 이메일 주소 확인 (계정 식별용)
Workhub 화면으로 자동 복귀 → 카드의 배너가 사라지고 prerequisites 모두 ✓ 표시

주의: OAuth 동의 시 사용하는 계정 = 기관 공용 메일/드라이브를 보유한 계정. 본인 개인 Gmail 로 동의하면 본인 개인 데이터에만 접근됩니다.

테스트 상태 GCP 프로젝트 의 경우: 1-3 단계에서 "테스트 사용자" 명단에 추가된 계정만 OAuth 진행 가능. 명단 외 계정은 "Access blocked / 이 앱이 차단되었습니다" 오류 발생.

연결 결과는 같은 화면의 "구글 계정 연결" 패널 에서 확인할 수 있습니다 (연결된 이메일 주소 + 부여받은 권한 목록).

4. 모듈 활성화 및 사용

4-1. 구글 드라이브 모듈

활성화

모듈 관리 화면의 "구글 드라이브" 카드 → 우측 토글 스위치 ON

사용 (일반 사용자)

드라이브 모듈은 좌측 메뉴 없이 메시지 첨부 흐름 에 통합됩니다.

사이드바 → 채널 / DM / 토픽 진입
하단 메시지 입력창 → 첨부 아이콘(📎) → "구글 디스크"
Google Picker 팝업 → "내 드라이브" 또는 "공유 문서함" 탭에서 파일 선택 → "선택"
메시지에 첨부 칩 표시 → 메시지 전송
다른 사용자가 메시지의 첨부 칩 클릭 시:
- 첨부한 파일이 본인 권한 안에 있으면 → Google Drive 에서 즉시 열림
- 권한 없으면 → 모듈 설정의 "자동 권한 부여" 가 켜져 있고 본인 Gmail 이 연결돼 있으면 자동 권한 부여 시도

모듈 설정

카드의 "설정" 버튼:

항목	설명
공유 드라이브	기본 첨부 대상 공유 드라이브 선택 (비워두면 마이드라이브 사용)
자동 권한 부여	첨부 메시지의 대화 구성원에게 자동으로 reader 권한 부여 (#508)

채널 파일 탭

채널 화면의 파일 탭에서 첨부된 드라이브 파일은 "Drive" 배지로 구분됩니다. 다운로드 대신 외부 링크 아이콘 으로 Google Drive 에서 열기.

4-2. 구글 메일 모듈

활성화

모듈 관리 화면의 "구글 메일" 카드 → 토글 ON
활성화 직후 좌측 사이드바에 "메일" 메뉴 자동 노출
접근 제어: 메일 모듈은 PolicyAllowlist — 모듈 설정의 "권한" 에서 메일함을 볼 수 있는 사용자를 명시적으로 추가해야 일반 사용자가 접근 가능 (관리자는 항상 접근)

사용 (허가된 사용자)

좌측 메뉴 "메일" 클릭 (/app/mail)
좌측: 스레드 목록 + 검색
우측: 선택 스레드의 최신 메시지 본문 + 액션
상단 연필 아이콘: 새 메일 작성
우상단 "답장" 버튼: 선택 메시지에 답장
우상단 "태스크 만들기": 메일 내용을 태스크로 변환 (프로젝트/토픽 선택 후 생성)
관리자만 표시되는 "새로고침" 아이콘: 즉시 Gmail 동기화

동기화 모드

기본은 수동/cron 폴링(pull). 운영에서 실시간 동기화가 필요하면:

GCP Pub/Sub 토픽 생성 + Workhub 운영 환경변수 GMAIL_PUSH_TOPIC 설정 (시스템 관리자 작업)
모듈 설정의 sync_mode 를 push 로 변경
자동 watch 등록 — Gmail 새 메일 도착 시 즉시 동기화

5. 운영 모드 결정 (Internal vs External)

GCP OAuth 동의 화면의 User Type 선택에 따라 운영 양상이 크게 달라집니다.

모드	조건	사용 가능 인원	검증	비용
Internal	GCP 프로젝트가 Google Workspace 도메인 안에 있을 때	Workspace 도메인 사용자 무제한	불필요	무료
External + Testing	일반 Gmail/Workspace 외 사용	등록된 테스트 사용자 최대 100명	불필요	무료
External + In Production	외부 사용자에게 공개	무제한	검증 필요	scope 종류에 따라

Gmail/Drive 의 검증 필요성:

drive (전체) : sensitive scope — 검증 필요, 무료 (2-6주 소요)
gmail.send : sensitive — 검증 필요, 무료
gmail.readonly : restricted — 검증 + 연간 보안평가 (Annual Security Assessment) 필요, 유료 ($4,500~$75,000/년)

기관 상황	추천 모드
Google Workspace 가입자 (회사 도메인 Gmail)	Internal 모드 — 가장 깔끔
소규모 (~100명) + 일반 Gmail 사용	External + Testing — 검증 회피
100명 초과 + 외부 사용자 다수	External + In Production + 검증 — 유료 보안평가 감수

6. 트러블슈팅

"redirect_uri_mismatch" 오류

OAuth 진행 시 가장 흔한 오류.

GCP Console "클라이언트" 메뉴 → 본인 OAuth Client → "승인된 리디렉션 URI" 가 Workhub 의 OAuth Config 에 입력한 값과 정확히 일치 하는지 확인
흔한 차이:
- http vs https
- 끝의 / 유무
- 포트 번호 (:80 명시 vs 생략)
- /api/ 경로 누락

수정 후 GCP 측 반영에 수십 초 지연될 수 있음 — 1~2분 대기 후 재시도.

"Access blocked: 이 앱이 차단되었습니다"

게시 상태가 Testing 인 GCP 프로젝트 + 시도한 Google 계정이 테스트 사용자 명단에 없음
해결: GCP "대상" 메뉴 → "테스트 사용자" 에 추가

Picker 가 "No documents" / 빈 화면

연결한 Google 계정의 드라이브에 파일이 없거나
Picker 가 다른 계정의 드라이브를 보여주고 있음 (브라우저의 다중 Google 세션 충돌)
해결:
- Picker 우상단 계정 표시 확인
- 시크릿/InPrivate 창에서 Workhub 로그인 후 재시도 (브라우저 세션 격리)
- 또는 https://accounts.google.com 에서 모든 계정 로그아웃 후 연결한 계정만 로그인

메일함이 비어 있음

모듈 활성화 직후엔 동기화 안 됨
관리자가 우상단 "새로고침" (수동 동기화) 클릭 — 최근 7일 INBOX 메시지 가져옴
또는 cron 으로 주기적 동기화 (시스템 관리자 영역)

"기관 구글 계정 연결 필요" 가 계속 표시됨

refresh_token 이 만료된 경우 (Testing 모드 + 7일 경과 등)
해결: 같은 화면에서 "연결 해제" → 다시 "구글 계정 연결" 진행

발신 시 "412 Precondition Required"

gmail.send scope 가 부여되지 않음
해결: 연결 해제 후 재연결 시 권한 동의 화면에서 모든 권한 체크

7. 보안 권장사항

Client Secret 관리

GCP Console 의 Client Secret 은 Workhub 관리자만 접근. 다른 곳에 평문으로 공유 금지
Workhub 내부에서는 AES-256-GCM 으로 암호화 저장 + 응답에서 마스킹
의심 정황 발생 시 GCP Console 에서 Reset Secret → Workhub OAuth Config 재등록

권한 부여 토글

드라이브 모듈의 "자동 권한 부여" 기능은 첨부 시 대화 구성원에게 자동으로 reader 권한을 부여합니다.

기관 외부 사용자 (예: 게스트, 협력사) 가 참여하는 채널에서 첨부하면 외부 사용자에게도 자동 부여 될 수 있음
민감 정보 보호가 중요한 채널은 자동 권한 부여 OFF + 수동 공유 권장

메일함 접근 통제

메일 모듈은 PolicyAllowlist 정책 — 명시적으로 허가한 사용자만 메일함 접근
기본 전제: 기관 공용 메일함 = 민감 정보 → 신뢰할 수 있는 인원만 추가

운영 환경 분리

검증/개발용 OAuth Client 와 운영 OAuth Client 는 분리 권장
redirect URI 도메인이 다르므로 한 Client 에 양쪽 모두 등록하지 말고, 환경별 별도 발급

8. FAQ

Q. 한 OAuth Client 로 드라이브와 메일을 같이 쓸 수 있나요? A. 예. 같은 Client ID 로 OAuth 진행 시 scope 만 추가로 요청합니다 (incremental consent). 기관당 1개의 OAuth Client 로 충분합니다.

Q. OAuth Client 를 수정하면 기존 연결도 끊어지나요? A. Client ID/Secret 자체가 바뀌면 기존 refresh_token 으로 토큰 갱신이 실패합니다. 변경 후엔 연결 해제 → 재연결 이 필요합니다.

Q. 일반 사용자가 본인 개인 Gmail 을 연결할 수 있나요? A. 현재 모델은 조직 단위 1개 연결만 지원 (기관 공용 계정). 개인별 연결은 별도 향후 기능.

Q. 메일함에서 사용자별로 다른 메일이 보이나요? A. 아닙니다. 연결된 기관 공용 계정의 INBOX 가 모든 허가 사용자에게 동일하게 보입니다. 개인 메일은 본인 Gmail 에서 직접 확인해야 합니다.

Q. 운영 환경에서 GCP 토큰이 자주 만료됩니다. A. GCP 동의 화면이 "Testing" 상태이면 refresh_token 이 7일마다 만료됩니다. 운영에선 Internal 모드 또는 In Production + 검증 으로 전환해야 합니다.

구글 드라이브 / 메일 연동 설정

개요

1. GCP 사전 작업

1-1. 프로젝트 생성 또는 선택

1-2. API 활성화

1-3. OAuth 동의 화면 설정

1-4. OAuth 2.0 Client ID 발급

1-5. (드라이브 모듈만) Google API Key 발급

2. Workhub 에서 OAuth Client 등록

3. 구글 계정 연결 (OAuth)

4. 모듈 활성화 및 사용

4-1. 구글 드라이브 모듈

활성화

사용 (일반 사용자)

모듈 설정

채널 파일 탭

4-2. 구글 메일 모듈

활성화

사용 (허가된 사용자)

동기화 모드

5. 운영 모드 결정 (Internal vs External)

추천 전략

6. 트러블슈팅

"redirect_uri_mismatch" 오류

"Access blocked: 이 앱이 차단되었습니다"

Picker 가 "No documents" / 빈 화면

메일함이 비어 있음

"기관 구글 계정 연결 필요" 가 계속 표시됨

발신 시 "412 Precondition Required"

7. 보안 권장사항

Client Secret 관리

권한 부여 토글

메일함 접근 통제

운영 환경 분리

8. FAQ

참고 링크

구글 드라이브 / 메일 연동 설정 ​

개요 ​

1. GCP 사전 작업 ​

1-1. 프로젝트 생성 또는 선택 ​

1-2. API 활성화 ​

1-3. OAuth 동의 화면 설정 ​

1-4. OAuth 2.0 Client ID 발급 ​

1-5. (드라이브 모듈만) Google API Key 발급 ​

2. Workhub 에서 OAuth Client 등록 ​

3. 구글 계정 연결 (OAuth) ​

4. 모듈 활성화 및 사용 ​

4-1. 구글 드라이브 모듈 ​

활성화 ​

사용 (일반 사용자) ​

모듈 설정 ​

채널 파일 탭 ​

4-2. 구글 메일 모듈 ​

활성화 ​

사용 (허가된 사용자) ​

동기화 모드 ​

5. 운영 모드 결정 (Internal vs External) ​

추천 전략 ​

6. 트러블슈팅 ​

"redirect_uri_mismatch" 오류 ​

"Access blocked: 이 앱이 차단되었습니다" ​

Picker 가 "No documents" / 빈 화면 ​

메일함이 비어 있음 ​

"기관 구글 계정 연결 필요" 가 계속 표시됨 ​

발신 시 "412 Precondition Required" ​

7. 보안 권장사항 ​

Client Secret 관리 ​

권한 부여 토글 ​

메일함 접근 통제 ​

운영 환경 분리 ​

8. FAQ ​

참고 링크 ​

구글 드라이브 / 메일 연동 설정

개요

1. GCP 사전 작업

1-1. 프로젝트 생성 또는 선택

1-2. API 활성화

1-3. OAuth 동의 화면 설정

1-4. OAuth 2.0 Client ID 발급

1-5. (드라이브 모듈만) Google API Key 발급

2. Workhub 에서 OAuth Client 등록

3. 구글 계정 연결 (OAuth)

4. 모듈 활성화 및 사용

4-1. 구글 드라이브 모듈

활성화

사용 (일반 사용자)

모듈 설정

채널 파일 탭

4-2. 구글 메일 모듈

활성화

사용 (허가된 사용자)

동기화 모드

5. 운영 모드 결정 (Internal vs External)

추천 전략

6. 트러블슈팅

"redirect_uri_mismatch" 오류

"Access blocked: 이 앱이 차단되었습니다"

Picker 가 "No documents" / 빈 화면

메일함이 비어 있음

"기관 구글 계정 연결 필요" 가 계속 표시됨

발신 시 "412 Precondition Required"

7. 보안 권장사항

Client Secret 관리

권한 부여 토글

메일함 접근 통제

운영 환경 분리

8. FAQ

참고 링크