From eacc0e86c975e59315393bbd5e7b72b9ba6b4ed0 Mon Sep 17 00:00:00 2001
From: donghyeon-ka <ehdgus6435@kumoh.ac.kr>
Date: Sat, 25 Jul 2026 16:31:13 +0900
Subject: [PATCH] feat: add validated named tunnel profile

---
 deploy/tunnel/cloudflared-config.yml   |  7 +++++++
 docs/public-domain-tunneling.md        | 21 +++++++++++++++++++++
 scripts/verify-public-tunnel-config.sh | 15 +++++++++++++++
 3 files changed, 43 insertions(+)
 create mode 100644 deploy/tunnel/cloudflared-config.yml
 create mode 100644 docs/public-domain-tunneling.md
 create mode 100755 scripts/verify-public-tunnel-config.sh

diff --git a/deploy/tunnel/cloudflared-config.yml b/deploy/tunnel/cloudflared-config.yml
new file mode 100644
index 0000000..028ceff
--- /dev/null
+++ b/deploy/tunnel/cloudflared-config.yml
@@ -0,0 +1,7 @@
+tunnel: 00000000-0000-0000-0000-000000000000
+credentials-file: /etc/cloudflared/00000000-0000-0000-0000-000000000000.json
+
+ingress:
+  - hostname: auth.example.test
+    service: http://reverse-proxy:8080
+  - service: http_status:404
diff --git a/docs/public-domain-tunneling.md b/docs/public-domain-tunneling.md
new file mode 100644
index 0000000..676232d
--- /dev/null
+++ b/docs/public-domain-tunneling.md
@@ -0,0 +1,21 @@
+# Public HTTPS domain for broker callbacks
+
+Google brokering을 반복 테스트할 때는 Cloudflare **named tunnel + 관리
+도메인**을 기본 profile로 사용한다. `trycloudflare.com` quick tunnel과
+임의 ngrok URL은 일회성 데모용이며 고정 callback으로 간주하지 않는다.
+
+설정 순서:
+
+1. `cloudflared tunnel login`
+2. `cloudflared tunnel create keycloak-patterns`
+3. 예제 config의 tunnel UUID와 credentials path를 실제 값으로 교체
+4. `cloudflared tunnel route dns keycloak-patterns auth.example.test`
+5. `cloudflared tunnel run keycloak-patterns`
+6. Keycloak `KC_HOSTNAME`과 Google redirect URI를 같은 public host로 설정
+
+컨테이너 안의 `127.0.0.1`은 cloudflared 컨테이너 자신이므로 origin에는
+`reverse-proxy:8080` 같은 Compose service DNS를 사용한다. 마지막 catch-all
+ingress는 알 수 없는 hostname을 404로 끝낸다.
+
+실 tunnel 생성과 DNS 변경에는 사용자 소유 계정·도메인이 필요하므로 자동
+검증은 ingress 파일의 구조까지만 수행한다.
diff --git a/scripts/verify-public-tunnel-config.sh b/scripts/verify-public-tunnel-config.sh
new file mode 100755
index 0000000..dec857b
--- /dev/null
+++ b/scripts/verify-public-tunnel-config.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+set -eu
+
+config=deploy/tunnel/cloudflared-config.yml
+grep -q '^tunnel: [0-9a-f-]*$' "$config"
+grep -q '^  - hostname: auth.example.test$' "$config"
+grep -q '^    service: http://reverse-proxy:8080$' "$config"
+grep -q '^  - service: http_status:404$' "$config"
+
+docker run --rm \
+  -v "$PWD/$config:/etc/cloudflared/config.yml:ro" \
+  cloudflare/cloudflared:2025.6.1 \
+  tunnel --config /etc/cloudflared/config.yml ingress validate
+
+echo "Cloudflare named-tunnel ingress configuration verified"