I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Staff Developer Advocate

Juan Cruz Martinez

Learn how to leverage Auth0 Actions to create custom MFA (Multi-Factor Authentication) workflows, enforce enrollment of users based on specific conditions, and validate user authentication.

Multi-factor authentication (MFA) is an essential security measure that helps to protect your organization's data and assets. By requiring users to provide an additional authentication factor, such as a security token or fingerprint, in addition to their username and password, MFA can significantly reduce the risk of unauthorized access.

However, implementing MFA can sometimes create friction in the user experience, potentially leading to frustration and reduced productivity. Additionally, not all users or scenarios may require the same level of security, making a one-size-fits-all MFA approach impractical.

Auth0 Actions is a powerful feature that allows you to customize and extend the functionality of Auth0. With Actions, you can create custom workflows that trigger in response to specific events, such as user login or registration. This enables you to tailor your MFA implementation to meet your organization's specific needs.

For example, you can use Actions to:

- **Enforce MFA based on user roles or permissions**: You can require certain users, such as administrators or those with access to sensitive data, to use MFA while allowing others to bypass it.
- **Implement risk-based authentication**: You can use Actions to assess the risk level of a login attempt based on factors such as the user's location, device, and IP address. If the risk is high, you can then require the user to provide an additional factor of authentication.

## Prepare your Tenant

Before diving into customizing your Multi-Factor Authentication (MFA) flows, let's make sure we have the essentials in place. This quick guide will walk you through the initial setup steps:

