// auth and identity
Via APIKeycloak email verification with pingutil
Keycloak's registration page has reCAPTCHA but no email-quality check, so throwaway and dead addresses become users in your realm. Blocking at the form means a Java FormAction in the registration flow; most teams start with a review job instead: read REGISTER events from the Admin REST API, verify up to 50 addresses per pingutil batch call and disable the invalid ones.
Where it connects: Keycloak REGISTER events via the Admin REST API (review), or a custom registration FormAction (blocking)
What goes wrong without it
- Self-registration is on in our realm and the user list is full of addresses at temp-mail domains.
- Writing and deploying a Java SPI just to reject bad emails is more than we can take on right now.
- Our admins disable fake users by hand after someone complains about bounces.
What you can do with Keycloak and pingutil
Nightly or hourly review of new registrations
Poll GET /admin/realms/{realm}/events?type=REGISTER, verify the addresses with /v1/verify/batch, and set enabled: false on users whose status is invalid.
Block at the form with a FormAction
For a hard block, implement a FormAction whose validate() calls pingutil and returns context.validationError with a FormMessage, then add it to a copy of the registration flow.
Report risky accounts to admins
Collect status risky results (catch-all, role, randomized) into a report instead of disabling them, so a person decides.
Set it up
- 1
In Realm settings > Events, turn on saving user events and include the REGISTER event type.
- 2
Create a confidential client with a service account and give it the realm-management roles view-events and manage-users.
- 3
Run the script below on a schedule with KEYCLOAK_URL, KEYCLOAK_REALM, KC_CLIENT_ID, KC_CLIENT_SECRET and PINGUTIL_KEY set.
- 4
Pass the date of the last run as dateFrom (yyyy-MM-dd) so each run only sees new registrations.
- 5
For blocking at the form instead, follow the Server Developer Guide section on extending the registration form with a FormAction.
const KC = process.env.KEYCLOAK_URL!; // e.g. https://auth.example.com
const REALM = process.env.KEYCLOAK_REALM!;
async function adminToken(): Promise<string> {
const res = await fetch(KC + '/realms/' + REALM + '/protocol/openid-connect/token', {
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.KC_CLIENT_ID!,
client_secret: process.env.KC_CLIENT_SECRET!,
}),
});
return (await res.json()).access_token;
}
export async function reviewRegistrations(dateFrom: string) {
const headers = { authorization: 'Bearer ' + (await adminToken()), 'content-type': 'application/json' };
const events: { userId?: string; details?: { email?: string } }[] = await fetch(
KC + '/admin/realms/' + REALM + '/events?type=REGISTER&dateFrom=' + dateFrom + '&max=50',
{ headers },
).then((r) => r.json());
const regs = events.filter((e) => e.userId && e.details?.email);
if (regs.length === 0) return;
const res = await fetch('https://pingutil.com/v1/verify/batch', {
method: 'POST',
headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ emails: regs.map((e) => e.details!.email) }), // max 50 per call
});
if (!res.ok) return; // rate limited or quota used up: try again next run
const { results } = await res.json();
for (const [i, result] of results.entries()) {
if (result.status !== 'invalid') continue;
await fetch(KC + '/admin/realms/' + REALM + '/users/' + regs[i].userId, {
method: 'PUT',
headers,
body: JSON.stringify({ enabled: false }),
});
console.log('disabled', regs[i].details!.email, result.reason);
}
}What to do with each result
| pingutil result | Action in Keycloak |
|---|---|
| status: "invalid" (disposable_domain, mailbox_not_found, no_mx) | PUT the user with enabled: false |
| status: "risky" | Add to an admin review report; leave enabled |
| status: "valid" | No change |
| status: "unknown" | No change; optionally re-check on a later run |
| 429 or 5xx from pingutil | Stop the run and retry next time |
Limits to plan for
- The review job runs after registration, so throwaway users can sign in until the next run. Only a FormAction in the registration flow blocks at the form, and that requires a Java provider deployed to Keycloak.
- Keycloak only returns events it has saved. Event storage must be on with REGISTER included, and saved events expire according to your realm's expiration setting.
- Batch calls take up to 50 addresses and count toward 300 verified addresses a day (3,000 a month) per account; mailbox checks on slow servers can take several seconds per address. Those are Free plan limits; Enterprise has custom limits.
Keycloak documentation
- www.keycloak.org/docs/latest/server_development/index.html#modifying-or-extending-the-registration-form
- www.keycloak.org/docs-api/latest/rest-api/index.html
Keycloak is a trademark of its owner. This integration uses Keycloak's documented extension points; it is not an official Keycloak app.
Common questions
- Can I block bad emails on the Keycloak registration page without Java?
- Not with a supported extension point. Rejecting at the form needs a FormAction provider. Without Java, use the REGISTER event review job and disable users after the fact.
- Why /v1/verify/batch instead of one call per user?
- The job is not latency-sensitive, so one batch call per 50 registrations keeps you well under the 60 requests per minute limit and gives you mailbox status, not only the disposable check.
Stop bad addresses in Keycloak today
Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Keycloak setup will receive.