@Mail Domain Check

Keycloak realm | Lost SMTP settings | Safe recovery

Keycloak Realm SMTP Settings Were Lost

If registration and password recovery stopped after a realm's email fields disappeared, do not guess a provider configuration and do not restore from an export that never contained SMTP values. Rebuild the sender from an owner-controlled source, prove one Keycloak test message, then prove the actual reset or verification workflow.

Repository-specific finding

In blue-core-lod/bluecore-workflows, the current realm file and all nine revisions in its file history contain "smtpServer": {}. There are no old host, sender, port, encryption, user, or credential values to recover from Git.

Do not use the empty export as a backup

Repository evidence
The versioned keycloak-export/bluecore-realm.json has an empty smtpServer object at every revision from its first commit through the current revision. Git cannot identify the former mail provider or secret.
Startup behavior
The development compose file mounts that realm file and starts Keycloak with --import-realm. Keycloak skips startup import when the realm already exists, so this path neither restores the missing SMTP fields nor overwrites the live realm during an ordinary restart.
Override risk
An explicit CLI import can override an existing realm. Running it with an empty smtpServer is a broad realm operation, not an SMTP repair. Rebuild email in the running realm and back it up deliberately after validation.

Browser-local recovery planner

Locate the first unproved recovery boundary

No domain, email address, SMTP host, port, username, password, token, realm export, provider payload, action link, cookie, authorization header, database row, or full log is requested or transmitted.

Rebuild from the owner, not from an example

  1. Identify the organization-controlled mailbox or transactional provider authorized to use the intended From address.
  2. From that source, record the non-secret field shape: host, port, implicit TLS or STARTTLS, authentication type, username identity, From, optional Reply-To, and optional envelope sender.
  3. Create or rotate a dedicated credential. Keep it in an owner-controlled secret store or Keycloak vault; never add it to the public realm JSON or an issue comment.
  4. If no owner-controlled source proves the old account, provision a new sender deliberately and verify its domain before changing Keycloak.

Keycloak's current administration guide defines From, Reply-To, envelope sender, host, port, encryption, authentication type and credential fields separately. A correct port does not prove the correct provider account, sender authorization or encryption mode.

What Test connection actually proves

Current Keycloak source handles POST /admin/realms/{realm}/testSMTPConnection by requiring realm-management permission and reading the current user. It returns an error when the logged-in administrator has no email address, then calls sendSmtpTestEmail(settings, user) only after that precondition passes.

If the UI sends a masked password or token secret, Keycloak reuses the stored secret only when authentication type, host, port and user still match the configured realm. After the configuration was lost, there is no old credential to reuse; a fresh owner-controlled secret is required.

A successful response means the test-send path did not throw. It is not proof that the receiving server accepted the message or that the administrator can see it. Match the same controlled attempt to a provider event and mailbox result.

Do not reopen registration after a generic test alone

  1. Receive one controlled Test connection message at the administrator address.
  2. Use a controlled non-admin user to request a password reset or the Verify Email required action.
  3. Confirm a provider event exists for that workflow message and the controlled mailbox receives the newest copy.
  4. Open the newest action link once and confirm it completes. Keep expired, malformed and replayed links rejected.
  5. Only then restore registration and password recovery for ordinary users.

Make the repaired state recoverable

Keycloak warns that Admin Console partial exports mask passwords and client secrets and are not suitable as backups. Use a controlled CLI export with Keycloak nodes stopped when you need a restorable realm backup, and keep the credential outside the public repository. Document who owns the sender, where the secret is rotated, and which controlled end-to-end test proves the mail path.

Do not run an override import against a live cluster. Keycloak's import documentation requires all nodes to be stopped for an override because the import command does not join the cache cluster.

Test connection returned an SMTP error?

Classify a redacted SMTP response locally, then repair only the first failing boundary. The pasted text never leaves the browser.

Decode the SMTP error locally

Primary references