9.7 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Google OAuth 2.0 Web Server — Redirect URI Validation Rules | official-doc | https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation | raw | high |
|
|
|
2026-05-25 | 2026-05-27 |
Google OAuth 2.0 — Redirect URI Validation (공식)
Layer:
raw/official-docs/— Google Identity Platform 공식 문서 발췌. P3B (단일 EC2 + Google IdP brokering)의 redirect URI 공개 도달성 제약을 보여주는 1차 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-patterns | keycloak-patterns root — Google federation 변형(P3B)의 public domain 의무 제약 명시 |
| raw/branch-notes/feature-keycloak-single-ec2-google-federation | P3B 단일 EC2에서 Keycloak broker endpoint URL이 public HTTPS hostname을 가져야 하는 근거 |
| raw/branch-notes/feature-keycloak-google-redirect-uri-policy | Google Cloud Console authorized redirect URI 등록 정책 (exact match, HTTPS 강제, raw IP 금지) 근거 |
| raw/branch-notes/feature-keycloak-public-domain-tunneling | EC2가 raw IP만 가질 때 도메인 + tunneling (Cloudflare Tunnel / ngrok) 필요한 이유 |
컨텍스트
Keycloak이 Google을 외부 IdP로 등록하면, Google이 사용자 로그인 후 Keycloak의 broker endpoint(/realms/{realm}/broker/google/endpoint)로 redirect한다. 이 redirect URI는 Google Cloud Console의 OAuth 2.0 Client → Authorized redirect URIs에 등록되어야 하며, Google이 검증 규칙을 강제한다.
단일 EC2 환경에서는 Keycloak이 localhost:8080에 떠 있지만, Google의 브라우저-side redirect는 사용자 브라우저를 통한 redirect이므로 사용자가 도달할 수 있는 public hostname이 필요하다. (Google 서버가 Keycloak에 직접 호출하는 게 아니라, 사용자 브라우저가 Google → Keycloak으로 navigate.)
출처 / Source
- 원본 URL: https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation
- 아카이브 URL: (미수집)
- 저자 / 조직: Google — Identity Platform Documentation
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 완료 — 5개 quote 중 4개 verbatim MATCH; quote 5 는 라이브 문서가 다른 형식으로 표현, 2026-05-27 update 본 추가)
핵심 인용 / Key quotes (verbatim)
[§Redirect URI validation rules, 2026-05-27 verified MATCH] "Redirect URIs must use the HTTPS scheme, not plain HTTP. Localhost URIs (including localhost IP address URIs) are exempt from this rule."
[§Redirect URI validation rules, 2026-05-27 verified MATCH] "Hosts cannot be raw IP addresses. Localhost IP addresses are exempted from this rule."
[§Redirect URI validation rules, 2026-05-27 verified MATCH] "The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 client, which you configured in the API Console. If this value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch' error."
[§Redirect URI validation rules, 2026-05-27 verified MATCH] "Redirect URIs cannot contain the fragment component."
[§Redirect URI validation rules, 2026-05-25 capture — 형식 차이] "Wildcard characters" are not allowed in redirect URIs.
[§Redirect URI validation rules, 2026-05-27 verified verbatim] "Redirect URIs cannot contain certain characters including: Wildcard characters (
'*')"
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| GOOGLE-REDIR-C1 | Google OAuth 2.0 redirect URI는 HTTPS scheme 필수 (localhost URI는 예외) | [§Redirect URI validation rules] "Redirect URIs must use the HTTPS scheme, not plain HTTP. Localhost URIs (including localhost IP address URIs) are exempt from this rule." | official-vendor-doc |
Google Cloud Console의 OAuth 2.0 client 등록 | localhost 예외가 production에서도 유효하다는 뜻은 아님 — 단순 개발 편의 |
| GOOGLE-REDIR-C2 | redirect URI의 host는 raw IP 주소 금지 (localhost IP는 예외) | [§Redirect URI validation rules] "Hosts cannot be raw IP addresses. Localhost IP addresses are exempted from this rule." | official-vendor-doc |
EC2 public IP / GCE 인스턴스 IP 같은 raw IP를 redirect URI로 등록하려는 경우 | Cloudflare Tunnel의 <UUID>.cfargotunnel.com 같은 generic subdomain 등록 가능성은 본 인용 범위 밖 (별도 정책 확인 필요) |
| GOOGLE-REDIR-C3 | request의 redirect URI 값은 등록된 authorized redirect URI 중 하나와 정확히 일치해야 하며, 불일치 시 redirect_uri_mismatch 에러 발생 |
[§Redirect URI validation rules] "The value must exactly match one of the authorized redirect URIs for the OAuth 2.0 client, which you configured in the API Console. If this value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch' error." | official-vendor-doc |
Google Cloud Console에 등록된 모든 redirect URI 비교 시점 | "정확히 일치"의 trailing slash / case sensitivity / query string 정책 디테일은 본 인용 직접 다루지 않음 — 일반적 OAuth 관례상 byte-level exact match로 추정 (verification 필요) |
| GOOGLE-REDIR-C4 | redirect URI는 fragment component (#...) 를 포함할 수 없음 |
[§Redirect URI validation rules] "Redirect URIs cannot contain the fragment component." | official-vendor-doc |
Google OAuth 2.0 client redirect URI 등록 | Implicit flow의 fragment 응답 메커니즘과 별개 — 등록 URI 자체의 제약 |
| GOOGLE-REDIR-C5 | redirect URI에 wildcard character (* 등) 사용 불가 |
[§Redirect URI validation rules, 2026-05-27 verified] "Redirect URIs cannot contain certain characters including: Wildcard characters ('*')" |
official-vendor-doc |
다중 환경 (dev/staging/prod)에서 redirect URI 관리 시 | 각 환경마다 redirect URI를 개별 등록해야 한다는 결론은 본 인용에서 유도 가능, 단 환경 분리 best practice 자체는 별도 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
GOOGLE-REDIR-C1~C5: Google OAuth 2.0 redirect URI 등록 시 5가지 검증 규칙 (HTTPS, no-raw-IP, exact match, no fragment, no wildcard)
- 이 자료가 증명하지 않는 것:
- "exact match"의 byte-level 정확한 정의 (trailing slash, query string, encoding normalization) — 일반 관례에 의존
- localhost 예외가 production에서 사용 가능한지 (단순 개발 시나리오 권고만)
- Cloudflare Tunnel 의
<UUID>.cfargotunnel.com같은 generic subdomain이 "raw IP가 아니므로" 무조건 허용되는지 (별도 vendor 정책 확인 필요) - Google이 IP allowlist / domain ownership verification을 어떤 시점에 강제하는지 (별도 페이지: OAuth 동의 화면 설정)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- EC2 public IP만 가진 환경에서 Cloudflare Tunnel
<UUID>.cfargotunnel.com등록이 실제로 통과하는지 (P3B 실험 필요) - Keycloak의 broker endpoint URL이
KC_HOSTNAME+ realm 이름으로 자동 생성되므로, redirect_uri_mismatch 디버깅 시 Keycloak 측 issuer/hostname 설정 검증 필수 - ngrok 무료 plan의 매번 변경되는 URL을 매 세션마다 Google Console에 재등록하는 friction (개발 편의성 비교 시)
- EC2 public IP만 가진 환경에서 Cloudflare Tunnel
P3B 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아닌 패턴 결정 컨텍스트 해석. wiki 추출 시 옮겨야 함.
- HTTPS 강제:
http://redirect URI는localhost한정 예외. EC2 public IP/domain은 반드시 HTTPS. - Raw IP 금지: EC2 public IP (예:
https://3.34.12.5/...)는 등록 불가. 도메인이 필요. (localhost 예외이지만 단일 EC2 외부 노출 의미 없음.) - Exact match:
https://kc.example.com/realms/dev/broker/google/endpoint형태 그대로 등록. trailing slash, port, path 모두 정확히 일치해야 함. - No fragments / wildcards:
https://*.example.com/...또는https://example.com/#foo사용 불가. - 개발용 ngrok URL 사용 시 → 매번 새 URL → Google Console 등록 갱신 필요(=학습 friction).
메모 / Notes
- 2026-05-27 re-verification: WebFetch 재확인 완료. Quote 1~4 verbatim MATCH. Quote 5 의 라이브 본문은 "Wildcard characters" 단독 문장이 아니라 "Redirect URIs cannot contain certain characters including: Wildcard characters (
'*')" 형식의 enumeration 항목 — 2026-05-25 capture 가 단편화한 표현이었음. 라이브 verbatim quote 를 추가 보존. 의미는 동일하므로 GOOGLE-REDIR-C5 의 strength 는 official-vendor-doc 유지.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/cloudflare-tunnel-routing-official — public hostname 노출 수단 (raw IP 금지 → 도메인 필요한 결정의 해법)
- raw/official-docs/keycloak-reverseproxy-official — Keycloak이 broker endpoint URL을 어떻게 생성하는지 (
KC_HOSTNAME)
- 인용하는 branch:
- 인용한 wiki 요약: (미작성)