- **Activate MFA**: Head over to your Auth0 Dashboard (<a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Get a free account</a> if you don't already have one) and navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa). Here, you'll be able to activate MFA for your tenant.

- **Choose Your Factors**: [MFA comes in various forms](https://auth0.com/blog/not-all-mfa-is-created-equal/). Decide which factors suit your security needs and enable them on the same Multi-factor Auth page. You might choose options like push notifications, SMS codes, or even biometrics.
 ![Auth0 Dashboard > Security > Multi-factor Auth](https://images.ctfassets.net/23aumh6u8s0i/5NSKKAcGSjkj40ZkTmUlDD/3165f217e14e7a85b9f0304695fdf9d5/MFA_Auth.png)

- **Enable Customization**: To personalize your MFA flows, toggle on the "Customize MFA Factors using Actions" setting. This is like unlocking a secret level – it opens the door to fully customized experiences for your users.
 ![Auth0 Dashboard > Security > Multi-factor Auth > Additional Settings](https://images.ctfassets.net/cdy7uua7fh8z/2hv0ELTkkka3t230SXfxw/46def5395652b2451cfc9e0ad01a371a/MFA_actions.png)

> Actions with `enrollWith` or `enrollWithAny` commands override any existing policies or rules that enable or disable MFA in a tenant.

## Understand the APIs

Once you've enabled Multi-Factor Authentication (MFA) in your Auth0 tenant, you can go beyond the basic settings and create truly customized enrollment flows using Auth0 Actions. Actions are snippets of code that run at specific points in the user's authentication journey, giving you granular control over your authentication workflow and, in particular, how MFA is presented.

To customize your MFA experiences, Auth0 Actions provides a set of APIs designed for enrollment and requiring authentication challenges. Here's a breakdown of the four key APIs you can use: 

### `enrollWith(factor, options)`

Initiates MFA enrollment for a specific factor (e.g., `otp`, `push-notification`, `webauthn-roaming`, etc. Visit the docs to learn about [all supported values](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object#:~:text=api.authentication.enrollWith(factor%2C%20options)).

Example:

```javascript
api.authentication.enrollWith({type: 'otp'})
```

### `enrollWithAny(factors)`

Similar to `enrollWith` but prompts the user to select an MFA factor to enroll in from the supplied list.

Example:

```javascript
api.authentication.enrollWithAny([{type: 'otp'}, {type: 'webauthn-roaming'}])
```

### `challengeWith(factor, options)`

Challenge the user with one or more specified multifactor authentication factors. This method presents the default challenge first, then allows the user to select a different option if additional factors have been supplied. If the user has not enrolled in any of the factors supplied (including both the default and any additional factors), the command fails.

Example:

```javascript
api.authentication.challengeWith({type: 'otp'})
```

### `challengeWithAny(factors)`

Trigger a MFA challenge and allow the user to select their preferred factor from the supplied list.

Example:

```javascript
api.authentication.challengeWithAny([{type: 'otp'}, {type: 'webauthn-roaming'}])
```

## Create a New Auth0 Action

To begin, let's create a new [Auth0 Action](https://auth0.com/docs/customize/actions/actions-overview). Actions are serverless functions that run in a secure Auth0 environment.

To create an Action, log into your [Auth0 Dashboard](https://manage.auth0.com/#/actions/flows), select Actions from the left sidebar menu, then select Flows. This page shows the different flows you can customize. For our use case, we’ll choose the “Login” flow.

![The “Actions” page of the Auth0 dashboard.](https://images.ctfassets.net/23aumh6u8s0i/3Es0FEV0EEyNeKgN6LXEeM/67763781d697663da79113ba381e8610/actions_flows.png)

This will take you to the “Login” flow page, where you can install, create, and add Actions to the flow.

![The “Login” flow page of the Auth0 dashboard.](https://images.ctfassets.net/23aumh6u8s0i/5dveq8h22H0Nje8Rub6sa9/7071335d4db1571af98440e527f1b999/actions_login_flow.png)

The screen has two main sections: the diagram in the center of the page shows the login flow and the Actions panel.

On the diagram, we can see the default login flow, which contains two states.

- **Start:** The user completed the login form and is ready to log in.
- **Complete:** The system issues the user’s credentials (an ID token and, if required, an access token).

You can drag and drop Actions in between these states to add custom logic to the login flow or deny the login request before the tokens are issued.

On the right panel, we have the Actions panel with two tabs.

- **Installed**: Pre-installed Actions from the [Auth0 Actions Marketplace](https://marketplace.auth0.com/features/actions)
- **Custom:** Actions created for this tenant

To create an Action, click the plus icon on the Actions panel and select "Build from scratch".

![Create a custom Action using the Actions panel](https://images.ctfassets.net/23aumh6u8s0i/3TABItaKOdq9dpsUIdQIpx/47d5010f5642123942ba3b7afd710300/actions_login_flow_create_menu.png)

After that, a modal window will appear to enter the information for our Action: you’ll have to provide a name, and you can leave the trigger and runtime as the default values. For my Action, I’ll name it “Require webauthn MFA for admins”.

![Enter the Action name and click create](https://images.ctfassets.net/23aumh6u8s0i/H6zvDcXGyg2a773gW790H/07ce6e74ee07f115d0e58d6e3863642f/actions_login_flow_create_dialog.png)

After clicking on "Create", you’ll be taken to the Action’s code editor, where you can write the code for your Action, install packages, test it, and more:

![Auth0 Actions code editor page](https://images.ctfassets.net/23aumh6u8s0i/6OzG8Oe3XU8lFnzLIr5Ver/4644c79782edaa0d279d4cf2112ae32c/actions_editor.png)

An Action can make use of two JavaScript functions to alter the Login flow:

- `onExecutePostLogin`: defines what should happen immediately after the user provides login credentials that Auth0 verified. This method receives two parameters, `event` and `api`.
 - `event`: contains details about the login request, such as the user and the context.
 - `api`: contains methods to manipulate the login’s behavior.
- `onContinuePostLogin`: defines what should happen when control returns to the Login Action after a redirect to another web page. It’s used only when the user returns after being redirected, which is why it’s commented out by default.

For this tutorial, we’ll focus on the `onExecutePostLogin` method.

## Writing the Actions Code

Next, we'll write the Action's code that will require users under the Admin's group to use `webauthn` as an additional authentication step. If the user isn't already enrolled with `webauthn`, the first time they login they will be prompted to do so.

The action will make use of the APIs `challengeWith` and `enrollWith`, in addition to using the user's property `enrolledFactors` to determine if the user has an MFA factor enrolled already.

Here's the actual code:

```javascript
exports.onExecutePostLogin = async (event, api) => {
 // Check if the user is an admin, enforce webauthn
 if (event.authorization?.roles?.includes('Admin')) {
 // Check if the user is already enrolled with webauthn
 if (event.user.enrolledFactors && event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
 api.authentication.challengeWith({type: 'webauthn-roaming'})
 } else {
 api.authentication.enrollWith({type: 'webauthn-roaming'})
 }
 }
};
```

## Attach an Auth0 Action to the Login Flow

After coding and testing your Actions, it’s time to deploy and use them as part of the login flow. Once you are ok with your testing results, you can hit the `Deploy` button on the top right corner of the screen. This will take the existing code and settings and generate a function snapshot you can use in your login flow.

If you ever need to change the code on the function, all changes will automatically be saved as a new draft, and if you want the changes to become effective, you’ll have to deploy your latest version once again.

Once your code is deployed, it doesn’t mean it is actively used as part of your login flow. To check for that, please refer back to the [login flow screen](https://manage.auth0.com/#/actions/flows/login/), where the login diagram is shown. If you don’t see your Action as part of the diagram, it means that, even if your Action is deployed, it has not yet been activated. To activate the Action as part of the flow, click on the “Custom” tab on the Actions panel, locate your Action by name, and simply drag and drop the box over the login diagram between the "Start" and "Complete" steps. After that, you can apply changes using the “Apply” button on the top right corner of the screen.

![Apply an Auth0 Action to the Login Flow](https://images.ctfassets.net/23aumh6u8s0i/5IKiEeHy8WharqTOjJnSLh/eb5025dfd22de94c2446ccc22f1b524d/actions_attach_to_flow.gif)

## Test Your New Authentication Flow

Now, you can try your new Action by logging into your Auth0-powered application using both admin and non-admin accounts. When you log using any method (e.g. username/password, or social login) with a non-admin user, you'll get direct access to your application or continue with the authentication flow as you have it specified for your tenant.

When you log in using an admin user (a member of the group "Admin", as we defined it on the Action), you'll be prompted to either register or validate your account with webauthn. The screen may look something like this:

![Auth0 MFA Validation Step](https://images.ctfassets.net/23aumh6u8s0i/7duWHgEkhhz2e7rLgLJV1X/d174ce044c7a8011f660cd83be1cc815/mfa_validate.png)

## Conclusion

Auth0 Actions provides a versatile and powerful toolkit to revolutionize your organization's MFA implementation. By harnessing the flexibility of Actions, you can create personalized, risk-based, and context-aware MFA workflows that enhance security without compromising user experience.

The ability to tailor MFA requirements based on user roles, risk assessments, and specific applications empowers you to implement a layered security approach. This means that you can enforce stricter MFA for high-risk scenarios, such as administrative access or sensitive data handling while offering a streamlined experience for regular users.

As you explore the possibilities of Auth0 Actions, remember that Customization is key. By experimenting with different workflows and conditions, you can fine-tune your MFA implementation to perfectly align with your organization's unique security requirements and user expectations.

Thanks for reading!

Using Actions to Customize Your MFA Factors

william_johnson

Will Johnson is a Developer Advocate at Auth0. He loves teaching topics in a digestible way to empower more developers. He writes blog posts, records screencasts, and writes eBooks to help developers. He's also an instructor on <a target='_blank' rel='noopener noreferrer' href='https://egghead.io'>egghead.io</a>.

Developer Advocate

Will Johnson

Quickly integrate Twilio for SMS-based multi-factor authentication

Your users' most trustworthy interaction with your business is when they type each letter on their keyboard to enter their username and password into your login box. After they hit enter and send this confidential information through the internet tubes, they trust that your application has done everything possible to keep their data safe from bad actors.

Even with proper protocols, expert attackers still find shortcuts and backdoors to access users' credentials and confidential information. The good news is you can add another layer of protection for your users by adding Multi-factor Authentication (MFA) to your Application. MFA lets you add another factor to verify so users can prove who they say they are. There are several types of MFA methods. Some of them are SMS-based, One-time passwords (OTP), Authenticator apps, and Biometrics, to name a few. 

> To learn more about MFA methods, [check out this MFA Guide](https://auth0.com/blog/multifactor-authentication-mfa/).

Today, you will add SMS-based MFA with Auth0 using Twilio as the SMS provider. Twilio is a popular customer engagement platform that you can easily integrate with Auth0.

If you prefer, you can also watch this video on the same topic:

<AmpContent>
<amp-youtube
 data-videoid="lF7stm2nUHQ"
 layout="responsive"
 width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
 class='embed-container'
 style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
 <iframe
 style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
 src='https://www.youtube.com/embed/lF7stm2nUHQ'
 frameborder='0' allowfullscreen>
 </iframe>
</div>
</NonAmpContent>

## What Will You Need?

* An Auth0 Account. If you don't have one, <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">you can register for free</a>
* A Twilio Account
* A mobile phone

## Set Up and Configure Auth0 React Demo Application

> If you already have a Single Page Application registered in your Auth0 dashboard, you can skip to [Create Twilio Account and Get Credentials](#Create-Twilio-Account-and-Get-Credentials).

### Clone the demo application

Start by cloning the [Auth0 React SDK Sample Application from GitHub](https://github.com/auth0-samples/auth0-react-samples/tree/master/Sample-01). This is a sample React app set up and connected with Auth0. Once you have the Application installed on your machine `cd` into `auth0-react-samples` then again into `Sample-01`, use npm to install the project's dependencies.

```bash
npm install
```

Once the dependencies are finished installing, run `npm run dev` in your terminal and in your browser visit `http://localhost:3000`, if it doesn't automatically start. Now you'll see the React sample project with a login button in the upper right corner of the screen.

![Auth0 Sample Project Login Screen](https://images.ctfassets.net/23aumh6u8s0i/4B7KxXicKfMF4SS7an6RxB/9c29ccdcc08572b11dd9691923c328c5/React_SDK_Local.png)

In the project's `src` folder, you'll find the `auth_config.json.example` file. There's a JSON object with placeholder values inside this file. Copy it, then create a new file in the same folder named `auth_config.json`. With this file created, you need to replace the placeholder values with your own credentials from the Auth0 dashboard. 

![Auth0 Config File](https://images.ctfassets.net/23aumh6u8s0i/6cM6y7s5CqxfC4DpMbDI8r/0b22c0cdc5ed736bc0631b52e2028080/Screen_Shot_2021-12-02_at_7.44.45_PM.png)

## Get Credentials from Auth0 Dashboard

Now go to your Auth0 Dashboard; click _Applications_, then click _Applications_ again when the options dropdown on the right-side panel. Click _Create Application_ if you don't already have an application in your Auth0 account.

![Auth0 Dashboard Application Page](https://images.ctfassets.net/23aumh6u8s0i/3IP95iBgYyz7XJ62rwqbyW/f6862e32b8169566bbd7343ff892966c/Screen_Shot_2021-12-02_at_8.19.52_PM.png)

On the Create Application screen, you'll give your Application a name. You can use "Twilio MFA Test." 

Next, you'll choose the application type; select _Single Page Application_ since this is a React application. Then click _Create_.

![Auth) Dashboard Create Application Page](https://images.ctfassets.net/23aumh6u8s0i/5ZxkkuVUS3nmhqWvQuu8aZ/67bef7be2b4cca5460f8311c2be69655/Screen_Shot_2021-12-02_at_8.45.53_PM.png)

Since you already have the sample application on your machine, skip Quick Start and click _Settings_. This is where you will find the Domain and Client ID, that you need to replace the placeholder values in the `auth_config.json` file. You can copy the values from the dashboard into your code editor.

![Application Settings Page](https://images.ctfassets.net/23aumh6u8s0i/nQMYVh3ZDtMSYUCog7e5r/e8b8b471b7097d36918547037c78ce5f/Screen_Shot_2021-12-02_at_9.11.39_PM.png)

Next, scroll down to the Application URIs section to fill in Allowed Callback URLs, Allowed Logout URL, and Allowed Web Origins. This example is running locally, so enter `http://localhost:3000` into each field. When you're finished, scroll to the bottom of the page and click _Save Changes_.

![Application URIs](https://images.ctfassets.net/23aumh6u8s0i/6kXeY9LVo5sincLcxSdrk1/e25a7bfd89bcda641f6c6625ad143aa5/Screen_Shot_2021-12-03_at_8.37.26_AM.png)

You can now run the Application locally again and click Login; enter a username and password, and the user will be successfully authenticated with Auth0. As you may have noticed the username and the password are the only factor being used to authenticate users. Make your application more secure by adding another factor for the user to verify. Twilio can add SMS-based authentication. You'll set that up next.

## Create Twilio Account and Get Credentials

If you don't have a Twilio account already, you can create one [here](https://www.twilio.com/try-twilio). Once you have created an account and logged in, you'll see the Twilio console. Here you'll see your Account SID and Auth Token, which you'll use later. The next step for a new Twilio account is getting a Twilio phone number. This will be the number that will send a one-time passcode to your user to verify and complete their authentication after they've logged in with their username and password.

### Get a Twilio trial phone number

In the Twilio Console, click _Get a trial phone number_. You'll automatically get assigned a number click Choose this Number. This number will now show on the Project Info section under Phone Number.

### Configure Auth0 to use Twilio for MFA

Back at your Auth0 dashboard, look at the ride side menu, click Security, then Multi-factor Auth. On this page, you'll be shown all the factor options that you can use with Auth0. For this Application, click on _Phone Message_.

The first thing you need to do on the Phone Message page is click the toggle button on the upper left side corner to enable Phone Message MFA. You'll see a pop-in notification confirming it has been enabled.

Next, you'll need to Choose a delivery provider; you'll see that Twilio is one of the listed options making it easy to connect Twilio to your Auth0 account.
For _Choose a delivery method_, you have SMS, SMS, and Voice, or Voice to choose from. For simplicity, select SMS.

![Phone Message Settings Page](https://images.ctfassets.net/23aumh6u8s0i/1Rhy8cNvQn76y81MQ9b81j/59ae57cdd0300d658456ef03b5ff0af9/Screen_Shot_2021-12-03_at_11.40.16_AM.png)

When you select Twilio as the delivery provider, you will have some new fields appear to enter the Twilio SID, Twilio AuthToken, and the From phone number. You'll see all of those values in the Twilio console.

![Twilio Console](https://images.ctfassets.net/23aumh6u8s0i/4SO3LiFDt5wt4MdOZFuFR1/446d53076c18666ac2d705de50b3f7f4/Screen_Shot_2021-12-03_at_10.59.05_PM.png)

Copy each value to the matching field in the Auth0 Dashboard. The two template fields can customize the message the user gets sent. You'll leave these as they are in this example. Now click _Save_.

![Phone Message Twilio Settings](https://images.ctfassets.net/23aumh6u8s0i/12Xd2Mg7Twq6Nk7eV5Ra1s/cfd809f4a460dca1c5c3ee4c82424971/Screen_Shot_2021-12-03_at_11.26.55_PM.png)

Now you have everything configured to use Twilio as an SMS MFA provider, but there is still one more step left to actually make everything work!

## Enable MFA in the Auth0 Dashboard

Back on the Multi-factor Authentication page, there are two sections Factors, which we just completed, and Define Policies. Define Policies will tell Auth0 when you want to prompt the user to use MFA. In the Require Multi-factor Auth section, the default is Never, which is the exact opposite of what you wish to do after doing all that work of configuring MFA.

The second option is an add-on called Adaptive MFA. This takes a look at the user's environment and determines if it's risky and requires another authentication factor. For this example, you'll choose _Always_, then click _Save_.

![Define Policies Section](https://images.ctfassets.net/23aumh6u8s0i/62TwidbXDP7luY9XQHeECD/25425b0cc1c9638401c40922cf61b371/Screen_Shot_2021-12-03_at_11.41.27_PM_1.png)

You'll get a prompt asking if you want to continue and let you know all new and existing users are now required to enroll in MFA click _Continue_. That will update your MFA policy, and now, when a user registers or logins, they will be met with a prompt to add their phone number to enroll in MFA.

Now that everything MFA is enabled in your Application, you want to test it out to ensure everything goes smoothly.

## Test MFA on Login

With your sample application running, click _Login_ and enter your email and password. Next, you'll be prompted to add a phone number to secure the account. This is what your users will see the next time they log in after you enable MFA.

You can select the code for your country on the first line, then type in your phone number and click _Continue_. You'll then have an SMS message come to your phone with a verification code. Enter that code into the input box on your application. 

Now you're successfully logged in, and your users have another layer of protection from their data being compromised. All thanks to you, pat yourself on the back!

## Summary 

You just added Multi-factor authentication to your application using Twilio as the provider. You entered your Auth0 credentials to the `auth_config.json` in the project files of your application. Then, you enabled Phone Message MFA in the Auth0 Dashboard and added your Twilio credentials.

Enable Multi-factor Authentication with Auth0 and Twilio

arthur-bellore

I’m a tech content creator. I enjoy breaking up seemingly complicated topics into easy-to-understand pieces for people to read. When I’m not in front of a computer, you’ll usually find me reading books.

Cybersec Writer

Arthur Bellore

Why hardware-based Two-Factor Authentication makes the user much more secure over other multi-factor alternatives

When I wrote about how software 2FA is a step-up from SMS 2FA, I also mentioned how there’s one attack vector that software 2FA is still vulnerable to phishing. It’s the **user** who must verify they are entering the passcode into the legitimate website, and bad actors exploit that.

Phishing is a hard problem to solve because the bad actor exploits human behavior that has been ingrained in all of us for the last couple hundred thousand years and will probably continue to be for a long time in the future.

Everybody is prone to fall for phishing campaigns, even security-conscious people, because these attacks are never head-on, explicit attacks, but sneaky ones and when you aren’t expecting them.

And if we look at types of attacks over the years, there is a clear trend: the number of websites containing malware has been declining, while the number of phishing websites skyrocketed in the last few years. You can see that in the chart below:

![01_bleeping_computer](https://images.ctfassets.net/23aumh6u8s0i/5Z7X9Z3Dm07lEvbjtubPO1/6c57ba7fc4b4458c6a995463e6a39ee6/01_bleeping_computer.jpg)
Source: <a href="https://www.bleepingcomputer.com/news/security/google-chrome-uses-safe-browsing-to-improve-phishing-protection/">Bleeping Computer</a> via <a href="https://transparencyreport.google.com/safe-browsing/overview">Google Transparency Report</a> (archive)


Attackers are becoming more **proactive** and trying to **force errors**. With more devices connected to the Internet, these attacks become more profitable (we’ve seen a [surge during the last few years](https://www.f5.com/company/news/features/phishing-attacks-soar-220--during-covid-19-peak-as-cybercriminal)), and now more companies are starting to pay attention to phishing attacks.

Taking the human element out of security is not an easy task, but that is what Universal 2nd Factor, or U2F, tries to do — it’s an open protocol for second-factor hardware keys that doesn’t rely on the user to make sure he’s on the right website; there is a built-in mechanism on the key itself to verify that.

## How The U2F Protocol Was Created

In 2011, the founders of Stockholm-based Yubico would relocate to Silicon Valley to be in close contact with tech companies to further develop the protocol used by the YubiKey into a universal standard. 

> Note: many hardware tokens, such as the YubiKey 5, support more types of authentications on top of U2F (e.g., TOTP), but references to hardware tokens throughout this article refer specifically to U2F.

In that same year, they started discussions with Google’s internal security team and together identified YubiKey as the best solution to solve the employee phishing problem Google was having at the time.

One year later, in 2012, Google and Yubico signed a partnership to co-create the U2F — an open standard for two-factor authentication based on public-key cryptography that would remove the need for the user to verify that they were, in fact, at the intended website. 

They tested the USB token Yubico had created with Google employees, and one year later, they joined the FIDO Alliance board and brought along with them the technical specifications to the protocol. The protocol continued to be improved over the years, being released publicly for Chrome and Gmail, along with many other products.

In 2019, the World Wide Web Consortium (W3C) announced Web Authentication API (WebAuthn), the new global standard comprising the implementation of FIDO U2F security keys in most modern browsers. By that time, [Google already eliminated phishing attacks by having its 85,000 employees use hardware tokens](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing/). 

## How Hardware 2FA (or U2F) Works

When you think of a real-world key, you probably imagine that the same key you use to _lock_ something is also used to _unlock it_. If you have a chest with all of your passwords stored inside, this setup works because you’re the only one who needs to access it.

But what would happen if you wanted to share a password securely with me (and only me)?

Well, here’s an option. I could get a chest and put it outside my door. Then I could leave the key on a key holder outside, and you would come over, put the password inside the chest, lock it, and put the key back on the key holder. As soon as I get back home, I would take the keys, open the chest, and pick up the password you put in there.

This approach is far less than ideal because we can’t be sure who else used the key to open the chest and read the password. I also can’t be sure that you, or anyone else, didn’t make copies of my key to open my chest.

The solution to this problem is **public-key cryptography**, and it’s the principle used by U2F tokens to authenticate users. In public-key cryptography, instead of using just one key, we use a pair of keys — if you lock the chest with a certain key, only the other key can unlock it.

![02_How_hardware_2fa_works](https://images.ctfassets.net/23aumh6u8s0i/1DZ5lxj8zLE6vu3vluVADj/1f79e96a559d9b0eecdce2603be22efa/02_How_hardware_2fa_works.jpg)

Now I can keep one key — my private key — and put the other one outside for you to use — the public key. And since only my private key can unlock the chest, once you lock it, no one else can use the key I left outside to peek inside the chest.

In cryptography, these keys are called a **key pair** and are mathematically linked. I could create as many public keys from a private key as I wanted, but you can’t recreate my private key from a public key.

Key pairs can be created using software, but in the case of U2F, the private key is **generated using a unique secret that is embedded during the manufacturing process and can never leave your U2F token**, which is what makes it so secure.

The process to start using U2F in an account is simple and happens in two steps: registration and authentication.

## Registration

This step involves four parties:

- the user, 
- the hardware token, 
- the client (e.g., a browser), 
- and the remote server. 

To register a security token, the user needs first to authenticate through another method, e.g., with username and password, or while he’s creating the account for the first time. After the user signals they want to register a U2F token, the server sends a challenge — a random number — and an AppID to the user’s device.

The AppID is a unique identifier for the app — on a browser, the AppID is the URL, like `auth0.com`. On Android, it’s going to look something like `android:apk-key-hash:<hash-of-apk-signing-cert>` and on iOS, something like `ios:bundle-id:<ios-bundle-id-of-app>`.

Once this information is received, the user will be prompted to press a button on the hardware token to confirm the request. This will prevent remote attacks even if the key is inserted into the user’s device.

![03_registration](https://images.ctfassets.net/23aumh6u8s0i/2mGwrM5SqnQ6Jz8S5EQXCo/d1ae6f4bfae43541bae86596dfa8fe43/03_registration.jpg)
Source: <a href="https://www.yubico.com">Yubico</a>


The hardware token will generate a [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) and hash it together with the AppID and the secret key on the token using HMAC-SHA256 to create a private key. From this private key, a public key is derived, along with a checksum. Check the diagram below:

The nonce and public key are sent back to the server to be stored for later when the user comes back to authenticate.

## Authentication

The user will normally authenticate with their login and password. The server will remember that this user has a security token registered and will generate a new challenge to send back along with the AppID and nonce created on the registration phase.

The browser will once again ask the user to press a button on their physical token, and the token will use the received information to re-create the same key pair is created during the registration phase.

If the information was sent from a legitimate server, it should result in the same public key since the secret inside the device didn’t change. The device will then encrypt the challenge sent by the server with the private key and send it back to the server.

However, because the domain is hashed together with the device secret, if you’re on a phishing website, the token will generate a different key, and the checksum will fail.

The challenge can only be decrypted by the public key created with that same private key, which the server already should have stored from the previous phase. The server will try to decrypt it using the public key it already has, and if the challenge matches with the one the server sent, the user is authenticated.

## What Makes Hardware 2FA Better than Software 2FA?

Hardware 2FA brings several security benefits over software 2FA. The most obvious one is phishing resistance. By using the website domain in the key generation process, the token assumes what normally would be a user responsibility — that of verifying that the website they are logging in to is legitimate.

It’s also more leak-resistant than software 2FA. We’ve seen that software 2FA works on the basis of a shared secret between user and server ahead of time, from which the passcode is derived. But if the shared secret is leaked from the server, anyone can use it to generate the correct passcodes.

If the user has secured their account with U2F, however, and the public keys and key handle on the server get leaked, the attacker still won’t be able to take over the account because he’d still need the private key to sign the payload and authenticate themselves.

Not only that, a U2F token can’t be exploited remotely by automated bots. Most keys require a physical touch on the device to sign the payload, so they aren’t vulnerable to the [brute-force attacks that can occur in improperly implemented TOTP systems](https://www.miknet.net/security/the-trouble-with-totp/) (e.g., not taking into consideration user behavior, geolocation, number of bad attempts before locking down the account for a determined amount of time).

In a scenario where the attacker has acquired a list of compromised passwords, brute-forcing any individual account by going over all possible 1,000,000 passcode possibilities is increasingly trivial with a big enough list:

![04_what_makes_hardware_2fa](https://images.ctfassets.net/23aumh6u8s0i/6ovPCcvrlpLnrKCviq4Ukw/8ed6038cb3408a799f5fa6cb54f1ac04/04_what_makes_hardware_2fa.jpg)
Source: <a href="https://www.miknet.net/security/the-trouble-with-totp/">The trouble with TOTP</a>.
 
An automated attack like that can’t happen on U2F-enabled accounts. Also, all cryptographic operations happen inside the token. By the time the private key leaves the token, it already has been hashed using SHA-256, so even if the user doesn’t know that the client is compromised, it’s still safe to use the token.

In terms of usability, in an [internal study at Google](https://research.google/pubs/pub45409/), they found that U2F allowed employees to authenticate as much as four times as fast as using an authenticator app.

And as with software 2FA, users can assign multiple tokens as backups in case they lose one — the only problem here is that each key additional key will cost money (presuming the user already had multiple devices in where to store the TOTP seeds), and considering the already low 2FA adoption rates, it’s something to be considered carefully.

In some cases, though, there might be a decrease in costs by mandating hardware tokens.

It’s what the study above found: initially, Google tested the YubiKey internally with 50,000 employees, and they found that not only internal accounts protected with YubiKey were much more likely to be secure, they also saw a 92% reduction in support incidents.

In the end, this allowed Google to _save money_ in support hours and costs related to compromised accounts by issuing multiple backups per employee.

In fact, requiring backups may also be one of the downsides of hardware 2FA: having no backups can be _extremely problematic_ if you lose your token. You’ll be at the mercy of the admins to let you in again — and in some cases, like in that of password managers where your vault is end-to-end encrypted, not even they can help you recover your account.

## Driving Up The Adoption Of U2F

The biggest problem with U2F right now is adoption — it’s low even among users who use any 2FA (according to [this 2018 report](https://www.theregister.com/2018/01/17/no_one_uses_two_factor_authentication), less than 10% of Gmail users enabled any kind of 2FA), and 2FA adoption overall is already low. In this case, it’s a two-sided adoption problem:

1. Users need to buy a hardware token to use U2F.
2. Applications need to implement the protocol to allow users to use them in the first place.

And as you can see [here](https://2fa.directory), U2F is not nearly as well-supported as SMS and software 2FA. Surprisingly, even applications you would expect to support U2F still don’t, such as some of the password managers.

If you want to incentivize your users to use U2F, Auth0 now supports WebAuthn with FIDO (U2F) security keys, so you can easily offer it as an option for your users. For more information, visit [Auth0 Docs](https://auth0.com/docs/mfa/configure-webauthn-security-keys-for-mfa).

The Working Principles of 2FA (2-Factor Authentication) Hardware

andres

I’ve been at Auth0 since 2017. I’m currently working as a Product Manager for the Auth0 FGA and OpenFGA products. Previously, I worked in the teams that owned the Login and MFA flows. 
I spent my entire 20+ year career building tools for developers, wearing different hats. When I'm not doing that, I enjoy spending time with my family, singing in a choir, cooking, or trying new kinds of local cheese.

Product Manager

Andrés Aguiar

Announcing support for WebAuthn with FIDO Security Keys for Multi-Factor Authentication in Auth0

Companies of all sizes are under attack, targeted by numerous phishing attacks that are coming at an ever-increasing rate. Even if the tech industry continues to improve how organizations identify and defend against those attacks, the problem is bigger than ever. According to ProofPoint's [2020 State of The Phish Annual Report](https://www.proofpoint.com/sites/default/files/gtd-pfpt-uk-tr-state-of-the-phish-2020-a4_final.pdf), 88% of organizations faced a targeted phishing attack in 2019, and 65% of US organizations experienced a **successful** phishing attack.

There are options for decreasing the chances of successful phishing attacks targeting your company. Things like employee training and security policies, such as using password managers and enforcing multi-factor authentication (MFA), are all steps in the right direction. 

However, if you want to neutralize the threat completely, you need to enable authentication methods that cannot be phished. That's [what Google did](https://krebsonsecurity.com/2018/07/google-security-keys-neutralized-employee-phishing) in 2017 to neutralize phishing of its employees. Google now requires all employees to use U2F Security Keys to authenticate to corporate websites. 

U2F evolved into the WebAuthn specification, which is now supported by the latest versions of browsers and operating systems. Auth0 is now supporting WebAuthn with FIDO security keys for multi-factor authentication. You can start protecting your users with Auth0 today, using the same technology as Google.

## About WebAuthn

The Web Authentication API (also known as WebAuthn) is a [specification](https://www.w3.org/TR/webauthn/) written by the World Wide Web Consortium (W3C) and The Fast IDentity Online Alliance, known as FIDO, with the participation of Google, Mozilla, Microsoft, Yubico, and others. The API allows servers to register and authenticate users with public-key cryptography instead of a password.

When it comes to security, many people think you have to sacrifice security in the name of user experience, and vice versa. However, the key to maximizing both variables is to reduce the number of times we prompt the user for authentication and to allow the user to authenticate with secure factors that provide low friction. WebAuthn promises to be the holy-grail of authentication factors, as it accomplishes exactly that by combining maximum security with a low-friction user experience.

WebAuthn allows users to authenticate using one of two options:

* **Roaming authenticators** — These are removable and cross-platform devices, like a [Yubikey](https://www.yubico.com/products/) that can be used on multiple devices. To authenticate with a roaming authenticator, you simply connect it to the device (through USB, NFC, or Bluetooth), provide proof of presence (e.g., touching it), and optionally an additional authentication factor like a PIN or fingerprint recognition.

* **Platform authenticators** — This option includes the MacBook's TouchBar, Windows Hello, iOS Touch/FaceId, and Android's fingerprint/face recognition. Integrated into the device being used, these only work on that device.

When doing multi-factor authentication, we want to challenge the user with something they know (like a password), something they have (like a security key), and something they are (e.g., their fingerprint).

Note that a Roaming Authenticator + PIN **combines two factors in one** (you have the key, and you know the pin), and a Platform Authenticator also does (you have the device, you are the person with that fingerprint/face, or you know the passcode).

In recent months the WebAuthn API has been implemented in major browsers and operating systems, enabling support for both options.

<include src="WebAuthnMeCTA" group="A"/>

## The Case for Security Keys

Using a Security Key allows you to authenticate users with the strongest possible authentication factor. This helps you to solve several problems at once by:

* Protecting sensitive data and employee accounts
* Providing secure access from outside the corporate network
* Allowing your employees to authenticate to shared computers
* Enabling MFA in scenarios where users cannot carry their mobile phone

It also offers several advantages when compared with using a smartphone only authenticator for MFA:

* Protects against phishing and man-in-the-middle attacks
* Strengthens user privacy as it doesn't require a personal device
* Provides one-touch login without having to take your mobile phone to complete an authentication challenge
* Has no battery or signal dependency
* Has no moving parts, so it's practically indestructible
* Allows users to register multiple keys, minimizing business disruption and the chances of account lockout

## WebAuthn With Security Keys for Multi-Factor Authentication

Auth0 with WebAuthn support for Security Keys is available starting today. You can enable the factor in the WebAuthn with Security Keys MFA configuration section of the admin dashboard:

![Multi-Factor Authentication 1](https://images.ctfassets.net/23aumh6u8s0i/5LAUWUPRO5gvYQ9t56rNPa/f9c2d823965b8070c22e6ab3151d2665/01-factors-updated)

After it is enabled, users will go through the enrollment flow below. At some point, their browser will show a native dialog to ask users to engage the security key. In the example below, we show the Android dialog:

![Multi-Factor Authentication 2](https://images.ctfassets.net/23aumh6u8s0i/4l0n2zVBk0Byf8P2MfWvaf/51a1b3ebb7248719a7cc17b32a4765a4/02-welcome)

The next time they login, the flow will look like this:

![Multi-Factor Authentication 3](https://images.ctfassets.net/23aumh6u8s0i/5f9tqz1pR3RgrkFZSOcp2F/41df6128ee37f040c0389dbd7db9dda8/03-waiting-for-your)

## Stay Tuned!

In addition to supporting WebAuthn with roaming authenticators, we are currently working on a unique approach that will greatly improve the usability and adoption of WebAuthn platform authenticators. Check out Vittorio Bertocci's session "[Democratizing WebAuthn for Developers and End Users](https://authenticatecon.com/session/democratizing-webauthn-for-developers-and-end-users/)" from FIDO's Authenticate conference for the scoop!

WebAuthn is an exciting technology, and Auth0 is committed to providing the best possible implementation, maximizing security without sacrificing user experience. Check out our new [WebAuthn](https://auth0.com/docs/mfa/configure-webauthn-security-keys-for-mfa) offering and let us know what you think on our [Feedback page](https://auth0.com/feedback) or in the [Auth0 Community](https://community.auth0.com).

<include src="asides/AboutAuth0" />

FIDO Security Key Support Comes To Auth0

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

Learn what multi-factor authentication is and different methods for implementing MFA.

Before you can learn about multi-factor authentication, you must understand authentication itself. Authentication, simply put, is the process of **verifying that someone is who they say they are**.

When you want to sign in to your account on a website, the website must first make sure you're the owner of that account. How do they do that? They ask you for something that only you should know. Typically, this is the **username and password** that you set up when you created the account. Great! You were the one who set it up, so there's no way anyone else could have your password, right?

It turns out that someone providing the correct username and password to access a resource doesn't necessarily prove that they are who they say they are. User credential breaches have become much more prevalent in recent years, so there's a good chance that some of your username and password combinations have been involved in a breach. This means that relying only on a username and password to identify someone isn't a great practice.

This is where multi-factor authentication comes into play.

## What is Multi-factor Authentication

Multi-factor authentication (MFA) provides a method to verify a user's identity by requiring them to provide **more than one piece of identifying information**.

You have most likely encountered multi-factor authentication on some of your favorite websites already. For example, when you sign in to your banking account, you may get a screen requesting that you enter the code that was emailed to you. Once you enter this code, you're then able to access your bank account. This is an example of MFA in action!

Providing a username and password coupled with a code sent to your email is one form of MFA, but there are several other options you have for implementing MFA. Let's look at some of those now.

## Types of Multi-factor Authentication

The category that you use to identify a user is called an **authentication factor**. In general, these identification methods fall into three authentication factor categories:

**Something you know** &mdash; Something you know, such as a password, PIN, personal information like mother's maiden name, etc.

**Something you have** &mdash; A physical item you have, such as a cell phone or a card.

**Something you are** &mdash; Biometric data, such as fingerprint, retina scan, etc.

To implement multi-factor authentication, you need to cover at least two of these categories.

A common scenario would be requiring a user to sign in with their username and password. This covers the "**something you know**" category. After providing their username and password, they'd receive a text to their cell phone with a short code called a one-time password (OTP). This covers the "**something you have**" category. They'll be required to type this code into the website, and if correct, then they'll be authenticated.

<AmpContent>
![One-time password screen](https://images.ctfassets.net/23aumh6u8s0i/5RoVY86v6SZ5OAVtZzRm6B/1ee99b6f7547ece9c5fc3e7ab2563360/one-time-password)

</AmpContent>

<NonAmpContent>

<img class="img-responsive" src="https://images.ctfassets.net/23aumh6u8s0i/5RoVY86v6SZ5OAVtZzRm6B/1ee99b6f7547ece9c5fc3e7ab2563360/one-time-password" alt="one-time password screen" style="width:50%"/>

</NonAmpContent>

In this scenario, even if an attacker knows the user's password, *it isn't enough*. They'll have to also gain access to the user's phone to provide the one-time password.

### One-time passwords

In the scenario above, the application sent the user a code known as a **one-time password (OTP)**. This is one of the most commonly used forms of multi-factor authentication. Let's take a closer look at what one-time passwords are.

A one-time password, like its name indicates, is a pseudo-randomly generated password that expires after a short time period and is only valid for one login. They are typically paired with a traditional username and password to make the authentication process more secure. Even if a user has a weak or reused password, the one-time password that is sent to them is a way to indirectly strengthen their credentials.

There are a few different ways to send one-time passwords to users.

#### SMS

SMS is one of the most user-friendly ways to send one-time passwords. The user signs in to your application with their username and password, and then they receive a text message to their cell phone with their OTP. They're able to easily copy the code from the text message and send it back to the application.

While this may be simple for the user, and it's better than not having MFA at all, it's still [not the best way](https://auth0.com/blog/dont-pass-on-the-new-nist-password-guidelines/#The-SMS-Controversy) to send or receive one-time passwords.

Believe it or not, delivering an OTP through SMS carries the risk of compromise. Here are some of the ways that an attacker can gain access to your OTP through SMS:

- **Social Engineering** &mdash; An attacker that has breached a user's username and password may also have access to their phone number. Attackers have been known to obtain SMS-delivered one-time passwords by sending a text to the user telling them that they used to have the same phone number as them, and they are locked out of one of their accounts because they forgot to update the phone number listed on the account. They politely ask for the code that was just sent to the user's cell phone, so they can get back into their account. Many people want to help the person on the other end, so they text them the code without thinking much of it.

- **SIM Swap** &mdash; [SIM swapping](https://www.consumer.ftc.gov/blog/2019/10/sim-swap-scams-how-protect-yourself) (also known as simjacking) is when an attacker gains access to your cell phone number. One interesting (and terrifying) way this can happen is by an attacker calling your cell phone provider and convincing them that they lost their phone and need a new SIM card activated. The SIM card that gets activated is one that the attacker owns. If the cell phone provider obliges, then the attacker now has access to any text messages, phone calls, etc. that come through. So, if they already have your username and password, all they have to do is type in the OTP that is texted to your phone number (which they now have access to), and they're in! This [Hacking Challenge at Defcon video](https://www.youtube.com/watch?v=fHhNWAKw0bY) has an excellent demonstration of this in action.

#### Email

Another option for receiving OTPs is through email. While this does provide another step to access your account, which is great, it still has some downfalls:

- Because [password reuse is so prevalent](https://www.zdnet.com/article/44-million-microsoft-users-reused-passwords-in-the-first-three-months-of-2019/), there's a chance that a user's email password is the same as the account that's requesting the OTP. Assuming the attacker already has this password, then the extra step of the OTP is useless.

- One of the requirements for MFA is that the implemented factors come from at least two of the MFA categories: something you know, something you have, and something you are. The username and password fulfill **something you know**, and OTP is meant to fulfill **something you have**. Ideally, something you have would be a physical item, such as your cell phone. Having access to an email account doesn't necessarily mean that the cell phone is in your possession, as you could access your email from any device. 

#### Authenticator apps

Another common way to manage OTPs is with authenticator apps. Once you install the app up on your cell phone, you can set up any accounts that work with the authenticator app to send your one-time passwords to that app. The OTPs will typically regenerate every 30 seconds, so instead of waiting for an email or a text message, you simply open up the app, and you'll always find a valid OTP there.

There are a lot of authenticator app options. Some of the most popular ones are [Duo](https://duo.com/), [Authy](https://authy.com/), and [Google Authenticator](https://support.google.com/accounts/answer/1066447).

An authenticator app is an excellent choice for receiving one-time passwords. Unlike SMS, an attacker can't access your authenticator app simply by having access to your text messages or phone number. Your one-time passwords also can't be stolen if someone gains access to your email account.

There are, however, still downsides to authenticator apps. Some users may find it too much of a hassle to download a new app and set up all of their accounts on it to receive one-time passwords, especially when it's so much easier to just enter their phone number instead.

Another issue is that if you lose your cell phone, accessing those accounts that have MFA enabled can quickly become a nightmare. Most popular authenticator apps now have [safeguards, such as key backups, built-in](https://authy.com/blog/how-the-authy-two-factor-backups-work/). To enable backups, you have to create a strong password that's used to encrypt your OTPs. Then, if you ever lose your phone, you can install the authenticator app on your new phone and type in your password to decrypt your keys.

## Step-up Authentication

You may have noticed a common theme amongst the downsides to some of the OTP options: **user experience**.

One of the biggest obstacles to mass adoption of MFA is the slight hit that user experience takes. Generally, the more steps you require to sign in to your application, the fewer people will want to use it.

To manage the balance between user experience and security, some people find it best not to require MFA on every login, but instead, require it when accessing more sensitive data.

> With [step-up authentication](https://auth0.com/docs/mfa/concepts/step-up-authentication), applications that allow access to different types of resources can require users to authenticate with a stronger authentication mechanism to access sensitive resources.

For example, say you have an application that requires users to sign in with their email and password to access customer data. However, when a user wants to see employee data, an **extra authentication factor** is required.

![Auth0 step-up authentication](https://images.ctfassets.net/23aumh6u8s0i/7AkLMOctLnHeZk8BFrw3fz/7aa520a8fa86e9f485d809c0aec4f0d2/step-up-authentication-flow)

Step-up authentication is an excellent option to bridge the gap between user experience and security.

## Implementing Multi-factor Authentication with Auth0

Now that you've seen why multi-factor authentication is important, you're probably wondering *how* you can implement it into your own apps. Let's go through how you can get MFA up and running in just minutes using [Auth0](https://auth0.com).

To start, <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</a>. Once you go through setup, leave the tab open, as you'll be returning to it soon.

Next, you're going to clone this [sample React application](https://github.com/auth0-blog/auth0-react-sample) that has already been set up to use Auth0 for authentication.

> If you'd like to know more about how this application was built, check out [The Complete Guide to React User Authentication](https://auth0.com/blog/complete-guide-to-react-user-authentication/).

In your terminal, run the following:

```bash
git clone git@github.com:auth0-blog/auth0-react-sample.git
cd auth0-react-sample
npm install
```

Next, create the `.env` file in your `auth0-react-sample` root directory:

```bash
touch .env
```

This is where you'll store your Auth0 variables so that you can connect your React application to Auth0. Paste the following into `.env`:

```
REACT_APP_AUTH0_DOMAIN=
REACT_APP_AUTH0_CLIENT_ID=
```

Back in the [Auth0 dashboard](https://manage.auth0.com/dashboard/), click on "**Applications**" and then on the "**Create Application**" button.

Name your application anything you'd like, click on "Single Page Web Applications", and then click "Create".

![Auth0 new application](https://images.ctfassets.net/23aumh6u8s0i/4qVyZ0Mpj5B9GhqeZuSc3Y/4aeab2a7cfaf7ebddf030ba9da13106f/new-auth0-application)

Click on the "**Settings**" tab. Paste the development URL for your React application (`http://localhost:4040`) into the text area under "Allowed Callback URLs", "Allowed Logout URLs", and "Allowed Web Origins".

**Allowed Callback URLs**: `http://localhost:4040`

**Allowed Logout URLs**: `http://localhost:4040`

**Allowed Web Origins**: `http://localhost:4040`

❗ Make sure you scroll down to the bottom and click "Save changes".

Next, you'll need to paste some of these values from the Settings page into your React application's `.env` file so that the Auth0 authentication server recognizes your React application.

Back in your code editor, open your `.env` file. Set `REACT_APP_AUTH0_DOMAIN` to the value for "Domain" from the Auth0 Settings page and `REACT_APP_AUTH0_CLIENT_ID` to the value of "Client ID". 

```
REACT_APP_AUTH0_DOMAIN=your-domain.auth0.com
REACT_APP_AUTH0_CLIENT_ID=yourclientidstring
```

Save this and then start your React application by running the following in your terminal:

```bash
npm start
```

Head to [`http://localhost:4040/`](http://localhost:4040/) in your browser to see your application live.

To test it out, click on the "Log In" button. You'll be redirected to the Auth0 Universal Login page (https://your-domain.auth0.com/login), where you can sign up as a new user. 

![Auth0 signup/login page](https://images.ctfassets.net/23aumh6u8s0i/6ToiqA66XF0UEs1OhYZ2Dw/66e51832bd2c5976b128ecf072927494/auth0-login-screen)

And just like that, you've successfully set up authentication on your demo React application! However, as you know from learning about MFA, this username and password approach leaves a little to be desired. Let's see how you can step up your application's security a notch by turning on multi-factor authentication.

### Enabling MFA with Auth0

Head back to the Auth0 dashboard and click on [**Multifactor Auth**](https://manage.auth0.com/dashboard/#/mfa) in the sidebar.

![Auth0 MFA](https://images.ctfassets.net/23aumh6u8s0i/7wWKd6DIOFnWafex1Iu4rT/c3df03c639a32e4679390c5b1223a7d5/mfa-dashboard.png)

There are a few options here that you can choose. To quickly see MFA in action, select "Phone Message". Scroll down a little and select "Always" from the "Require Multi-factor Auth
" dropdown, and then press "Save".

![Auth0 MFA phone number](https://images.ctfassets.net/23aumh6u8s0i/2jbVMojYAIwwnldyQBMCIY/07413d4028ea0afa75caf81f4f151969/auth0-mfa-phone-number)

Head back to your React application, sign out, and then sign back in. After entering your email and password, you'll be prompted to enter your phone number. Once you do, you'll be asked to enter the 6-digit code that was texted to you.

![Auth0 MFA text OTP](https://images.ctfassets.net/23aumh6u8s0i/4TisUePt1RFWO7GCoxiqnN/208fb3f7ab33d6be9120c862e862952c/auth0-mfa-text-otp)

![Auth0 MFA text OTP code](https://images.ctfassets.net/23aumh6u8s0i/7lCkR3RkB3XqjpIDsEk7F0/283bd91de9a1b338493df8d0361c4137/sms-otp)

Type in the code that you received to your cell phone, and then click "Continue". You'll then be asked to copy a recovery code. This is one of the safeguards that we covered back in the Authenticator Apps section that will allow you to recover your account if you ever lose your phone.

![Auth0 MFA recovery code](https://images.ctfassets.net/23aumh6u8s0i/1fK66CyrkCPmjghImTP4Hb/0e6390f24f78f7758cb8bc40b4130bbe/auth0-mfa-recovery)

Once you've copied it and pressed "Continue", you'll be redirected back to the React application, and you're now signed in!

🎉 **You just enabled MFA on your application in a matter of minutes!**

Auth0 offers several different options for MFA. This demo showed how to set up an SMS one-time password for the sake of simplicity, but if you'd prefer an even better option, you can choose from some of the authenticator apps that are offered. Feel free to experiment in the dashboard and see what works best for you!

## Wrap Up

If you need any more convincing about the need for multi-factor authentication, have a look at the popular website [haveibeenpwned.com](https://haveibeenpwned.com/). The website collects data on password breaches. You can type in your email address to see if it has been involved in any publicly known data breaches. As of writing this, there are **over 10 billion accounts** listed. So, even if you have a strong password, you're trusting the websites you use to keep that password safe, which unfortunately doesn't always happen.

While it's on your mind, take this time to go review your important accounts to make sure you have MFA enabled. Nobody wants to deal with the fallout of canceling their credit cards, dealing with stolen funds, and resetting all of their passwords because their bank account was breached due to weak credentials. Make sure you're always on the offensive by securing your accounts as much as possible! And if you run a website, take care of your users by giving them the means to secure their accounts on your application.

Be sure to reach out in the comments below or [find me on Twitter](https://twitter.com/hollylawly) if you have any questions. Thanks for reading!

Multi-factor Authentication Guide

df6c864847fba9687d962cb80b482764?size=200 avatar

df6c864847fba9687d962cb80b482764?size=200

Martin Gontovnikas, a.k.a Gonto, is a software engineer at heart who moved to the ‘dark side’ and became VP of Marketing at Auth0. He considers himself lucky to have found a way to combine his two passions and apply his engineering thinking model to marketing. Gonto’s analytical thinking is a huge driver of his data-driven approach to marketing strategy and experimental design. He is based in the Bay area, and in his spare time, can be found eating gourmet food at the best new restaurants, visiting every local brewery he can find, or traveling the globe in search of new experiences.

Former SVP of Marketing and Growth at Auth0

Martin Gontovnikas

The trends defining the year and how businesses can protect themselves

The 11 Biggest Data Breaches of 2020 (So Far)

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

Embed Multi-Factor Authentication using push notifications, SMS, or TOTP anywhere, taking full control of the experience.

We are pleased to announce the availability of our [Multi-Factor Authentication API](https://auth0.com/docs/api-auth/tutorials/multifactor-resource-owner-password). Up to now, we have provided support for MFA through a simple switch in the Auth0 Dashboard, following our premise of *simplicity* and ease of use. However, we also believe in providing powerful *building blocks* for our users. For this reason we have developed a new API to perform the full MFA flow, even with multiple authenticators, in a flexible and convenient way. In this article we will take a look at the API and build a simple CLI app to demonstrate how to use it. Read on!

<include src="TweetQuote" quoteText="The MFA API is now available, learn how to embed MFA in your apps taking full control of the experience!"/>

> **Note**: for most MFA scenarios, we still recommend the use of [Universal Login](https://auth0.com/docs/hosted-pages/login) whenever possible. This new API is meant for advanced use cases where Universal Login is not flexible enough. [Universal Login is the best alternative](https://auth0.com/blog/authentication-provider-best-practices-centralized-login/) in most cases.

---

## Why?
Up to now, enabling MFA at Auth0 was simply a matter of flipping a switch and optionally selecting which application you wanted to enable MFA for. When MFA is enabled, hitting the `/authorize` endpoint or starting an authorization flow through one of our libraries was enough to trigger MFA. Simple, convenient.

![MFA Switch](https://images.ctfassets.net/23aumh6u8s0i/4Fk1xnLP6wm5Ay24YJLeex/c7047fc95a6712dfa7a92f5b7c5522e7/1-mfa-enable)

However, some of our customers have requested to have more control over the MFA process. For this reason, we have been working with [ATEA Norge](https://www.atea.no/) and other customers under a private BETA program to find the right implementation for this feature. The result: a new API for MFA to give back control to you when required. Let's check it out.

> **Note**: for most MFA scenarios, we still recommend the use of [Universal Login](https://auth0.com/docs/hosted-pages/login) whenever possible. This new API is meant for advanced use cases where Universal Login is not flexible enough. [Universal Login is the best alternative](https://auth0.com/blog/authentication-provider-best-practices-centralized-login/) in most cases.

## A Simple API
The API works by introducing some changes to how the `/token` endpoint behaves. Let's take a look.

<include src="TweetQuote" quoteText="The new MFA API is simple, it works on top of the existing /token endpoint."/>

The API works in four simple steps:

1. Access token request to `/token`.
2. Challenge request to `/challenge`.
3. Asking the user for a code (if necessary).
4. Final request to `/token`.

> This scenario assumes the user is already enrolled in MFA and has at least one authenticator enabled. There's also a [new API for enrollment](https://auth0.com/docs/multifactor-authentication/api/otp) to have full control over the enrollment process. This API also allows for obtaining a list of associated authenticators, useful for using multiple authenticator, as we will see in step 2 below.

### 1. Access Token Request to `/token`
When a request is made to the `/token` endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA API is enabled, the `/token` endpoint may return a new error code: `mfa_required`.

```
POST /oauth/token HTTP/1.1
...

{
 "username": "...",
 "password": "...",
 "grant_type": "password"
 ...
}
```

Response:

```
HTTP/1.1 403 Forbidden
...

{
 "error": "mfa_required",
 "mfa_token": "..."
}
```

The `mfa_token` in the response value must be used in the following requests.

> MFA is also supported for the `refresh_token` [grant type](https://auth0.com/docs/applications/application-grant-types). This allows for use cases in which you want to require 2FA (TOTP, SMS, push notifications) when refreshing an access token, useful for extra security and step-up authentication.

### 2. Perform an MFA Challenge
When the `mfa_required` error is returned, the client must then perform a `challenge`. This is done by sending a request to the `/mfa/challenge` endpoint.

```
POST /mfa/challenge HTTP/1.1
...

{
 "mfa_token": "<from step 1>",
 "challenge_type": "otp oob",
 "authenticator_id": "optional, if known"
}
```

Response:

```
HTTP/1.1 200 OK
...

{
 "challenge_type": "oob",
 "binding_method": "prompt",
 "oob_code": "..."
}
```

The response tells the client which type of authenticator will be used (`challenge_type`) and also returns additional arguments relevant for that method. The `binding_method` parameter tells the client it should ask the user for a code.

The client may optionally request a specific authenticator through `authenticator_id`. This allows for multiple authenticators, even for the same resource.

> `OOB` means "out-of-band". All methods that are not [TOTP](https://auth0.com/blog/from-theory-to-practice-adding-two-factor-to-node-dot-js/) are OOB.

### 3. Prompt For Input (If Necessary)
If the `challenge_type` is `otp` or the `binding_method` parameter is set to `prompt`, the client should ask the user to input a code before continuing.

### 4. Get The Access Token
Finally, a new request to the `/token` endpoint is performed.

```
POST /oauth/token HTTP/1.1
...

{
 "mfa_token": "<from step 1>",
 "oob_code": "<from step 2, optional>",
 "binding_code": "<from step 3, if 'binding_method' === 'prompt'>",
 "otp": "<from step 3, if challenge_type === 'otp'>",
 "grant_type": "<one of two strings, see below>"
}
```

Grant type must be one of two values:
- For OTP: `http://auth0.com/oauth/grant-type/mfa-otp`
- For OOB: `http://auth0.com/oauth/grant-type/mfa-oob`

Response:

```
HTTP/1.1 200 OK
...

{
 "access_token": "...",
 "expires_in": "...",
 ...
}
```

Note that certain methods do not require the user to input anything (push notifications, for example). For those cases, this request must be performed repeatedly until an access token is returned or the authorization is denied. If the client is expected to repeat the request again in the future (after a certain amount of time) the response will be:

```
HTTP/1.1 400 Bad Request
...

{
 "error": "authorization_pending"
}
```

This means the user has not performed any actions yet and the client should wait a bit before trying again. The `error` can also be `slow_down` if the client is not waiting enough between requests.

That's it! If all went well, you now have an access token issued through MFA!

## Example: A CLI App with MFA
To give you a better understanding of how the API works we have developed a [simple CLI app that uses MFA](https://github.com/auth0-blog/oauth2-mfa-cli-example).

<video src="https://cdn.auth0.com/blog/oauth2-mfa-api/cli-demo-2.m4v" controls autoplay loop></video>

Take a look at the [full code in GitHub](https://github.com/auth0-blog/oauth2-mfa-cli-example). You will find the interesting bits in the `/token-endpoint.mjs` file, particularly in the `token` function.

To use the app, make sure that:
- You have created a new [Application](https://manage.auth0.com/#/applications) in the Auth0 Dashboard. Select the `Machine-to-Machine type`.
- The `token authentication method` is set to `none` in the Auth0 Application settings.
- You have enabled the `Password` and `MFA` grants in `Application -> Advanced Settings -> Grant Types`.
- You have MFA enabled. Go to [Multifactor Auth](https://manage.auth0.com/#/guardian) and enable SMS and push notifications for [Guardian](https://auth0.com/docs/multifactor-authentication/guardian/user-guide).
- You have set the right client ID (get this from the [application](https://manage.auth0.com/#/applications) settings area) in the MFA rule in the [Multifactor Auth](https://manage.auth0.com/#/guardian) section. Otherwise MFA will be enabled for all clients.

To use the app simply do:

```sh
git clone git@github.com:auth0-blog/oauth2-mfa-cli-example.git
cd oauth2-mfa-cli-example
npm install
node src/index.js login
```

The app supports some other commands. You can take a look at them by running it with no arguments.

## Other Use Cases
The sky is the limit! Here are some scenarios where using the new MFA API could make sense:

- Protect a VPN like OpenVPN (Pritnul) or Juniper with a second factor.
- Integrate with a PAM module to do second factor with SSH.
- Integrate with an LDAP service to provide a second factor.
- Step up authentication when refreshing an `access_token` (`refresh_token` grant).
- Trigger second factor from any backend process.

You are now free to build powerful MFA flows wherever you want!

## Conclusion
The MFA API brings flexibility to the use of MFA in your apps. One thing you may have noticed is that we are using the [OAuth 2.0 `/token` endpoint](https://tools.ietf.org/html/rfc6749#section-3.2). In fact, we designed this to be compatible with OAuth 2.0 right from the start. We have prepared two specification drafts, [one for MFA](https://github.com/jaredhanson/draft-oauth-mfa/blob/master/Draft-1.0.txt), [the other for authenticator association](https://github.com/jaredhanson/draft-oauth-mfa-assoc/blob/master/Draft-1.0.txt), to be sent to the [IETF OAuth 2.0 Working Group](https://tools.ietf.org/wg/oauth/). Other implementations of OAuth 2.0 can follow these specifications to implement MFA in a flexible, yet powerful way, while remaining compatible. We will have more information about this in an upcoming post.

We can't wait to see how you use this API to build powerful multi-factor flows! Let us know what you think in the comments.

<include src="TweetQuote" quoteText="We can't wait to see how you use this API to build powerful multi-factor flows!"/>

Introducing the Multi-Factor Authentication API

71313b369e8f23b7ec7b4614acdf3031?s=200 avatar

71313b369e8f23b7ec7b4614acdf3031?s=200

Staff Security Engineer

Radek Karpowicz

Automation which helps you monitor the multi-factor authentication status of various services.

Imagine a situation where your company hires more and more people and uses a lot of external services. The number of available assets you need to track is always growing. It's hard to keep up with all the services that employees at your company use on a day-to-day basis. Are you sure that you have appropriate security checks in place?

## Proactive protection

Monitoring your assets can be a manual or an automated job. If you implement the right solution, it could give you almost an instant notification when there's a problem. It's often a missing feature on the service provider side to notify you when someone disables MFA protection for one of your organization's accounts.

If you go the manual route, that just creates more routine work. More routine at work (and sometimes in life) doesn't lead to good things. Also, with shifting priorities everyday, it's easy to skip a manual process or even forget about them. Automation is a better solution.

By being more proactive and productive, we mean automation and an appropriate solution to the problem. At Auth0, we want to automate as many things as we can and decrease the number of alerts we receive to get only the real threats and not noise. It gives us the best overview of our infrastructure's security status.

## The MFA Monitoring tool

The [MFA monitor](https://github.com/radekk/webtask-mfa-monitor) uses an API to fetch information about the MFA status for every user under your organization, checks the previous state of MFA, and alerts you when that status changed (enabled or disabled state).

![Slack MFA alert](https://images.ctfassets.net/23aumh6u8s0i/5OJnSCaBGuhks7eZ8ue5RV/3e2fa24f916f501cdce48819cd42b7ff/slack)

Possibilities for implementing additional monitors or notifiers which will receive your alerts are endless as long as there's an API on the provider side. For now, we have implemented checks for GitHub and Amazon Web Services (AWS), we added Slack as a notification provider. If you use Hipchat or Twitter for notifications, you can quickly add them as an additional module. Feel free to send pull requests!

### Implementation

The MFA Monitor was implemented in JavaScript with Node.JS as a target platform. The toolkit consists of two main parts - notification and monitor modules.

#### Monitors

The monitor module was implemented to provide the possibility to inspect the status of MFA settings of different services. You can quickly add new controls as far as the service you want to monitor allows you to fetch MFA status over an API or another channel. What monitor module requires is to receive the status of protection from the external service.

As an example, the GitHub monitor was implemented using publicly available API to fetch information about users assigned to your organization. Requirements could be different for every service as GitHub requires an API token with access to the list of members of your organization. Always remember to choose privileges for access tokens wisely.

The important part of the monitor module is the callback that returns information about all user logins with MFA disabled:

```javascript
 client.orgs.getMembers({
 org: ctx.secrets.ORGANIZATION,
 per_page: 100,
 filter: '2fa_disabled'
 }, (err, res) => {
 if (err) return cb(err);
 if (!res) return cb(new Error('Empty response received from Github API!'));

 cb(null, res.map(data => data.login));
 });
```

#### Notifier

Notifiers are modules that were created to notify users about the security event that occurred on the 3rd party service - it could be information about enabled or disabled MFA on the particular account.

The first module we implemented was Slack, but it doesn't mean you can only use chat applications. It's able to send notifications directly to a URL, Twitter, or even TCP socket; it depends on what you need and want to implement.

To implement notifier modules and secure required tokens you can use secrets that could be stored by the [Webtask](https://webtask.io) platform. After that you can call them using ``ctx.secrets`` prefix.

```javascript
 const slack = require('slack-notify')(ctx.secrets.SLACK_WEBHOOK_URL);
 const mfaStatus = !!ctx.body.mfaStatus;
 slack.onError = (err) => cb(err);

 ctx.body.data.forEach(service => {
 let accounts = service.accounts.map(account => `*${account}*`).join(', ');
 let message = getMessage(service.name, accounts, mfaStatus);

 slack.send({
 channel: ctx.secrets.SLACK_CHANNEL_NAME,
 username: 'MFA Agent',
 text: message
 });
 });
```

#### Storage

An early version of this tool was using MongoDB as a storage. It generated many additional steps to setup this database. As for the latest release, it's using built-in storage into the Webtask service. In short it means that you don't need to use any external database and worry about the security of your data, now it's safe, encrypted, and stored locally.

```javascript
db.init(ctx.storage);
```

Using the [Webtask storage](https://webtask.io/docs/storage) is easy, to write or read data you need to call methods on the ``ctx.storage`` object. Below is the implementation of the storage wrapper which helps to handle storing and receiving data using Promises.

```javascript
'use strict';

const Promise = require('bluebird').Promise;
let db;

module.exports = {
 init: (storage) =>
 db = storage,

 getStoredData: () =>
 new Promise((resolve, reject) =>
 db.get((err, data) => {
 if (err) return reject(err);
 resolve(data || []);
 })
 ),

 storeData: (data) =>
 new Promise((resolve, reject) =>
 db.set(data, {force: 1}, err => {
 if (err) return reject(err);
 resolve();
 })
 )
};
```

You can easily implement additional storage modules if needed. We wanted to keep it as simple as possible, that's why we decided to use built-in storage which is also the best way to work with the Webtask platform.

### Installation

Setting up the MFA monitoring in place requires creating the Webtask account for free ([https://webtask.io](https://webtask.io)). It's a server-less environment, and it means that you don't need any additional infrastructure to monitor your assets. Fewer assets means less work for you.

![MFA monitor configuration process](https://images.ctfassets.net/23aumh6u8s0i/5a6kFSy2amtxyZ94pFc4cR/7067346475056cac6d9cb16c5eea2aad/mfa)

After creating the Webtask account you need to clone the MFA monitor repository from GitHub, install required npm packages (``npm install``) and you're ready to go. The configuration process is rather straightforward, and it asks you for all necessary data like GitHub token, Slack token, etc.

By default, it installs GitHub monitoring and sends alerts to Slack. In case if you want to modify it, you need to write additional monitors or notifiers. You can find more details on the official repository [README](https://github.com/radekk/webtask-mfa-monitor/blob/master/README.md) file.

### Usage

Once installed MFA monitor shouldn't require any maintenance steps. It's working as a Webtask cron job which means that it runs periodically to pull out the data from your services and checks the status of MFA setting.

You can periodically check the log stream to verify that MFA monitor is working or verify if the status is monitored.

## Awareness

Keep in mind that monitoring the MFA status will not protect you against other malicious activities that could occur. The purpose of this particular tool is to alert you every time your users forget to enable MFA.

<include src="TweetQuote" quoteText="The MFA monitoring tool will alert you every time your users forget to enable MFA."/>


This tool works well for us; it fits into our methodology of being a proactive team. Setup your monitors and start protecting your accounts now.

"multi factor authentication"