diego-parrilla

Diego is a Security Software Architect at the Office of the CTO team (OCTO). It has been a long journey since his dad bought his first eight-bit computer in the early 80s. He joined Auth0 after the acquisition of Apility.io in October 2019, and now he is looking for new ways to improve how Auth0 detects and stops potential threats. When he's not working, Diego loves participating in open source communities, riding his mountain bike, listen 80s and 90s hard rock music, watching NBA games, and traveling with his wife and teenage daughter.

Security Software Architect at OCTO

Diego Parrilla

Assess your users' reputation using the Auth0 Signals Email Verification API.



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>Important Information</strong><br> 
  <b>The Apility.io and Signals web properties and public APIs are no longer available. For more details, please refer to this <a href="https://auth0.com/blog/auth0-sunsets-signals/">blog post</a>.</b><br> 
</div>

**TL;DR:** How often do you feel that there is something wrong with the email address of that new customer? The username and the domain look suspicious. With the new risk assessment features of the Email Verification API, you can get enough insights to make informed decisions about your users in real-time.

## The Problem

There is a rising wave of abusers that sign up to services offering freemium or free-trial. Typically they want to exploit the resource you offer (compute, streaming, APIs, etc). The tension lies between converting more vs stopping these abusers.

One way to stop them, without introducing much friction, is to verify if their email is legitimate (without sending all users an email). This is what the Auth0 Signals Email Verification API provides.

## What is the Auth0 Signals API?

