6개월 전에 넘긴 자동화가 지난주부터 돌지 않습니다. 코드는 아무도 손대지 않았고 서버도 켜져 있는데, 로그에는 인증 실패만 쌓여 있습니다. 고객사는 먼저 개발사를 부릅니다.
이런 중단의 상당수는 코드가 아니라 구글 계정에 걸린 토큰이 수명을 다한 경우입니다. 구글은 토큰이 죽는 조건을 문서에 숫자로 적어 두었습니다. 그 숫자를 알면 원인 구분은 10분이면 끝나고, 모르면 며칠이 갑니다.
코드 문제인지 토큰 문제인지는 마지막 배포일로 먼저 가르세요
첫 번째 단서는 배포 이력입니다. 마지막 배포가 중단 시점보다 훨씬 앞서 있고 그 사이에 정상 동작했다면, 코드가 원인일 확률은 거의 없습니다. 코드는 스스로 변하지 않습니다.
두 번째 단서는 실패 지점입니다. 구글 API를 부르는 첫 요청에서 바로 거절당하면 인증 문제입니다. 반대로 데이터를 몇 건 처리한 뒤 특정 건에서 깨지면 코드나 데이터 문제입니다.
세 번째 단서는 주기성입니다. 중단 간격이 7일이나 6개월에 맞아떨어지면 구글이 못 박아 둔 만료 규칙에 걸린 것입니다. 아래에서 그 숫자를 하나씩 보겠습니다.
동의화면이 '테스트' 상태면 리프레시 토큰은 7일 만에 죽습니다
구글 공식 문서에 따르면, 외부 사용자 유형으로 설정한 OAuth 동의화면의 게시 상태가 '테스트'이면 발급되는 리프레시 토큰은 7일 후 만료됩니다. 이름과 이메일, 프로필에 해당하는 범위만 요청하는 경우에만 예외입니다.
테스트 상태는 동의화면에 등록한 테스트 사용자 100명까지만 쓸 수 있습니다. 개발 중에는 편하지만, 이 상태로 납품하면 고객이 매주 재인증을 눌러야 하는 자동화가 됩니다.
'프로덕션'으로 올리면 검증 절차가 따라옵니다
게시 상태는 앱 게시 버튼을 누르면 프로덕션이 되고, 그때부터 구글 계정이 있는 누구나 쓸 수 있습니다. 7일 만료도 함께 사라집니다. 문제는 그다음입니다.
민감하거나 제한된 범위를 요청하는 앱은 검증을 통과해야 합니다. 확인된 도메인의 홈페이지와 개인정보처리방침, 서치 콘솔의 도메인 소유 확인이 기본이고, 민감·제한 범위에는 사용 사례 설명과 시연 영상이 추가로 필요합니다.
제한된 범위는 한 단계 더 갑니다. 구글이 지정한 평가 기관의 연 1회 보안 평가를 받아 검증 레터를 받아야 하고, 매년 다시 받아야 합니다. 검증 전에 공개하면 미확인 앱 경고가 뜨고 신규 사용자 100명이라는 평생 한도가 걸리는데, 이 한도는 초기화되지 않습니다.
토큰 개수 한도를 넘기면 가장 오래된 토큰이 조용히 무효가 됩니다
구글은 하나의 OAuth 클라이언트 ID당, 구글 계정당 리프레시 토큰 100개까지만 유지합니다. 한도에 닿은 상태에서 새 토큰을 발급하면 가장 오래된 토큰이 경고 없이 무효가 됩니다.
같은 계정으로 재인증을 반복하거나 서버를 여러 대로 늘리면, 멀쩡히 돌던 쪽의 토큰이 먼저 죽습니다. 어디에서도 알림이 오지 않습니다.
전체 클라이언트를 합산한 더 큰 한도도 따로 있습니다. 구글은 한 계정에 승인하는 클라이언트를 15~20개로 제한하라고 권고합니다. 이 100개 한도는 서비스 계정에는 적용되지 않습니다.
비밀번호를 바꾸는 순간 Gmail 연동이 끊깁니다
공식 문서는 토큰이 멈추는 사유 중 하나로 사용자가 비밀번호를 변경했고 토큰에 Gmail 범위가 포함된 경우를 명시합니다. 보안 점검으로 비밀번호를 바꾼 다음 날 메일 자동화가 멈추는 이유가 이것입니다.
앱 비밀번호도 같습니다. 앱 비밀번호는 2단계 인증을 켠 계정에서만 만들 수 있고, 계정 비밀번호를 바꾸면 폐지됩니다. 생성할 때 한 번만 보여 주기 때문에 따로 보관해 두지 않았다면 복구가 아니라 재발급입니다.
6개월 쓰지 않으면 토큰도, 클라이언트도 지워집니다
리프레시 토큰은 6개월 동안 사용되지 않으면 무효가 됩니다. 분기 마감이나 연말 정산처럼 드물게 도는 자동화가 특히 위험합니다.
클라이언트 자체도 사라집니다. 6개월간 토큰 요청도 설정 변경도 없는 OAuth 클라이언트는 자동 삭제되고, 삭제 후 30일이 지나면 복구할 수 없습니다. 삭제된 클라이언트로 발급한 토큰의 호출은 전부 실패합니다.
담당자가 퇴사하면 그 사람 계정에 걸린 연동이 함께 죽습니다
구글 워크스페이스에서 사용자 계정을 삭제하면 그 계정의 모든 서비스와 데이터 접근이 끊깁니다. 복구는 삭제 후 20일 안에만 가능하고, 20일이 지나면 그 이메일 주소 자체가 조직에서 제거됩니다.
관리자가 특정 서비스를 제한으로 바꾸는 경우에도 연동은 멈추고, 이때는 admin_policy_enforced 오류가 돌아옵니다. 담당자 개인 계정으로 연결한 자동화는 인사와 보안 정책에 그대로 묶여 있는 셈입니다.
서비스 계정으로 옮기면 사람 계정에 걸린 사고가 사라집니다
서비스 계정은 개인이 아니라 애플리케이션에 속한 계정입니다. 앱이 비공개 키로 서명한 토큰 요청을 보내 액세스 토큰을 받고, 사용자가 중간에 끼지 않습니다. 동의화면도, 7일 만료도 없습니다.
워크스페이스 사용자 데이터를 다뤄야 하면 도메인 전체 위임을 씁니다. 수퍼 관리자가 관리 콘솔의 API 제어에서 서비스 계정의 클라이언트 ID와 허용 범위를 승인하는 방식입니다. 비밀번호 변경과 토큰 100개 한도, 퇴사를 모두 비켜 갑니다.
서비스 계정이 안 맞는 경우도 있습니다
서비스 계정은 워크스페이스 계정의 구성원이 아니고 도메인 정책의 적용도 받지 않습니다. 그래서 키를 가진 쪽이 사실상 전권을 갖습니다. 키 보관과 교체 책임을 계약서에 적어 두지 않으면 사고가 났을 때 책임 소재가 흐려집니다.
도메인 전체 위임은 수퍼 관리자만 승인할 수 있습니다. 고객사 IT가 승인을 거부하면 이 방식은 선택지에서 빠집니다. 워크스페이스가 아닌 개인 지메일 계정은 승인해 줄 관리자가 아예 없습니다.
위임을 받아도 해당 사용자가 접근할 수 없는 데이터에는 접근하지 못합니다. 권한을 넓혀 주는 장치가 아니라, 사람 계정의 수명에서 자동화를 떼어 내는 장치로 보는 것이 맞습니다.
유지보수 계약서에는 이 다섯 줄을 넣으세요
토큰 사고는 기술 문제이면서 동시에 계약 문제입니다. 누가 갱신하고 누가 알리는지 적혀 있지 않으면 멈춘 뒤에 책임 공방부터 시작합니다. 다음 항목을 과업 범위에 명시하세요.
- 연동 주체 명시: 자동화가 사용하는 구글 계정과 OAuth 클라이언트 ID를 계약서 별표에 적고, 계정 소유를 고객사 법인 계정으로 둡니다.
- 갱신 책임자: 재인증과 게시 상태 변경을 누가 수행하고 비용을 누가 부담하는지 정합니다.
- 알림 의무: 인증 실패를 감지하면 몇 시간 안에, 지정된 담당자 두 명 이상에게 통보합니다.
- 고객사 통지 의무: 담당자 변경, 계정 삭제, 비밀번호 정책 변경 전에 개발사에 알립니다.
- 검증 대응은 별도 과업: 프로덕션 전환과 민감·제한 범위 검증, 연 1회 보안 평가 대응의 비용과 기간을 따로 산정합니다.
알림은 사람의 기억에 기대지 말고 월 1회 자동 점검으로 돌리세요. 만료 규칙과 오류 조건은 구글 OAuth 2.0 공식 문서에서 확인할 수 있습니다. 비슷한 운영 사례는 업무 자동화 카테고리에 모아 두었고, 연동 설계 상담은 Codeforest로 보내 주세요.
결론: 멈춘 자동화는 코드보다 토큰을 먼저 의심하세요
배포 이력이 조용한데 첫 인증 요청에서 끊겼다면 코드를 열 필요가 없습니다. 게시 상태가 테스트인지, 7일이나 6개월 규칙에 걸렸는지, 비밀번호나 계정이 바뀌었는지를 순서대로 확인하는 쪽이 훨씬 빠릅니다.
재발을 막는 방법은 두 가지입니다. 사람 계정 대신 서비스 계정으로 옮기는 것, 그리고 갱신 담당과 알림 경로를 계약서에 적어 두는 것입니다. 둘 다 하지 않으면 같은 중단이 몇 달 뒤에 또 옵니다.