Keycloak prod SMTP 설정 — 비밀번호 찾기 / 메일 검증 (#2101)

상태: 런북 준비 완료 — 실제 적용은 자격증명 확보 + 정비창 게이트. 자율 적용 불가(자격증명 필요).

결정 (2026-06-21, #2101 결정 7)

• 메일 릴레이 = Google Workspace SMTP relay (smtp-relay.gmail.com). 비번재설정은 저빈도 트랜잭션이라 신규 SaaS(SendGrid) 대신 보유한 Workspace 릴레이 사용 — 신규 벤더·비용 0, genon.ai SPF/DKIM 이미 설정됨.
• resetPasswordAllowed=true 활성화 (Forgot Password 링크 노출 — UI 진입은 #1959 fix 로 이미 해소).
• verifyEmail=true 활성화 (가입 메일 검증 — 가짜가입 차단 + Kind export 와 정합).

현 상태 (2026-06-12 admin API 실측)

플래그	값
registrationAllowed	true (#1959)
resetPasswordAllowed	false → true 로 전환
verifyEmail	false → true 로 전환
smtpServer	{} → 아래 설정 주입

⚠️ realm 드리프트: prod realm 은 분리된 진실원천. infra/keycloak/base/realm-export.json 은 Kind 전용 — prod 에 직접 import 금지. prod 변경은 admin API 또는 콘솔로만.

절차 (자격증명 확보 후, 정비창)

1. Google Workspace 릴레이 + Vault 자격증명

1. Google Workspace Admin → Apps → Gmail → Routing → SMTP relay service 에 AKS egress(또는 genon.ai 인증 발신) 허용 등록. 또는 전용 발신계정 noreply@genon.ai 의 앱 비밀번호 발급(2FA 계정 한정).
2. Vault 에 등록:

   vault kv put secret/gend/keycloak-smtp \
     SMTP_USER="noreply@genon.ai" \
     SMTP_PASSWORD="<Workspace 앱 비밀번호 / relay 자격증명>"

3. ESO 적용 → K8s Secret keycloak-smtp 생성 확인:

   kubectl --context aks-genos-prod apply -f infra/external-secrets/keycloak-smtp-externalsecret.yaml
   kubectl --context aks-genos-prod get secret keycloak-smtp -n gend   # ESO 1m 폴링 후

2. realm smtpServer 주입 (admin API)

Keycloak realm 은 secret 참조를 직접 못 하므로, keycloak-smtp Secret 을 읽어 admin API 로 주입한다(자격증명을 git 에 두지 않는 경로):

KC=https://gend.genon.ai/auth
ADMIN_TOK=$(curl -s -f "$KC/realms/master/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=admin-cli \
  -d username="$KC_ADMIN" -d password="$KC_ADMIN_PASS" | jq -r .access_token)
if [ -z "$ADMIN_TOK" ] || [ "$ADMIN_TOK" = "null" ]; then
  echo "Error: admin 토큰 발급 실패 (자격증명/네트워크 확인)" >&2
  exit 1
fi
# go-template + base64decode 로 디코딩 — `base64 -d`(GNU) vs `base64 -D`(macOS BSD) 차이 회피
SMTP_USER=$(kubectl --context aks-genos-prod get secret keycloak-smtp -n gend -o go-template='{{.data.SMTP_USER | base64decode}}')
SMTP_PASS=$(kubectl --context aks-genos-prod get secret keycloak-smtp -n gend -o go-template='{{.data.SMTP_PASSWORD | base64decode}}')

curl -s -X PUT "$KC/admin/realms/gend" \
  -H "Authorization: Bearer $ADMIN_TOK" -H 'Content-Type: application/json' \
  -d "$(jq -n --arg u "$SMTP_USER" --arg p "$SMTP_PASS" '{
    smtpServer: {
      host: "smtp-relay.gmail.com",
      port: "587",
      from: "noreply@genon.ai",
      fromDisplayName: "GenD",
      replyTo: "noreply@genon.ai",
      ssl: "false",
      starttls: "true",
      auth: "true",
      user: $u,
      password: $p
    },
    resetPasswordAllowed: true,
    verifyEmail: true
  }')"

포트 587 + starttls=true (Workspace 릴레이 권장). 465 SSL 을 쓰면 ssl=true,starttls=false,port=465.

3. 검증 (E2E)

1. Test connection: 콘솔 Realm Settings → Email → Test connection (또는 admin API testSMTPConnection).
2. Forgot Password: 로그인 페이지 → Forgot Password → 테스트 계정 메일 수신 확인 → 링크로 재설정 완료.
3. verifyEmail: 신규 가입 → 검증 메일 수신 → 링크 클릭 → 계정 활성 확인.
4. 발신 도메인 SPF/DKIM 정합(스팸함 직행 여부) 확인.

롤백

# smtpServer 비우고 플래그 원복
curl -s -X PUT "$KC/admin/realms/gend" -H "Authorization: Bearer $ADMIN_TOK" \
  -H 'Content-Type: application/json' \
  -d '{"smtpServer":{},"resetPasswordAllowed":false,"verifyEmail":false}'

참고

• UI 진입(Forgot Password 링크 → KC 페이지)은 #1959 fix 로 이미 400 해소 — 본 작업은 순수 ops.
• ESO/Vault 운영: project_eso_prod_status, project_vault_prod_install_done.
• realm 드리프트: prod 분리 진실원천 — project_kind_oidc_url_chain.