pal-e-docs

Phase 28: Keycloak SMTP — Platform Email Foundation

phase-pal-e-platform-28-keycloak-smtp Phase

phase
Project
Goal: Configure Keycloak SMTP on westside-basketball realm so all apps inherit password reset, email verification, and execute-actions-email natively.
Owner: Dev agent
Repo: forgejo_admin/pal-e-platform (Keycloak admin API config)
Depends on: None (first platform phase in this stream)

Scope

  • Configure SMTP on westside-basketball realm via Keycloak Admin API (PUT /admin/realms/westside-basketball with smtpServer payload)
  • NOT Terraform — per Keycloak Terraform onboarding design (2026-03-21), SMTP was explicitly excluded from var.keycloak_realms. Manual admin API is appropriate for one-time realm config.
  • Gmail app password via smtp.gmail.com:587 (per feedback_gmail_oauth_not_smtp.md: OAuth for app email, app password for Keycloak SMTP)
  • From address: westsidebasketball@gmail.com, display name: "Westside Kings & Queens"
  • Pre-req: Gmail account must have 2FA enabled and an app password generated

Acceptance Criteria

  • Keycloak realm westside-basketball has SMTP configured
  • "Forgot Password?" on Keycloak login page sends a real email
  • Player can click the link and set a new password
  • From address is westsidebasketball@gmail.com
  • Tested with a real email address (not @example.com)

Deliverables

  • SMTP configured on westside-basketball realm
  • Runbook added to sop-secrets-management for Gmail app password rotation