auth

Block personal emails in AWS Cognito

Use a Cognito pre sign-up Lambda trigger to deny personal, disposable and relay emails with isBusinessEmail, including first sign-ins through Google and other federated providers.

isBusinessEmail for AWS Cognito

AWS Cognito on its own

  • Anyone with a Gmail, Outlook or iCloud address can create an account
  • "Sign in with Google" lets personal Gmail accounts straight in
  • Throwaway inboxes restart free trials again and again
  • A hand-written domain check in your Lambda goes stale

AWS Cognito + isBusinessEmail()

  • Personal, disposable and relay addresses are stopped before the user exists
  • The same trigger covers Google, Apple and SAML first sign-ins
  • Typos get a "Did you mean gmail.com?" hint instead of a lost signup
  • You learn whether the company runs Google Workspace or Microsoft 365

Try it from your terminal

Before you set up AWS Cognito, see what the API returns. Test addresses need no key; for real addresses use a free key. Full reference.

# Test addresses need no key
curl -sG https://api.isbusinessemail.com/v1/check \
  --data-urlencode "[email protected]"

Amazon Cognito user pools call a pre sign-up Lambda trigger right before they create a new user. If the function throws an error, the user isn’t created. That makes it the right place to require a work email.

Unlike many auth providers, Cognito runs this trigger for every way a user can be created:

event.triggerSource When
PreSignUp_SignUp Self-service sign-up with email and password (the SignUp API, Hosted UI or Managed Login)
PreSignUp_ExternalProvider First sign-in through a federated provider: “Sign in with Google”, Apple, Facebook, SAML or OIDC
PreSignUp_AdminCreateUser An admin creates the user (AdminCreateUser)

So one function also covers “Sign in with Google”, where a personal @gmail.com account would otherwise get straight in.

1. Store the key

Put your ibe_live_… secret key in an environment variable on the function (IBE_API_KEY). For production, keep it in AWS Secrets Manager or SSM Parameter Store and load it once per container. Never put it in the browser or in the app client.

2. The Lambda function

Create a Node.js 20 or newer function (it has fetch built in, so there are no dependencies):

// index.mjs
const DENY_MESSAGE = 'Please sign up with your work email.';

export const handler = async (event) => {
  // Admins can create any user they like.
  if (event.triggerSource === 'PreSignUp_AdminCreateUser') return event;

  const email = event.request.userAttributes.email;
  if (!email) return event;

  let verdict;
  try {
    const res = await fetch('https://api.isbusinessemail.com/v1/check', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.IBE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, policy: 'b2b' }),
      signal: AbortSignal.timeout(2500),
    });
    if (!res.ok) return event;    // fail open: never block signups on our errors
    verdict = await res.json();
  } catch {
    return event;                 // timeout or network error: fail open
  }

  if (verdict.recommendation === 'block') {
    const hint = verdict.did_you_mean ? ` Did you mean ${verdict.did_you_mean}?` : '';
    throw new Error(`${DENY_MESSAGE}${hint}`);
  }

  return event;
};

Then attach it: Cognito → your user pool → Extensions (Lambda triggers) → Add Lambda trigger → Sign-up → Pre sign-up trigger. The console grants Cognito permission to invoke the function.

3. Show the message in your app

Cognito wraps the error. SignUp fails with UserLambdaValidationException and a message like:

PreSignUp failed with error Please sign up with your work email.

Strip the prefix before you show it:

try {
  await signUp({ username: email, password, options: { userAttributes: { email } } });
} catch (err) {
  if (err.name === 'UserLambdaValidationException') {
    showError(err.message.replace(/^PreSignUp failed with error\s*/, ''));
  } else {
    throw err;
  }
}

For federated sign-ins, Cognito redirects back to your callback URL with error_description in the query string instead. Read it on the callback page and show the same “use your work email” screen, with a link back to the sign-in page.

4. Store the verdict (optional)

A pre sign-up trigger can only allow or deny. It can’t add attributes to the new user. To keep the verdict, for example to route Google Workspace companies to a Google integration, add a post confirmation trigger that calls /v1/check again (the result is cached) and saves category, workspace.google_workspace.detected and workspace.microsoft_365.detected with AdminUpdateUserAttributes into custom attributes you defined on the pool. Or store them in your own database, keyed by the user’s sub.

Tips

  • Timeouts. Cognito waits about 5 seconds for a trigger and retries on timeout. Keep the API timeout around 2–3 s and fail open, so a slow network never locks people out.
  • Cold starts. Keep the function small and dependency-free. A cold start plus a check usually fits easily in the limit.
  • Policy. b2b blocks personal, disposable and relay addresses. Use policy: 'strict' if you need a company domain from day one (it also blocks unknown), or lenient to only stop disposable addresses.
  • Soft block. If you sell to freelancers and founders too, don’t throw. Let the user in and decide later from the stored verdict, for example a shorter trial or a talk with sales.
  • Test addresses. Sign up with [email protected] (denied) and [email protected] (allowed). See Test addresses.

Official docs: Pre sign-up Lambda trigger. See also: Sign-up form guide, Categories and policies and Block free emails at sign-up.