Bug: Keycloak SMTP not configured — password reset emails don't send #131

New issue

Closed

opened 2026-03-21 16:01:47 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-03-21 16:01:47 +00:00

Owner

Type

Bug

Lineage

plan-wkq → Phase 11 (Girls Tryout — March 24)
Discovered during E2E registration validation

Repo

forgejo_admin/basketball-api (Keycloak infra, not code)

What Broke

Keycloak's "Forgot Password?" flow shows a success page but no email is ever sent. The realm has no SMTP server configured (smtpServer: {}). Players who forget their password have no self-service recovery path — every reset requires admin API intervention.

Confirmed via Keycloak admin API:

curl .../admin/realms/westside-basketball → smtpServer: {}

Repro Steps

Go to westsidekingsandqueens.tail5b443a.ts.net/signin
Click "Sign In" → Keycloak login page
Click "Forgot Password?"
Enter any valid player email, click Submit
See "You should receive an email shortly" message
No email arrives — ever

Expected Behavior

Player receives a password reset email from westsidebasketball@gmail.com with a one-time link to set a new password.

Environment

Cluster/namespace: keycloak namespace
Realm: westside-basketball
Related alerts: none — silent failure

Acceptance Criteria

Keycloak realm westside-basketball has SMTP configured
"Forgot Password?" sends a real email to the player
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)

Fix

Configure Keycloak SMTP via admin API:

curl -X PUT .../admin/realms/westside-basketball \
  -d '{"smtpServer": {
    "host": "smtp.gmail.com",
    "port": "587",
    "from": "westsidebasketball@gmail.com",
    "fromDisplayName": "Westside Kings & Queens",
    "auth": "true",
    "starttls": "true",
    "user": "westsidebasketball@gmail.com",
    "password": "<gmail-app-password>"
  }}'

Requires a Gmail App Password (2FA must be enabled on the Gmail account).

feedback_gmail_oauth_not_smtp.md — decision: Keycloak SMTP = Gmail app password
reference_gmail_oauth.md — Gmail OAuth re-auth procedure
westside-app #57 — spike that led to this discovery
David Kaneko (player ID 99) — first reported player unable to log in

### Type Bug ### Lineage `plan-wkq` → Phase 11 (Girls Tryout — March 24) Discovered during E2E registration validation ### Repo `forgejo_admin/basketball-api` (Keycloak infra, not code) ### What Broke Keycloak's "Forgot Password?" flow shows a success page but **no email is ever sent**. The realm has no SMTP server configured (`smtpServer: {}`). Players who forget their password have no self-service recovery path — every reset requires admin API intervention. Confirmed via Keycloak admin API: ``` curl .../admin/realms/westside-basketball → smtpServer: {} ``` ### Repro Steps 1. Go to `westsidekingsandqueens.tail5b443a.ts.net/signin` 2. Click "Sign In" → Keycloak login page 3. Click "Forgot Password?" 4. Enter any valid player email, click Submit 5. See "You should receive an email shortly" message 6. No email arrives — ever ### Expected Behavior Player receives a password reset email from `westsidebasketball@gmail.com` with a one-time link to set a new password. ### Environment - Cluster/namespace: keycloak namespace - Realm: westside-basketball - Related alerts: none — silent failure ### Acceptance Criteria - [ ] Keycloak realm `westside-basketball` has SMTP configured - [ ] "Forgot Password?" sends a real email to the player - [ ] 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) ### Fix Configure Keycloak SMTP via admin API: ```bash curl -X PUT .../admin/realms/westside-basketball \ -d '{"smtpServer": { "host": "smtp.gmail.com", "port": "587", "from": "westsidebasketball@gmail.com", "fromDisplayName": "Westside Kings & Queens", "auth": "true", "starttls": "true", "user": "westsidebasketball@gmail.com", "password": "<gmail-app-password>" }}' ``` Requires a Gmail App Password (2FA must be enabled on the Gmail account). ### Related - `feedback_gmail_oauth_not_smtp.md` — decision: Keycloak SMTP = Gmail app password - `reference_gmail_oauth.md` — Gmail OAuth re-auth procedure - westside-app #57 — spike that led to this discovery - David Kaneko (player ID 99) — first reported player unable to log in

forgejo_admin referenced this issue

2026-03-21 16:10:55 +00:00

Feature: Password reset flow via Gmail OAuth (bypass Keycloak SMTP) #132

forgejo_admin commented

2026-03-21 16:11:04 +00:00

Author

Owner

Superseded by #132 — building password reset flow through basketball-api's existing Gmail OAuth pipeline instead of configuring Keycloak SMTP. The platform decision is OAuth everywhere, no app passwords.

forgejo_admin referenced this issue from a commit

2026-03-24 20:46:25 +00:00

feat: add SMTP server support to Keycloak realm config

forgejo_admin closed this issue

2026-03-24 20:54:03 +00:00