# Test Keycloak email verification with Playwright and a real inbox

Register a Keycloak user, read the verification email sent over SMTP, then check the user's emailVerified flag and sign in from a fresh browser.

A new user can appear in Keycloak's Admin Console while they're still waiting for the email that lets them finish registration. If a signup test stops when it finds the user record, it can pass even when the mail server rejected the message. Checking the inbox catches delivery failures. Checking the user again after clicking the link tells you whether verification actually worked.

In this example Playwright registers through Keycloak's own account console. MailSlurp provides a dedicated SMTP sender and a separate recipient inbox. We'll watch one user's verification flag change, set their password, and sign in from a browser that has never seen the registration page.

## How do I set up Keycloak for secure user authentication?

For the email-verification step, enable **User registration** and **Verify email** under **Realm settings → Login** and configure the sender under **Realm settings → Email**. In Keycloak 26.8.2 the default registration form in this configuration collects the name and email first. The password form comes after the user opens the verification link. That order determines what Playwright should wait for at each step. [Keycloak server administration guide](https://www.keycloak.org/docs/26.8.2/server_admin/)

### Run a disposable realm locally

[Open the runnable Keycloak example](https://github.com/mailslurp/examples/tree/master/keycloak-email-verification). On macOS or Linux, install OpenJDK 25 and Node.js 22.13 or newer, then extract the Keycloak 26.8.2 distribution. From the example directory:

```sh
npm ci
npx playwright install chromium
cp .env.example .env.local
```

Set `KC_HOME` to the extracted directory containing `bin/kc.sh`. Set `MAILSLURP_API_KEY` on the runner using a MailSlurp account with SMTP sending and inbox access. Run `npm test`. Playwright starts Keycloak on `127.0.0.1:38761` with an in-memory database. The runner creates a realm, configures it with the sender inbox's SMTP credentials, and opens the account console. [Keycloak installation guide](https://www.keycloak.org/getting-started/getting-started-zip)

## Register and read the first account state

The test chooses **Register**, enters the recipient address and a name, then submits the form. When the browser reaches **Email verification**, the runner searches the Admin API for the exact email address. It requires one matching record and saves its ID:

```js
const before = await readUser();
expect(before.emailVerified).toBe(false);
```

Now read the message delivered to that inbox after registration. The default template in this run identified the realm by its display name, explained why the user received the email, and gave the verification link a five-minute lifetime.



![Received Keycloak email with subject Verify email, a verification link, and a five-minute expiry](/_astro/delivered-email.CWlGy2u7_Z1548ks.webp)

The subject and body from the delivered message. The link is inactive in this local rendering.





### Follow the verification email Keycloak actually sent

Give each signup its own inbox and retrieve the link from the message that arrived for that user.

[Create a free MailSlurp account](https://app.mailslurp.com/sign-up/?onboardingRequest=testing)



## Open the link and finish password setup

The helper in the example accepts one distinct URL with the test server's origin, the realm's `/login-actions/action-token` path and a nonempty `key` parameter. Open it in the registering browser. Read the user again to confirm that the flag changed on the original account:

```js
const action = verificationLink(links, baseURL, realm);
await page.goto(action);
await expect.poll(async () => (await readUser()).emailVerified).toBe(true);
expect((await readUser()).id).toBe(before.id);
```

At this point the address is verified, but the user still needs a password. Keycloak now displays **Update password**. Submit the new password and wait for the account console's **Personal info** page.



![Keycloak Update password screen with empty New Password and Confirm password fields](/_astro/set-password.Bn6riOkT_Z2cdgIB.webp)

Following the verification link opened password setup for the newly registered user.



### Sign in from a fresh browser

Create a new Playwright context, visit the account console, and sign in with the same address and the password you just set. Reload **Personal info** and check its email field. This makes the last check independent of the browser session that opened the link.



![Keycloak Personal info after a fresh sign-in, with the username and email fields masked](/_astro/verified-account.U4PCQtYM_ZoWfPf.webp)

The new browser retrieved the submitted profile after reload. The test compared the full email address before masking it for the screenshot.



If registration reaches **Email verification** but the inbox stays empty, check the realm's sender address, SMTP credentials and TLS mode. If the email arrives but the browser cannot open the link, inspect its origin. This example sends a real email containing a loopback URL, so the browser must open it on the machine running Keycloak. For a hosted staging realm, the URL should contain that realm's public hostname.
