8.4 KiB
8.4 KiB
title, source_type, url, archive_url, related_projects, related_branches, tags, status, confidence, created, last_reviewed
| title | source_type | url | archive_url | related_projects | related_branches | tags | status | confidence | created | last_reviewed | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ngrok — HTTP tunnel for local dev with external OAuth (official) | official-doc | https://ngrok.com/docs/universal-gateway/http/ |
|
|
|
raw | high | 2026-05-25 | 2026-05-27 |
ngrok — HTTP Tunnel (공식)
Layer:
raw/official-docs/— ngrok Universal Gateway / HTTP endpoints 페이지 verbatim. P3B 단일 EC2 + Google federation 학습 단계에서 public HTTPS URL + Google OAuth 호환을 빠르게 확보하는 개발 환경 대안의 1차 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-patterns | keycloak-patterns root — public 도메인이 필요한 외부 IdP federation 의 개발 환경 대안 |
| raw/branch-notes/feature-keycloak-single-ec2-google-federation | P3B 단일 EC2 학습 환경에서 ngrok 으로 Google OAuth callback redirect URI 확보 결정 근거 |
| raw/branch-notes/feature-keycloak-public-domain-tunneling | 자체 도메인 + Let's Encrypt vs ngrok / cloudflared tunneling 의 trade-off 비교 시 ngrok 측 baseline |
컨텍스트
Google OAuth 는 redirect URI 가 HTTPS + 도메인이어야 함 (localhost 예외). 자체 도메인 + Let's Encrypt 발급 + EC2 보안 그룹 80/443 개방 vs ngrok 1줄로 HTTPS public URL 발급. 학습 단계에서는 후자가 빠르지만 URL 이 매번 바뀌면 Google Console 등록을 매번 갱신해야 한다.
출처 / Source
- 원본 URL: https://ngrok.com/docs/universal-gateway/http/
- 아카이브 URL: (미수집)
- 저자 / 조직: ngrok
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27
핵심 인용 / Key quotes (verbatim)
[§Randomly assigned hostnames] "the command
ngrok http 80may create an endpoint likehttps://1eb2-181-80-12-3.ngrok.app."
[§Validation — URL Part defaults table] "Scheme |
https"
[§Bring your own domain] "Endpoints with randomly assigned hostnames are an exception and won't match an existing Domain object."
[§Bring your own domain] "If you want to bring your own domain, first create a Domain record and set up a DNS CNAME record. Then create an endpoint on that domain by specifying a URL with a matching hostname."
[§Google OAuth example] "The following example enforces a browser-based OAuth redirect flow in front of your endpoint using Google as the identity provider by using the OAuth Traffic Policy action."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| NGROK-C1 | ngrok http <port> 명령은 random hostname 의 HTTPS endpoint 를 생성 (예: https://1eb2-181-80-12-3.ngrok.app) |
[§Randomly assigned hostnames] "the command ngrok http 80 may create an endpoint like https://1eb2-181-80-12-3.ngrok.app." |
official-vendor-doc |
ngrok free plan 의 default 동작 | ngrok http 8080 의 정확한 출력 hostname 형식이 항상 <hash>-<ip>.ngrok.app 이라는 뜻 아님 — 시점/region 별 변경 가능 |
| NGROK-C2 | URL part default 의 scheme 은 https (HTTPS 가 default) |
[§Validation — URL Part defaults table] "Scheme | https" |
official-vendor-doc |
URL 명시 없이 endpoint 생성 시 |
| NGROK-C3 | random hostname endpoint 는 기존 Domain object 와 매칭되지 않음 (= reserved domain 자동 적용 안 됨) | [§Bring your own domain] "Endpoints with randomly assigned hostnames are an exception and won't match an existing Domain object." | official-vendor-doc |
ngrok 의 reserved domain 정책 | random hostname 의 lifetime / TTL 의 정확한 값은 본 인용 범위 밖 |
| NGROK-C4 | bring-your-own-domain 사용 시: (1) Domain record 생성 + DNS CNAME 설정 (2) 해당 hostname 으로 endpoint 생성 | [§Bring your own domain] "If you want to bring your own domain, first create a Domain record and set up a DNS CNAME record. Then create an endpoint on that domain by specifying a URL with a matching hostname." | official-vendor-doc |
고정 URL 이 필요한 OAuth callback 등록 시나리오 | paid plan 이 필수라는 뜻은 본 인용에 직접 없음 — pricing 별도 페이지 |
| NGROK-C5 | ngrok 의 Traffic Policy OAuth action 이 Google 을 IdP 로 사용하는 browser-based OAuth redirect flow 를 endpoint 앞단에서 enforce 가능 (공식 예제 존재) |
[§Google OAuth example] "The following example enforces a browser-based OAuth redirect flow in front of your endpoint using Google as the identity provider by using the OAuth Traffic Policy action." | official-vendor-doc |
ngrok Traffic Policy OAuth action 사용 | Keycloak 의 Google federation 을 대체한다는 뜻 아님 — ngrok 측 edge OAuth (다른 layer) |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
NGROK-C1:ngrok http <port>가 random HTTPS hostname 을 생성한다는 사실NGROK-C2: HTTPS 가 endpoint scheme defaultNGROK-C3: random hostname 은 Domain object 와 매칭되지 않음NGROK-C4: 자체 도메인 사용의 정확한 절차 (Domain record + DNS CNAME + endpoint URL)NGROK-C5: ngrok Traffic Policy 에 Google OAuth action 이 공식 예제로 존재한다는 사실
- 이 자료가 증명하지 않는 것:
- free plan vs paid plan 의 정확한 hostname 정책 (free 에서도 reserved domain 가능 여부)
- free plan 에서 재시작 시 새 hostname 으로 변경된다는 명시적 정책 (관행적 사실이나 본 페이지에 직접 인용 없음)
- Keycloak
KC_HOSTNAME+KC_PROXY_HEADERS=xforwarded설정과의 통합 정확성 - ngrok 의 inbound traffic 에 대한 rate limit / TLS termination 의 정확한 동작
- production 운영 적합성 (본 페이지는 개발/시연 도구로 자주 사용되지만 production 적합 여부 직접 언급 없음)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- free plan 에서
ngrok http 8080실행 시 재시작마다 hostname 이 변경되는지 (관행적 알려진 사실 → free plan 페이지 별도 확인) - paid plan 의 reserved domain 가격 + Google Cloud Console redirect URI 등록 절차
- Keycloak
KC_HOSTNAME=<ngrok-url>설정 시issclaim 의 정확한 형태와 backendissuer-uri동기화 절차
- free plan 에서
P3B 함의 (해석 — 내 프로젝트 메모)
본 섹션은 자료 직접 인용 아님. P3B 결정 컨텍스트 해석.
- 개발 환경: EC2 (또는 로컬) 에서
ngrok http 8080→ Keycloak 외부 HTTPS URL 확보 (NGROK-C1/C2). - Keycloak 설정:
KC_HOSTNAME=https://<ngrok-id>.ngrok.app+KC_PROXY_HEADERS=xforwarded(별도 raw/official-docs/keycloak-hostname-configuration 결합). - Google Cloud Console → Authorized redirect URIs 에
https://<ngrok-id>.ngrok.app/realms/dev/broker/google/endpoint등록. - URL 변경 friction (UNSUPPORTED — free plan 정책 별도 확인 필요): free plan 에서 ngrok 재시작 시마다 새 hostname → Keycloak
KC_HOSTNAME+ Google Console redirect URI 모두 갱신 필요. paid plan 의 reserved domain (NGROK-C4) 으로 고정 가능. - 운영 (prod) 용도 아님 — 어디까지나 학습/시연 (본 페이지 직접 인용 아님, 관행).
대안
- Cloudflare Tunnel (
cloudflared): 무료 + 안정적 hostname (Cloudflare 도메인 보유 시). raw/official-docs/cloudflare-tunnel-routing-official 참고. - 자체 도메인 + EC2 public IP + Let's Encrypt: 가장 운영-가까운 환경. P3B 본격 시도 시 권장.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/cloudflare-tunnel-routing-official (동일 카테고리 — 무료 tunneling 대안)
- raw/official-docs/google-oauth2-redirect-uri-validation-official (Google OAuth 의 redirect URI 검증 규칙)
- raw/official-docs/keycloak-hostname-configuration (Keycloak
KC_HOSTNAME결합)
- 인용하는 branch:
- 인용하는 wiki: (미작성)