[Google OAuth][인증] redirect_uri_mismatch가 날 때 Cloud Console에서 먼저 볼 곳

IT 리서치 노트

[Google OAuth][인증] redirect_uri_mismatch가 날 때 Cloud Console에서 먼저 볼 곳

`redirect_uri_mismatch`는 Google OAuth에서 가장 흔하지만 가장 시간을 많이 잡아먹는 오류 중 하나다. 원인은 복잡해 보이지만 대부분은 클라이언트 유형, 등록된 URI, 실제 요청 URI 셋 중 하나가 정확히 맞지 않아서 생긴다. 중요한 점은 Google이 말하는 일치가 '대충 같은 경로'가 아니라 정확한 값 일치라는 점이다. 이 글은 어떤 콘솔 메뉴를 먼저 보고, 요청 로그에서 무엇을 복사하고, 로컬과 운영 URL을 어떻게 분리해야 하는지 설명한다.

목차

1. 개요
2. 어디서 막히는가
3. 실제로 해결하는 순서
4. 화면과 출력으로 확인하기
5. 주의할 점
6. 결론
7. 참고 링크

1. 개요

`redirect_uri_mismatch`는 Google OAuth에서 가장 흔하지만 가장 시간을 많이 잡아먹는 오류 중 하나다. 원인은 복잡해 보이지만 대부분은 클라이언트 유형, 등록된 URI, 실제 요청 URI 셋 중 하나가 정확히 맞지 않아서 생긴다.

중요한 점은 Google이 말하는 일치가 '대충 같은 경로'가 아니라 정확한 값 일치라는 점이다. 이 글은 어떤 콘솔 메뉴를 먼저 보고, 요청 로그에서 무엇을 복사하고, 로컬과 운영 URL을 어떻게 분리해야 하는지 설명한다.

• 이 글은 현재 공식 문서와 공개 도움말을 다시 확인한 뒤 정리했다.
• 설정 경로, 실패 지점, 검증 결과를 분리해서 읽으면 바로 실행에 옮기기 쉽다.
• 실제 운영에서는 권한, 비용, 배포 로그를 함께 봐야 같은 실수를 반복하지 않는다.

2. 어디서 막히는가

문제가 길게 보이더라도 실제 막힘은 몇 가지 패턴으로 모인다. 아래 증상 중 하나라도 보이면 설정값, 요청값, 실행 결과를 분리해서 기록하는 쪽이 빠르다.

• Cloud Console에는 URI를 등록했는데 여전히 mismatch가 난다.
• `http`와 `https`, trailing slash, 포트 번호 차이 같은 작은 차이를 놓친다.
• 웹 클라이언트와 네이티브 앱 클라이언트를 섞어 같은 redirect URI를 기대한다.
• 프록시와 reverse proxy 뒤에서 실제 요청 URI와 앱 설정값이 달라진다.

여기서 가장 흔한 실수는 증상만 보고 권한을 넓히거나 비용 플랜을 올리거나, 별도 로그 없이 다시 시도하는 것이다. 그러면 당장은 지나가도 다음 배포나 다음 운영 시간대에 같은 문제가 다시 나온다.

따라서 먼저 실제 값과 공식 기준이 어떻게 다른지 좁히고, 그 다음에 클릭, 입력, 실행, 저장 순서를 하나씩 재현해야 한다. 이 순서가 있어야 팀원끼리 같은 결과를 볼 수 있다.

문제정의 단계에서는 오류 문구 한 줄만 보는 대신, 어떤 메뉴에서 확인했고 어떤 필드가 비어 있었는지, 어떤 응답 상태가 먼저 나타났는지까지 적어두는 편이 좋다. 그래야 해결 단계에서 값을 바꾼 뒤에도 같은 기준으로 성공과 실패를 다시 비교할 수 있다.

특히 비용 문제나 권한 문제는 겉으로는 비슷하게 보여도 원인이 다르다. 청구 화면, 콘솔 설정, 배포 로그, 브라우저 요청, CLI 출력 가운데 무엇이 기준 화면인지 먼저 정하고 그 화면을 중심으로 확인해야 엉뚱한 메뉴를 오래 헤매지 않는다.

3. 실제로 해결하는 순서

아래 순서는 메뉴를 열고 값을 확인하고 결과를 다시 보는 실무용 순서다. 한 번에 모두 바꾸지 말고 한 단계씩 적용한 뒤 출력과 화면을 확인하는 편이 안전하다.

1. 오류 화면과 요청 로그에서 실제 redirect_uri 값을 그대로 복사한다.
2. Cloud Console Credentials의 해당 OAuth client에서 Authorized redirect URIs를 비교한다.
3. 클라이언트 유형이 web인지 desktop인지 먼저 확인한다.
4. 환경별 URL을 분리하고, 프록시를 쓴다면 최종 외부 URL 기준으로 다시 등록한다.

안전한 예제 코드

const params = new URLSearchParams({
  client_id: "YOUR_CLIENT_ID",
  redirect_uri: "https://example.com/auth/google/callback",
  response_type: "code",
  scope: "openid email profile",
});

console.log(`https://accounts.google.com/o/oauth2/v2/auth?${params}`);

실제 client ID와 도메인은 넣지 않는다. 중요한 것은 앱이 보내는 redirect URI 문자열을 그대로 로그로 남겨 비교하는 습관이다.

