봇한테 구글 계정 쥐어주기
붙이고, 안 끊기게 만들기

• Google Cloud 프로젝트 — 이 모든 걸 담는 상자. 우리는 nodak-gws-app 하나만 쓴다.
• OAuth 동의화면 — 로그인할 때 뜨는 "이 앱이 캘린더를 보려고 합니다" 그 화면. 앱 이름·연락처·처리방침이 여기서 나온다.
• OAuth 클라이언트 — 프로그램의 신분증. 만들면 JSON 파일이 하나 떨어지고, 그걸 gws한테 쥐어준다.
• 스코프(scope) — 권한 범위. 캘린더 읽기처럼 항목별로 쪼개져 있다.
• 게시 상태 — 테스트 중 / 프로덕션 두 가지. 여기가 6~7장의 주인공이야.

• console.cloud.google.com 접속
• 상단 파란 바의 프로젝트 선택 드롭다운 → 새 프로젝트
• 이름 짓고(예: nodak-gws-app) → 만들기
• 만든 뒤 상단 드롭다운에 그 프로젝트가 선택돼 있는지 확인

좌측 API 및 서비스 → OAuth 동의화면(= Google 인증 플랫폼)으로 들어가서 시작하기.

4단계 아코디언이 뜨면 위에서부터:

1. 앱 정보 — 앱 이름 + 사용자 지원 이메일(드롭다운에서 본인 계정)
2. 대상 — 외부 선택
3. 연락처 정보 — 본인 이메일 → 동의합니다 체크 → 계속
4. 완료 — Google API 서비스: 사용자 데이터 정책에 동의합니다 체크 → 계속 → 만들기

동의화면 구성 캡처 보기 · 캡처 3장

구성이 끝나면 OAuth 개요 화면이 뜬다. 상단 프로젝트 이름 한 번 더 확인하고:

• OAuth 클라이언트 만들기 (또는 좌측 클라이언트 → 클라이언트 추가)
• 애플리케이션 유형: 데스크톱 앱
• 이름 짓고 → 만들기
• 팝업에서 JSON 다운로드 (~/Downloads에 떨어짐)

클라이언트 만들기 화면 보기 · 캡처 1장

gws는 클라이언트 설정을 ~/.config/gws/client_secret.json에서 읽어. 받은 JSON을 그 자리로 옮겨:

cp ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json
gws auth status    # client_config_exists: true 확인

명령은 하나야:

gws auth login --services calendar,meet,gmail,drive,docs,sheets,tasks,people

케이스 A — 그 컴퓨터 앞에 앉아서 인증

gws가 도는 그 맥 앞에서, 그 맥의 브라우저로 누르는 경우. 제일 쉬움.

1. 터미널에서 위 명령 실행
2. 브라우저가 자동으로 열림 (안 열리면 출력된 URL을 직접 붙여넣기)
3. 계정 선택 → 고급 → (안전하지 않음) 이동 → 계속 / 허용
4. 끝. 터미널에 status: success

코드가 같은 컴퓨터의 localhost로 돌아오니까 gws가 알아서 받아. 손댈 게 없어.

케이스 B — 원격 머신에 붙일 때 (에이전트가 대신 셋업할 때가 보통 이거)

gws는 원격 맥미니에서 도는데, 나는 내 노트북 브라우저로 버튼을 누르는 경우.

이땐 자동으로 안 잡혀. 구글이 코드를 localhost로 보내는데 그 localhost가 내 노트북을 가리켜서, 정작 맥미니는 코드를 못 받거든. 그래서 인증 후 "이 사이트에 연결할 수 없음 / localhost에서 연결을 거부" 에러 화면이 떠.

1. 맥미니에서 gws auth login ... 실행 → 출력된 인증 URL을 사람에게 전달
2. 사람은 자기 브라우저에 붙여넣고 → 계정 선택 → 고급 → 이동 → 허용
3. http://localhost:54329/?code=4/0ATs...&scope=... 로 넘어가며 에러 화면이 뜸
4. ⭐ 그 주소창 URL을 통째로 복사해서 맥미니 쪽(에이전트)에 넘긴다
5. 맥미니에서 자기 로컬 서버에 코드를 직접 꽂아 마무리:

curl "http://localhost:54329/?code=<붙여준_URL의_code값>&scope=email%20profile"

앱이 테스트 중 상태면 개발자가 지정한 테스트 사용자만 로그인할 수 있어. 본인 계정을 안 넣으면 로그인할 때 403 access_denied가 뜬다.

403 화면 · 테스트 사용자 추가 화면 보기 · 캡처 2장

좌측 대상(Audience) → 맨 아래 테스트 사용자 → + Add users → 본인 계정 입력 → 저장. 그리고 다시 로그인하면 이번엔 통과돼.

gws auth status    # auth_method 가 none → 로그인된 방식으로 바뀜

여기까지가 "붙이기"야. 그런데 —

7일마다 재로그인하는 법

