// auth and identity
Via APIWSO2 Identity Server and Asgardeo email verification with pingutil
Self-registration in Asgardeo or WSO2 Identity Server creates an account for any address that passes email OTP, and a temp-mail inbox passes OTP fine. A flow extension added to the Self Registration flow pauses the flow and calls your endpoint; your endpoint asks pingutil and answers FAILED with a reason the user sees, or SUCCESS to let the account be created.
Where it connects: Flow extension (FLOW_EXTENSION action) in the Self Registration flow of Asgardeo; documented for WSO2 Identity Server in the "next" docs
What goes wrong without it
- Throwaway inboxes get through email OTP, so our Asgardeo organization keeps gaining accounts nobody will ever use.
- We want to say no at registration, not disable accounts after someone notices them in the Console.
- Our flow extension has 3 seconds to answer, so whatever we call has to be fast.
What you can do with WSO2 Identity Server and Asgardeo and pingutil
Fail registration for disposable and randomized addresses
Your endpoint reads the email claim, calls POST /v1/lookup with skip_enrichment: true and returns actionStatus FAILED with a failureReason and failureDescription when verdict.is_spam is true.
Store the email risk on the new account
Create a custom attribute, mark it Write in the extension's access configuration, and return a replace operation with verdict.reason for role and sales addresses, so applications can treat them differently.
Tag work-email sign-ups
Write category (company, free, isp, educational) to the same kind of custom attribute, so downstream apps can route company sign-ups without another lookup.
Set it up
- 1
Deploy the endpoint below on HTTPS with PINGUTIL_KEY and EXT_TOKEN set.
- 2
In the Console, go to Connections, click New Connection, select Create Flow Extension, enter your endpoint and choose the Bearer authentication scheme with EXT_TOKEN.
- 3
In the extension's Access Configuration tab, mark the email attribute as Read; if you want to store the risk, create a custom attribute and mark it Write.
- 4
Go to Flows, open Self Registration, drag a Flow Extension View between the Email OTP view and the End node, and select your extension in the Connection dropdown.
- 5
Save the draft, publish the flow with the toggle, and register with a disposable address to see the failure message.
import express from 'express';
const app = express();
app.use(express.json());
const EMAIL = 'http://wso2.org/claims/emailaddress';
// Optional custom attribute you created and marked Write.
const RISK = 'http://wso2.org/claims/emailRisk';
app.post('/wso2/flow-extension', async (req, res) => {
if (req.get('authorization') !== 'Bearer ' + process.env.EXT_TOKEN) return res.status(401).end();
const ok = { actionStatus: 'SUCCESS' };
const claims: { uri: string; value: string }[] = req.body?.event?.flow?.user?.claims ?? [];
const email = claims.find((c) => c.uri === EMAIL)?.value;
if (!email) return res.json(ok);
let data;
try {
const r = await fetch('https://pingutil.com/v1/lookup', {
method: 'POST',
headers: {
authorization: 'Bearer ' + process.env.PINGUTIL_KEY,
'content-type': 'application/json',
},
body: JSON.stringify({ input: email, skip_enrichment: true }),
signal: AbortSignal.timeout(1500), // the flow extension call times out at 3 s
});
if (!r.ok) return res.json(ok); // 429 or 5xx: fail open
data = await r.json();
} catch {
return res.json(ok); // an ERROR or no answer would abort the flow, so allow instead
}
if (data.verdict?.is_spam) {
return res.json({
actionStatus: 'FAILED',
failureReason: 'Email address not accepted',
failureDescription: 'Please register with a permanent email address.',
});
}
const allowed: string[] = (req.body.allowedOperations ?? []).flatMap((o: { paths?: string[] }) => o.paths ?? []);
const riskPath = '/user/claims[uri=' + RISK + ']';
if (data.verdict?.low_trust && allowed.includes(riskPath)) {
return res.json({
actionStatus: 'SUCCESS',
operations: [{ op: 'replace', path: riskPath, value: data.verdict.reason }],
});
}
return res.json(ok);
});
app.listen(3000);What to do with each result
| pingutil result | Action in WSO2 Identity Server and Asgardeo |
|---|---|
| verdict.is_spam: true, reason "disposable_domain" | Return actionStatus FAILED with failureReason and failureDescription |
| verdict.is_spam: true, reason "randomized_local_part" | Return FAILED; the account is not created |
| verdict.low_trust: true | Return SUCCESS with a replace operation on your custom risk attribute |
| category: "free" or "company" | Return SUCCESS |
| Timeout, 429 or 5xx from pingutil | Return SUCCESS (fail open); ERROR or no response aborts the user's flow |
Limits to plan for
- WSO2 documents a 3-second timeout for the flow extension call, and an ERROR status or no response aborts the registration. That rules out a mailbox check here; use fast-mode /v1/lookup and verify mailboxes later with /v1/verify/batch if you need it.
- Flow extensions are documented for Asgardeo and in the WSO2 Identity Server "next" docs; the 7.2 and 7.3 docs do not include them. They apply to the flow-based Self Registration, not to users created by admins or through SCIM.
- Each registration counts toward 2,000 lookups a day (30,000 a month) per account. Those are Free plan limits; Enterprise has custom limits.
WSO2 Identity Server and Asgardeo documentation
- wso2.com/asgardeo/docs/guides/flows/flow-extension-external-service/
- wso2.com/asgardeo/docs/guides/flows/flow-extension-configuration/
- is.docs.wso2.com/en/next/guides/flows/flow-extension-external-service/
WSO2 Identity Server and Asgardeo is a trademark of its owner. This integration uses WSO2 Identity Server and Asgardeo's documented extension points; it is not an official WSO2 Identity Server and Asgardeo app.
Common questions
- Does this work on WSO2 Identity Server 7.x?
- The flow extension is documented for Asgardeo and in the WSO2 Identity Server docs for the next release. If your Identity Server version has no Create Flow Extension option under Connections, this extension point is not available to you yet.
- Why return SUCCESS when pingutil fails?
- WSO2 treats an ERROR response, an error status or a missing answer as a failure and aborts the flow. Returning SUCCESS on a pingutil timeout or 429 means a real person can still register when the check cannot run.
Stop bad addresses in WSO2 Identity Server and Asgardeo 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 WSO2 Identity Server and Asgardeo setup will receive.