Skip to content

// auth and identity

Via API

Keycloak 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. 1

    In Realm settings > Events, turn on saving user events and include the REGISTER event type.

  2. 2

    Create a confidential client with a service account and give it the realm-management roles view-events and manage-users.

  3. 3

    Run the script below on a schedule with KEYCLOAK_URL, KEYCLOAK_REALM, KC_CLIENT_ID, KC_CLIENT_SECRET and PINGUTIL_KEY set.

  4. 4

    Pass the date of the last run as dateFrom (yyyy-MM-dd) so each run only sees new registrations.

  5. 5

    For blocking at the form instead, follow the Server Developer Guide section on extending the registration form with a FormAction.

Review job: REGISTER events to pingutil batch (Node 18+)
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 resultAction 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 pingutilStop 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

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.