MINARAGoogle Chat
서비스 계정 JWT 인증을 통한 Google Workspace Chat 연동. 수신 활동은 [email protected]으로 서명됩니다.
🟡 서비스 계정을 통한 아웃바운드 지원, 수신 JWT 검증 완료. Google Workspace 배포 환경에서 사용합니다. 아웃바운드는 서비스 계정 JSON 키로 단기 액세스 토큰을 발급하며, 수신 시에는 모든 POST 요청이
[email protected]으로 서명되었는지 검증합니다.
제공 기능
{text}와 함께POST https://chat.googleapis.com/v1/{space}/messages를 통한 아웃바운드 텍스트 전송. 스레드(thread.name)도 지원됩니다./webhooks/google-chat의 수신 웹훅. Google은[email protected]이 발급한 bearer JWT로 모든 수신 요청에 서명합니다.- TTL 1시간, 갱신 여유 시간 5분의 액세스 토큰 캐시.
- 이번 PR에서는 텍스트만 지원합니다. Cards v2, 다이얼로그, 슬래시 명령어, 첨부 파일 다운로드는 추후 지원 예정입니다.
- 메시지당 4096자 텍스트 제한.
설정
1. Google Cloud 프로젝트 및 서비스 계정 생성
- Google Cloud Console에서 Chat 앱용 프로젝트를 선택하거나 새로 생성합니다.
- "APIs & Services" → "Enable APIs"로 이동하여 Google Chat API를 활성화합니다.
- "IAM & Admin" → "Service Accounts" → "Create Service Account"를 클릭합니다. 이름을 지정합니다 (예:
minara-chat-bot). - 생성 후 서비스 계정을 열고 "Keys" 탭 → "Add Key" → "JSON"을 선택합니다. 다운로드된 파일을 저장합니다.
2. Chat 앱 구성
- Google Cloud 프로젝트에서 Google Chat API → "Configuration" 탭으로 이동합니다.
- App name, Avatar URL, Description: 적절한 값을 입력합니다.
- Functionality: "Receive 1:1 messages"와 "Join spaces and group conversations"를 선택합니다.
- Connection settings: "App URL"을 선택하고 엔드포인트를
https://<your-host>/webhooks/google-chat으로 설정합니다. - Authentication Audience: 하나를 선택하고 기억합니다.
- "Project Number" → audience는 12자리 GCP 프로젝트 번호가 됩니다.
- "HTTP endpoint URL" → audience는 엔드포인트 URL이 됩니다.
- Permissions: "Specific people and groups" 또는 도메인을 선택합니다.
3. 서비스 계정 JSON을 샌드박스로 이동
CLAUDE.md §4에 따라 서비스 계정 키는 data / 샌드박스 트리 내에 위치해야 합니다. 다운로드한 JSON을 ~/.minara/sandbox/ (또는 MINARA_DATA_DIR 동등 경로) 아래로 이동합니다.
mv ~/Downloads/<project>-<hash>.json ~/.minara/sandbox/google-chat-sa.json
chmod 600 ~/.minara/sandbox/google-chat-sa.json4. 기본 스페이스 확인
Chat 앱을 스페이스에 추가하거나 테스트 사용자가 봇에게 DM을 보낸 후, URL에서 스페이스 리소스 이름을 확인합니다. spaces/AAAA1234567 형식입니다. 이를 GOOGLE_CHAT_DEFAULT_SPACE_ID로 저장합니다.
5. Minara 구성
minara auth messaging add
# 목록에서 `google_chat`을 선택합니다.또는 환경 변수를 직접 설정합니다.
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH=/Users/you/.minara/sandbox/google-chat-sa.json
GOOGLE_CHAT_DEFAULT_SPACE_ID=spaces/AAAA1234567
GOOGLE_CHAT_AUDIENCE=1234567890GOOGLE_CHAT_AUDIENCE는 Workspace 콘솔의 값과 정확히 일치해야 합니다. 콘솔에서 "Project Number"를 선택했다면 숫자만 입력합니다. "HTTP endpoint URL"을 선택했다면 콘솔에 표시된 URL을 그대로 입력합니다 (후행 슬래시 포함 여부도 동일하게 맞춰야 합니다).
6. 테스트
minara auth messaging test google_chat수신 웹훅
Google의 수신 JWT에는 다음 정보가 포함됩니다.
| 클레임 | 기대값 |
|---|---|
iss (발급자) | [email protected] |
aud (audience) | GOOGLE_CHAT_AUDIENCE와 일치 |
| 서명 | RS256, https://www.googleapis.com/service_accounts/v1/jwk/[email protected]에 게시된 Google X.509 인증서로 검증 |
| 클록 스큐 | ±5분 |
JWKS는 24시간 동안 캐시됩니다. kid 미스 발생 시 자동으로 키 교체가 처리됩니다.
허용 이벤트 유형: MESSAGE (앱이 속한 스페이스에 사용자가 게시한 경우). 그 외 유형(ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED)은 무시됩니다.
제한 사항 및 주의 사항
GOOGLE_CHAT_AUDIENCE는 바이트 단위로 정확히 일치해야 합니다. 수신 시 401 오류가 발생하는 가장 흔한 원인은 audience 환경 변수 값이 콘솔 설정과 다른 경우입니다. "Project Number"의 경우 앞에 0이 없는 실제 숫자 문자열을 그대로 사용해야 합니다.- 서비스 계정 JSON 경로는 샌드박스 내에 있어야 합니다. CLAUDE.md §4 (샌드박스 전용 파일 참조) 규정에 따릅니다. 팩토리는 부팅 시 파일을 읽으므로 키를 교체하려면 재시작이 필요합니다.
- 하나의 JSON, 하나의 audience 모델. 콘솔에서 "Authentication Audience"를 변경한 경우 같은 시간 내에
GOOGLE_CHAT_AUDIENCE도 업데이트해야 합니다. - 카드 미지원. Cards v2 메시지와 다이얼로그는 양방향 모두 아직 지원되지 않습니다.
문제 해결
"수신 시 401 Unauthorized"
GOOGLE_CHAT_AUDIENCE가 콘솔과 일치하지 않습니다. Chat API 구성 페이지를 열고 audience 값을 그대로 복사합니다.
"아웃바운드 시 Missing required scope"
- 서비스 계정에
https://www.googleapis.com/auth/chat.bot스코프가 없습니다. 팩토리가 자동으로 요청하므로, 서비스 계정이 Chat API가 활성화된 프로젝트에 속해 있는지 확인합니다.
"서비스 계정 JSON을 찾을 수 없음"
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH가 샌드박스 외부를 가리키거나 파일이 존재하지 않습니다.~/.minara/sandbox/아래로 이동하고 환경 변수를 업데이트합니다.