토큰이 죽으면 gws 명령이 갑자기 인증 에러를 뱉어. 고치는 건 로그인 명령을 그대로 다시 돌리는 것뿐이야.

gws auth login --services calendar,meet,gmail,drive,docs,sheets,tasks,people

엔터 치고 나서:

1. 브라우저가 열린다 → 계정 선택
2. "확인되지 않은 앱" 경고가 뜨면 → 고급 → (안전하지 않음) 이동
3. 권한 목록에서 → 계속 / 허용
4. 터미널로 돌아와서 확인:

gws auth status    # has_refresh_token: true, scope_count 원래대로면 복구 완료

원격이면 위 케이스 B 그대로 하면 돼.

| | 테스트 중 (기본) | 프로덕션 (게시 후) | |---|---|---| | 누가 로그인 가능 | 테스트 사용자만 (최대 100명) | 아무 구글 계정이나 | | 토큰 수명 | 7일 — 매주 재로그인 | 만료 없음 | | 구글 심사 | 없음 | 민감 스코프면 대상 (심사 전에도 경고 뜬 채 사용은 가능) | | 필요한 준비물 | 없음 | 아래 4종 |

준비물 4종

API 및 서비스 → OAuth 동의화면 → 브랜딩 화면이 다 채워져 있어야 해. 하나라도 비면 저장이나 게시가 막혀.

| # | 항목 | 넣는 값 (노닥 기준) | 주의 | |---|---|---|---| | 1 | 애플리케이션 홈페이지 | https://nodak.co.kr/ | 실제로 열려야 함 | | 2 | 개인정보처리방침 링크 | https://nodak.co.kr/privacy | 로그인 없이 열리는 공개 페이지 | | 3 | 승인된 도메인 | nodak.co.kr | 서브도메인 말고 루트 도메인 | | 4 | 도메인 소유권 인증 | 서치콘솔에서 nodak.co.kr | OAuth 프로젝트와 같은 구글 계정으로 |

여기에 개발자 연락처 이메일도 필수야(구글이 알림 보내는 주소). 로고는 선택인데 넣으면 동의 화면이 훨씬 덜 수상해 보여.

처리방침(2번)에 꼭 들어가야 하는 것

심사관은 동의 화면의 스코프랑 처리방침 문구를 나란히 놓고 대조해. 최소한 이 네 개:

• 어떤 구글 데이터에 접근하는지 — 스코프별로 구체적으로. "필요한 범위에서" 같은 뭉뚱그린 말 말고
• 그걸 왜 쓰는지 / 어디 저장하는지 / 누구와 공유하는지
• 이용자가 권한을 철회하는 방법 (Google 계정 권한 페이지 링크)
• Limited Use 선언 — 아래 영문 원문을 그대로 넣는 게 제일 안전해:

Our use and transfer of information received from Google APIs to any other app
will adhere to the Google API Services User Data Policy, including the Limited Use requirements.

도메인 소유권 인증(4번) — 「도메인 속성」으로 할 것

1. search.google.com/search-console → 속성 추가 → 도메인 → 루트 도메인 입력
2. google-site-verification=... TXT 값이 나온다
3. DNS에 TXT 추가 (네임서버가 Vercel이면 CLI로 바로):

npx vercel dns add <도메인> "@" TXT "google-site-verification=<받은값>" --scope <팀slug>

1. 전파 확인하고 서치콘솔에서 확인 클릭:

dig +short TXT <도메인> @8.8.8.8

게시하기

준비물이 다 차면 대상(Audience) → 앱 게시 → 확인. 게시 직후부터 토큰이 안 죽어. 게시하고 나서 gws auth login을 한 번 더 돌려 새 토큰을 받아두면 깔끔하게 마무리돼.

• gws auth login 하니 403 access_denied → 테스트 사용자 추가를 안 한 것. 대상 → 테스트 사용자에 내 계정 추가 후 재시도.
• 잘 쓰다가 갑자기 인증 에러가 난다 → 십중팔구 테스트 중 7일 만료. 6장 재로그인 한 방. 반복되면 7장으로 게시해.
• 앱 게시 버튼이 안 눌리거나 저장이 안 됨 → 브랜딩 화면에 빈 칸이 있는 것. 홈페이지·처리방침·승인된 도메인·개발자 연락처 4개를 확인.
• 승인된 도메인 넣었는데 "인증되지 않은 도메인" → 서치콘솔 소유권 인증이 안 된 것. OAuth 프로젝트와 같은 구글 계정으로 인증해야 해.
• 동의화면이 안 뜸 → 이미 구성된 프로젝트라 정상. 바로 클라이언트 만들기로.
• 브라우저가 안 열림 → ~/.config/gws/client_secret.json이 새 클라이언트 JSON인지 확인(gws auth status의 config_client_id).
• 인증 후 localhost 연결 거부 → 실패 아님. 케이스 B 상황이야. 그 주소창 URL 통째로 넘기면 돼.
• URL 넘겼는데 code 만료/무효 → 코드는 1회용에 금방 죽어. gws auth login부터 다시.