llm-wiki/raw/official-docs/ngrok-http-tunnel-official.md

---
title: ngrok — HTTP tunnel for local dev with external OAuth (official)
source_type: official-doc
url: https://ngrok.com/docs/universal-gateway/http/
archive_url:
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-patterns, feature-keycloak-single-ec2-google-federation, feature-keycloak-public-domain-tunneling]
tags: [keycloak-patterns, p3b-single-ec2-google, ngrok, public-uri, oauth-callback, local-dev, official-doc]
status: raw
confidence: high
created: 2026-05-25
last_reviewed: 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 80` may create an endpoint like `https://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 생성 시 | HTTP 강제 옵션이 없다는 뜻 아님 — URL 명시 시 변경 가능 |
| 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 default
  - `NGROK-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>` 설정 시 `iss` claim 의 정확한 형태와 backend `issuer-uri` 동기화 절차

## 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:
  - [[raw/branch-notes/feature-keycloak-patterns]]
  - [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] (P3B)
  - [[raw/branch-notes/feature-keycloak-public-domain-tunneling]]
- 인용하는 wiki: (미작성)