The [Auth0 Signals API](https://auth0.com/signals) is a standalone free service for the community. The service consists of an HTTP API that allows you to detect the reputation of an Email address or the IP address. The API checks the Email and/or IP address against several public denylists to evaluate its reputation. It responds with data about the originator and a score indicating the reliability level of the Email or IP address. Having this information enables you to detect malicious activities proactively.

## When to use Email Verification signal?

The Email Verification signal provides a continually curated and accurate Email reputation data. It takes the hard work out of consuming Open-Source Intelligence (OSINT) by curating, parsing, and normalizing numerous denylists. Auth0 uses this data to protect its own service.

There are two main use cases for this API:

- **Real-time risk assessment:** Developers can embed into their code requests to the API and detect malicious activity proactively, not reactively. For example, automatically checking Email reputation during the authentication flow. With a disclaimer that it’s free, no SLA and rate limits are in place.
- **Incident response and forensics:** When security experts identify an incident, they begin investigation and response processes to determine if a genuine security incident occurred, its scope, and the best way to remediate the threat. The API and some assessment tools will become part of the Security professionals swiss army knife.

Auth0 Email verification signal enables all users to obtain a score that indicates the risk level of an analyzed Email address. The overall process involves an in-depth analysis of each email,  combining several validation techniques based on custom-built algorithms scoring the legitimacy of an email. Clean and valid email addresses will have a neutral score. Suspicious addresses will have a negative rating: the more negative the score, the more probability of being an address with a low reputation.

## How does the Email Verification API work?

First [sign up in Auth0 Signals and get an API Key](https://auth0.com/signals). If you have any doubt, you can [read this short tutorial detailing all the steps](https://community.auth0.com/t/how-to-obtain-an-auth0-signals-api-key/42048)
The [API documentation in the Auth0 Signals site](https://auth0.com/signals/docs/#email-verification) explains how to use the service with or without an API Key. For example, let’s get the score for the email ```test@example.com```. We will assume that ```example.com``` is a very well known [Disposable Email Address](https://en.wikipedia.org/wiki/Disposable_email_address) provider, so it should have a negative rating. To test the API, we will use the command ```curl```. The requests need two parameters: the Auth0 Signals API Key and the Email to analyze. It’s also possible to add parameters in the query string to tweak how the service works.

```shell
$ curl -i -H "Accept: application/json" -H "X-Auth-Token: API_KEY" -X GET "https://signals.api.auth0.com/bademail/test@example.com"
```

or

```shell
$ curl -H "Accept: application/json" -X GET "https://signals.api.auth0.com/bademail/test@example.com?token=API_KEY"
```

the JSON response will be:

```
{
   "response":{
      ...
      "score":-3,
      "email_address":"test@example.com"
   },
   "type":"bademail"
}
```

We have trimmed the JSON object of the response to make this post more readable, but you can [read the full JSON response in the documentation](https://auth0.com/signals/docs/#email). The global score is ```-3```. That’s a bad score. Let’s see how the scoring formula works in detail.

## The scoring formula explained

The global score or confidence score is the sum after analyzing different parameters of the Email address. These are the possible values:

- **0:** Auth0 Signals is neutral about the Email address given. It means the service cannot find the Email address in any given individual service and cannot classify the Email as risky.
- **-1:** Auth0 Signals has detected the Email address in one of the checks.
- **lower than -1:** Auth0 Signals has detected the Email address in two or more checks. The lower the score, the riskier the Email.

The possible values range between -3 and 0, and there are no positive values because the algorithm does not calculate confidence levels, but rather levels of DISTRUST.

The email verification process analyzes different elements of an email address assigning a neutral or negative score for each part:

- **Address:** If any of these checks fail, the score of this test is -1.
  - **Address Syntax:** This check removes improperly formatted email addresses. It must adhere to [IETF standards](https://tools.ietf.org/html/rfc2822).
  - **Role-Based Account:** Email sent to role-based such as postmaster@, info@, sales@, admin@, etc. can negatively impact the deliverability, and even some ISPs will block them. This process detects and flags such addresses.
- **Domain:** test for the MX domains, and NS domains. If any of these checks fail, the score of this test is -1.
  - **Domain banned:** The process searches the domain in different deny lists. To be a clean domain, it must not appear in any of them.
  - **MX domain banned:** It searches the MX domains in different deny lists too. Clean MX domains must not appear in any of them.
  - **NS domain banned:** It searches the NS domains in different deny lists too. Spammers use very well-known suspicious Nameservers, and we also can block them.
- **Free Email Service:** detects emails hosted by Free Email Services like (Google, Yahoo, Hotmail/Microsoft, etc.). Since this is a very aggressive option, the algorithm does not compute the result as negative, but it flags the email to help users to make a decision.
- **Disposable Email Address:** Throwaway/disposable email addresses, or “junk collector” email addresses" are detected and processed appropriately. It is a widespread threat indicator of bad actors using them to bypass signup forms or login forms that require a valid email address. The score for this test is -1.
- **Banned Email Address:** If the Email address belongs to some of our Email Abuse deny lists, then the score for this test is -1.
- **SMTP Verification:** Performs deep-level extended SMTP verifications on the email address. The process pings the addresses for mailbox existence without sending an actual email to the inbox. It will also check the validity of the MX records and will test if the server implements a catch-all policy. The score for this test is -1 for any of them.
- **Lookup IP in OSINT deny lists:** The algorithms check the email addresses and IP addresses against known DNSBLs and RBL to trap spam networks. The score for this test is -1 for any of them.

## Using the Email Verification API in your application

It’s perfectly fine to use the API in your own services. If you are a developer, here goes some hints to get the most of the Email verification service:

- You can verify 4,000 emails in a 24-hour range. Use your quota wisely.
- The global score or confidence score should be considered an important signal. Still, we strongly recommend reviewing the different individual scores as you process production traffic to better understand the email address's reputation for your use case. Our general-purpose scoring formula can be too generic for some use cases.   
- You can ignore the global score and focus on individual tests. For example: if you want to detect emails from Free Email providers, you can check the ```freemail``` object in the JSON and ignore the rest of the response.
- Have a look at the [Querystring parameters](https://auth0.com/signals/docs/#check-if-an-email-scores-a-negative-or-neutral-score). This can help you adjust the results to your specific needs. 
- Auth0 Signals is free for all and offered 'as is' with no SLA. This means you should make your code resilient in case the API stops responding.
- For production-grade usage use the Auth0 service that includes Signals built-in. 

## The Email Verification tools: Slack Bot
The [Signals Slack Bot](https://auth0.com/signals/ip#signalsbot-slack-landing) is a new tool built on top of the Signals API for Cybersecurity Professionals, SecOps, analysts, and forensics teams willing to use the bot to get the most of the API without having to write a single line of code. The tool uses the Email Verification and IP Reputation APIs combined with some interactive features to drill down on the data. The installation is very straightforward following the [instructions on our community site](https://community.auth0.com/t/auth0-signals-slack-bot/45216).

![The installation page of the SignalsBot App](https://images.ctfassets.net/23aumh6u8s0i/1MhWa1qfDbbAaxaSMG1xcc/b5d1cb6ebfb99b28824293dee6c4ac3f/signals-installation-page)

Once the Slack Bot is installed and configured, any member of the Slack workspace can go to the SignalsBot in the Apps section and click on the Messages tab at the right-hand side of Home and execute the ```email```(lowercase) command with the email to analyze:

![Auth0 Signals Email verification score](https://images.ctfassets.net/23aumh6u8s0i/4jQkOPsEDZy6FopipmFhQj/38d05be24c61028cfcc372cd68875954/signals-email-score)

## Summary

The Email Verification API is a powerful tool to prevent and mitigate sign-up and sign-in abuse at different stages. If the API integrates with the existing authentication workflow it can help to detect potential low-quality users. When the API or the tools are in the hands of Security professionals it can help SecOps teams perform threat intelligence duties more effectively. Be sure to [check out the documentation](https://auth0.com/signals/docs) for more details.

## Join the community!

[Check out the Auth0 Signals community](https://community.auth0.com/c/auth0-signals/78). Go there to interact with other security professionals, get help on incident response actions, or learn more about digital abuse.


Introducing Auth0 Signals Email Verification API

ec1016a9a63da65998b75f35b6ceb3bb

Javascript junkie, technology enthusiast, tinkerer. Currently Technical Evangelist at Auth0 (https://auth0.com ). I like to learn new things and share that knowledge at conferences.

Technical Evangelist

Joel Lord

Learn how to ensure that only real users are registering to your applications using Kickbox and Auth0 Hooks.



When building an application, it is critical to ensure that the users who are signing up for services or products are real users. By using Auth0, email verification services are provided out of the box; however, wouldn't it be better if verification emails didn't have to be sent at all? By using a combination of [Kickbox](https://kickbox.com/) and [Auth0 Hooks](https://auth0.com/docs/hooks), user email addresses can be validated without sending any emails.

## How does Kickbox work?

Kickbox is an [email technology company](https://kickbox.com/about) with products that help verify email addresses and prevent fake sign-ups applications.

To create a free account, we can visit the [Kickbox sign-up page](https://app.kickbox.com/signup).

<include src="TweetQuote" quoteText="Kickbox ensures we only send email to real users and helps us separate the low-quality addresses from high-value contacts."/>

## Preparing an Auth0 Tenant to Integrate with Kickbox

To demonstrate the integration of Kickbox with Auth0, we are going to use an existing [Auth0 Tenant](https://auth0.com/docs/getting-started/the-basics#account-and-tenants).

> If you haven't already done so, <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free Auth0 account here</a>.

Since we don’t want an email verification to be sent any more, we need to deactivate that option in the tenant. On the left sidebar of the Auth0 Dashboard, let's click on **Emails** first and then on **Templates** to get to the [Email Templates section](https://manage.auth0.com/#/emails). In this section, the **Verification Email** template should be selected by default. Find the **Status** toggle and turn it off.

![Auth0 Email Templates](https://images.ctfassets.net/23aumh6u8s0i/UitVKwTRyrujA8IOXGyfE/54bbbcefe7f54f7fa1dcfab90920d63b/auth0-email-templates)

We are now ready to add an Auth0 hook and integrate Kickbox.

## Kickbox Sendex™ Email Quality

As stated in the Kickbox documentation, Kickbox provides us with a [Sendex value](https://docs.kickbox.com/docs/the-sendex) which is an indicator of the quality of an email address. The existence or syntactical correctness of an email address does not indicate its quality. For example, `john.smith@example.com` can generally be seen as a higher quality email address than `sdfsdfsdf@example.com`.

Kickbox uses a number of algorithms, derived from the millions of email transactions it performs each hour, to determine the overall quality of an email address. These are some of the characteristics Kickbox considers when classifying the quality of an email address:

- Is the email address similar to a known, high-quality, valid email address? The Kickbox platform is always evaluating and learning what patterns good email addresses employ. Its evolving data is used to provide insight into the overall quality of a given address.

- Is the email address domain a commercial domain (example: `acme.com`) or a personal domain (`example: yahoo.com`)?

- Does the email address appear to be associated with a role (example: `postmaster@example.com`) instead of a person (example: `bob.smith@example.com`)?

The Sendex value ranges from a `0` (no quality) to `1` (excellent quality). The value of a good Sendex score depends on the specific purpose of the application. For a transactional email the following criteria may be applied:

- 1.00 - 0.55 = Good

- 0.54 - 0.20 = Fair

- 0.19 - 0.00 = Poor

While the Sendex code is useful to verify the quality of an email address, using it in a pre-registration hook could be problematic. In our case, we will want to validate the authenticity of the email, not the quality. To achieve this, Kickbox provides us with other useful information. We will use two of the properties that are provided by Kickbox to validate the email:

- The `result` property will tell us if this email will actually be delivered or if it's from a risky source. In our case, we will validate that this email is not `undeliverable`.

- The `disposable` property will tell us if this email comes from a service that offers disposable email addresses.

Using these two properties with a pre-registration hook, we'll determine if we'll either create the user account or send an error at the moment of the sign-up.

## Building an Auth0 Hook

[Auth0 Hooks](https://auth0.com/docs/hooks) allow us to customize the behavior of Auth0 using [Node.js](https://nodejs.org/en/) code that is executed against extensibility points (which are comparable to webhooks that come with a server). Hooks give us modularity when configuring our Auth0 implementation and extend the functionality of base Auth0 features.

On the left sidebar in the Auth0 Dashboard, let's click on [Hooks](https://manage.auth0.com/#/hooks). In the Hooks page, we will find different places where we can add a hook in the user login or sign-up life cycle. The one we are interested in is the **Pre User Registration** hook. We want to verify a user email before they register into our system.

To create a new hook, let's do the following:

- Click on the **Create New Hook** button.

- Give the hook a name.

- Select "Pre User Registration" from the "Hook" drop-down field.

- Click on the "Create" button.

Our newly created Auth0 hook will be shown under the "Pre User Registration" section with a green dot before its name. To edit it, let's click on the pencil button in the row below it.

![Newly created Auth0 Hook with an active indicator](https://images.ctfassets.net/23aumh6u8s0i/5YViqqBkxsCE9Am5KufZl8/2f6b325ac113e82ec75baf89547b2f47/newly-created-auth0-hook)

We are taken to the [Webtask editor](https://webtask.io/docs/editor) where we can easily edit our hook logic within the Auth0 Dashboard. In here, we will be able to edit the code that gets executed every time a new user registers. We can add new metadata to our users and return this or we can throw an error which will prevent the user registration.

We can remove all the default code that is there to start with an empty hook. The first thing that we will need is the function that will be executed upon a new user registration:

```javascript
module.exports = function(user, context, callback) {};
```

When our code execution is done, it will need to return the `callback` function with either an error or a valid response. So let’s add this:

```javascript
module.exports = function(user, context, callback) {
  const response = {};
  response.user = user;

  callback(null, response);
};
```

In order to connect to the Kickbox service, we will need to do a `GET` request using the Node `request` module. We can add that at the top of our code just before the `module.exports`:

```javascript
const request = require("request");

module.exports = function(user, context, callback) {
  // ...
};
```

The [Kickbox email verification API](https://docs.kickbox.com/v2.0/reference) is fairly simple to use. We simply make a `GET` call to the following endpoint:

```shell
https://api.kickbox.com/v2/verify?email=<email>&apikey=<API_KEY>
```

In the URL above, `<email>` is the address that we want to verify and `<API_KEY>` is our [Kickbox API key](https://docs.kickbox.com/docs/using-the-api).

Let’s build the `GET` request:

```javascript
const request = require("request");

module.exports = function(user, context, callback) {
  const response = {};
  response.user = user;
  const API_KEY = context.webtask.secrets.KICKBOX_API_KEY;
  const email = user.email;
  const url = `https://api.kickbox.com/v2/verify?timeout=6000&email=${email}&apikey=${API_KEY}`;

  request.get({ url }, function(err, resp, body) {
    // Process the response and send back the callback
    callback(null, response);
  });
};
```

Now, we will automatically reject any email address that comes from a disposable email service or email addresses that are known to be undeliverable:

```javascript
const request = require("request");

module.exports = function(user, context, callback) {
  const response = {};
  response.user = user;
  const API_KEY = context.webtask.secrets.KICKBOX_API_KEY;
  const email = user.email;
  const url = `https://api.kickbox.com/v2/verify?timeout=6000&email=${email}&apikey=${API_KEY}`;

  request.get({ url }, function(err, resp, body) {
    body = JSON.parse(body);

    // Add the user_metadata property if not present already
    if (!response.user.user_metadata) response.user.user_metadata = {};

    if (body.result != "undeliverable" && !body.disposable) {
      // Good email
      console.log("This email is valid, run the callback");
      callback(null, response);
    } else {
      console.log("Probably not a valid email address");
      callback(`Access Denied by Kickbox server. (${body.sendex})`);
    }
  });
};
```

In this case, we are looking at the Sendex score only. If the Sendex score is over `0.75`, we assume that the email address is safe and good to go. There are various other checks that we could make to decide if we want to accept the user or not.

Using this code will send back a generic error message to the end-user on the [Auth0 Universal Login page](https://auth0.com/docs/hosted-pages/login) when the user is trying to sign up with an invalid email.

<include src="TweetQuote" quoteText="Auth0 Hooks are a new extensibility mechanism in Auth0 that allows us to customize the behavior of the Auth0 platform using Node.js."/>

## Taking the User Experience One Step Further

This workflow may not create the most user-friendly experience. In order to show a more meaningful message, we could use the [Auth0 Hosted Pages editor](https://auth0.com/docs/hosted-pages#customize-your-hosted-page). Now that we have access to the Kickbox email data, we could still let our users login but we could perform email verification if we are feeling unsure. There are many other options that we can add to this workflow from here on. There is no limit at what we can do using the Auth0 hooks! I encourage everyone to give them a try.

<include src="asides/AboutAuth0" />


"email-verification"