예제 코드는 흐름만 남겼다. 실제 토큰, 계정, 내부 서버 주소, 비공개 저장소 이름은 placeholder로 바꾸고 서버 환경변수나 보안 저장소로 분리한다.

중요한 점은 설정 변경 직후 바로 다음 단계로 넘어가지 않는 것이다. 각 단계마다 어떤 메뉴를 클릭했고, 어떤 값을 입력했고, 어떤 출력이 돌아왔는지 짧게라도 기록해야 한다. 그래야 실패했을 때 마지막으로 바뀐 값이 무엇인지 빠르게 되짚을 수 있다.

또한 해결 절차는 한 번 성공했다고 끝나지 않는다. 같은 절차를 다른 환경이나 다른 브랜치, 다른 계정에서도 다시 실행해 보고 결과가 같은지 확인해야 한다. 운영 환경과 로컬 환경의 URL, 권한, 캐시, 플랜, 리전 차이가 숨어 있으면 여기서 드러나는 경우가 많다.

4. 화면과 문서 기준으로 확인하기

아래 화면은 모두 실제 공식 문서 화면이다. 문서 제목, redirect_uri 규칙, 클라이언트 유형을 같은 순서로 확인하면 오류 원인을 더 빨리 좁힐 수 있다.

첫 화면에서는 문서가 웹 서버용 OAuth 흐름인지 먼저 확인한다. 같은 OAuth라도 클라이언트 유형이 다르면 리디렉션 처리 방식이 달라진다.

웹 서버 애플리케이션용 OAuth 문서인지 제목과 첫 설명으로 확인한다.

다음으로 클라이언트 라이브러리와 기본 요건을 본다. 서버 쪽 구현에서는 라이브러리가 redirect URL 생성과 토큰 갱신을 어떻게 맡는지 확인해야 한다.

클라이언트 라이브러리 섹션에서는 서버 쪽 구현에서 어떤 라이브러리와 기본 요건을 먼저 볼지 확인한다.

가장 중요한 기준은 redirect_uri 행이다. 이 문서가 말하는 일치는 비슷한 주소가 아니라 scheme, 대소문자, 경로, trailing slash까지 맞는 문자열 일치다.

redirect_uri 행에서는 값이 정확히 일치해야 하며, scheme과 trailing slash까지 비교해야 한다는 기준을 확인할 수 있다.

OpenID Connect 문서는 로그인 버튼과 ID 토큰 흐름을 함께 볼 때 필요하다. OAuth 2.0 설정과 인증 응답 위치를 같은 문맥에서 확인할 수 있다.

OpenID Connect 문서에서는 OAuth 2.0 설정과 인증 흐름이 같은 문서 안에서 어떻게 연결되는지 확인한다.

마지막으로 네이티브 앱 문서와 비교한다. 설치형 앱은 웹 서버 앱과 리디렉션 전제가 다르므로, 클라이언트 유형을 잘못 고른 경우에는 URI만 고쳐도 문제가 반복될 수 있다.

네이티브 앱용 OAuth 문서는 웹 서버 방식과 다른 리디렉션 전제를 비교할 때 확인한다.

이 순서로 보면 먼저 클라이언트 유형을 확인하고, 그 다음 redirect_uri 행의 정확한 일치 조건을 비교한 뒤, 실제 앱 로그의 요청값을 같은 기준으로 대조하면 된다.

5. 주의할 점

설정을 맞췄더라도 운영에서는 다시 틀어지는 지점이 있다. 아래 항목은 배포 직전과 배포 직후에 꼭 다시 점검할 부분이다.

• 요청 값과 콘솔 값을 눈으로만 보면 작은 차이를 놓치기 쉽다.
• 클라이언트 유형을 잘못 만들면 URI를 맞춰도 계속 실패할 수 있다.
• 변경 직후에는 전파 지연 가능성도 있으니 몇 분 뒤 재확인한다.

특히 권한, 비용, 캐시, 재시도 정책은 한 번 맞춘 뒤에도 환경이 바뀌면 다시 확인해야 한다. 문서가 바뀌었는지, 콘솔 기본값이 달라졌는지, 팀의 배포 방식이 바뀌었는지도 같이 본다.

6. 결론

오류가 나면 코드보다 먼저 실제 요청 URI를 복사한다.

• 오류가 나면 코드보다 먼저 실제 요청 URI를 복사한다.
• 운영 환경이 프록시 뒤에 있으면 외부 공개 URL 기준으로 본다.
• 로컬과 운영을 같은 client에 섞을지 별도 client로 나눌지 미리 정한다.

핵심은 추상적인 '좋은 설정'을 찾는 것이 아니라, 지금 내 서비스에서 어떤 값과 어떤 출력이 정답인지 빠르게 확인하는 것이다. 이 글의 순서대로 문서, 설정, 실행 결과를 묶어 보면 같은 문제를 다시 만났을 때 훨씬 빨리 끝낼 수 있다.

만약 URI 문자열은 이미 맞는데도 로그인 유지가 정확히 7일 전후로 끊긴다면, 값 일치 문제보다 앱 상태 문제일 가능성이 크다. 그 경우에는 오늘 정리한 Testing 상태 refresh token 7일 만료 분기 글로 이어서 보면 redirect 값 문제와 consent screen 상태 문제를 더 빠르게 나눌 수 있다.

7. 참고 링크

1. https://developers.google.com/identity/protocols/oauth2/web-server
2. https://developers.google.com/identity/openid-connect/openid-connect
3. https://developers.google.com/identity/protocols/oauth2/native-app