andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn some guidelines to migrate your Auth0 Hooks to Auth0 Actions successfully.

Migrating Auth0 Hooks to Auth0 Actions

How to use Auth0 Actions to let users access your application or website for a trial period.

Managing Trial Periods with Auth0 Actions

How to deal with logins that must meet specific criteria based on the user’s country? Let's see how you can do this.

If your application needs conditional access based on the user’s country, you can easily achieve it with a simple Auth0 Action. Let’s see how you can do it.

## Why a Country-based Login?

Controlling user access based on the country where they're located when they log in to your application may have different reasons. To mention just a few of them:

- *Legal reasons*. Laws are different around the world. This leads to adapting access to services or content offered by your application so that it does not break the laws of a particular country. For example, think of online gambling: it is illegal in some countries. Also, think of the liability requirements of [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) for Europe: you must comply with them in order to offer your services to European citizens.
- *Business reasons*. A company may decide not to offer their services or product to a country for business reasons: maybe because the cost of delivering that product or service in a given country is not affordable, or because the pricing strategy may depend on the country. You can even consider copyright licenses: think of the availability of video on-demand services due to copyright restrictions, for example.
- *Security reasons*. You may consider accesses coming from a given country dangerous because most traffic is statistically malicious.

Depending on the reason you want to control user access and on the services or content offered by your application, you can apply different restriction levels. You can range from blocking access to your application ([geo-blocking](https://en.wikipedia.org/wiki/Geo-blocking)) to adapting your services or content to that country's audience.

> Be aware that the most common technique to geolocate a user is based on their IP address. However, blocking users based on their IP address can be easily circumvented through VPNs or anonymizer services.

## Using Auth0 Actions

This article will focus on how you can use [Auth0 Actions](https://auth0.com/actions) to detect the user's country and how to block them or require a second authentication factor. Auth0 Actions are JavaScript functions running in a Node.js environment executed when specific events happen in a few internal Auth0 Flows, such as the Login Flow, the Change Password Flow, the User Registration Flow, etc.

Each Flow is made up of one or more triggers. For example, the Login Flow runs when a user logs in. This Flow has a post-login trigger: an event fired after the user logs in. You can handle this event through one or more Actions. You can think of Actions as event handlers that run when a specific event fires in an Auth0 Flow.

The following is a graphical representation of an Action (*AddRoles*) that will be executed in the Login Flow after the user logs in:

![Auth0 Action in the Login Flow](https://images.ctfassets.net/23aumh6u8s0i/1pJn7J2p7cICewJkSv4Ecj/4030cd2fa04c3df43e8c29b3c537b68c/auth0-action-in-login-flow.png)

In the following, you will use the post-login trigger of the Login Flow to detect the user's country and apply your control strategy.

To learn more, you can check out this blog post for [a quick introduction to Auth0 Actions](https://auth0.com/blog/introducing-auth0-actions/).

## Blocking Logins from a Country

Let's assume you want to block users coming from a given country. As I said, you need to create an Auth0 Action to handle the post-login trigger. So, head to your [Auth0 dashboard](https://manage.auth0.com/). If you don't have an Auth0 account yet, you can <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 one</a>.

Select *Actions* on the left side menu and then [*Flows*](https://manage.auth0.com/#/actions/flows). You should land on the following page:

![Auth0 Flows in the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/4rUFsGdm1cYpgP6jS8xF98/ed055e37e3cb144cc7f5d540095b9ab3/auth0-flows-dashboard.png)

Click the *Login* Flow and enter the Flow editor, as shown below:

![Auth0 Flow editor](https://images.ctfassets.net/23aumh6u8s0i/4uIJUK8GRjAkfo5eksSffh/0c62aeb77c6178fba58b1bdc30a21491/auth0-flow-editor.png)

Here, you can add a custom Action by clicking the *Build Custom* menu item in the Add Action section of the Flow editor:

![Add Custom Action menu](https://images.ctfassets.net/23aumh6u8s0i/WD1Alxdh14g8jrzztaD58/9597f8fd5a522f02b5816fdc525b4f60/add-custom-action-menu.png)

This allows you to assign a name to the Action you are going to create and to access the Action editor:

![Auth0 Action editor](https://images.ctfassets.net/23aumh6u8s0i/5uI0EGTobmSMBbTcifj6dL/382a78976db5dd4f250759f6f8c47b53/auth0-action-editor-block-users-by-country.png)

Replace the code in the editor with the following:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  if (event.request.geoip.countryCode === "AQ") {
    const countryName = event.request.geoip.countryName;
    
    api.access.deny(`Users from ${countryName} are not allowed!`);
  };
};
```

This code defines the `onExecutePostLogin()` method, which handles the post-login trigger. It receives two parameters: `event` and `api`.

The `event` parameter provides some information about the current running environment. For example, it allows you to access the current user's data, the current request, the tenant, etc. For more details about [the Pre User Registration `event` object, check out the documentation](https://auth0.com/docs/actions/triggers/pre-user-registration/event-object).

The `api` parameter provides methods for changing the behavior of the Flow. For example, it allows you to deny access to your application or set specific metadata for the user or the application. For more details about [the Pre User Registration `api` object, check out the documentation](https://auth0.com/docs/actions/triggers/pre-user-registration/api-object).

In your Action, you used the `event.request.geoip` object to get geolocation information about the user logging in. In particular, you checked the `countryCode` property, which can have one of the [ISO country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) as a value. In the example, you want to block users coming from Antarctica, whose country code is `AQ`. The `geoip` object also provides you with other information about the user's country. For example, you used the `countryName` property to get the full name of the country. Check out [the post-login `event` object documentation](https://auth0.com/docs/customize/actions/triggers/post-login/event-object) for more details.

If the user's country is Antarctica, access is denied through the `api.access.deny()` method. The string passed to the `deny()` method briefly explains the reason for the denied access.

Click the *Save Draft* button to store the Action you just created.

To test this Action, you should... move to Antarctica and try to log in to your application from there. This approach is a bit expensive and ineffective 🙂. Alternatively, you can test the Action by using the *Test* button on the upper-left corner of the Action editor. It opens a sliding window whose content is the `event` object that will be passed to the Action:

![Testing Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/1VA1JtGrCB9hzt5fasJC0p/0b758ea2dea47ebb8e3ee10e7d5b08ca/testing-auth0-action.png)

You can modify the `geoip` object's properties to simulate a request coming from Antarctica and click the *Run* button. At this point, you will get a window showing a result similar to the following:

![geoip test result](https://images.ctfassets.net/23aumh6u8s0i/dqH3FqfMGOJUGh2Jeg84x/e442c573c846355a336edfd734eb3084/geoip-test-result.png)

## Requesting MFA from a Country

In addition to or instead of blocking users, you may want to enforce [Multi-Factor Authentication (MFA)](https://auth0.com/docs/secure/multi-factor-authentication) for users logging in from specific regions. First, you must have [configured MFA in your Auth0 dashboard](https://auth0.com/docs/secure/multi-factor-authentication/enable-mfa). This lets you define what additional factor you want to use. The next step is to force MFA when a user logs in from specific regions.

For example, assume you want to enforce MFA for North American users. You can create an Action with the following code:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  if (event.request.geoip.continentCode === "NA") {
    api.multifactor.enable("any");
  };
};
```

In this case, you used the `continentCode` property of the `geoip` object. If a user logs in to your application from one of the North American countries, you force MFA by invoking the `api.multifactor.enable()` method. The `"any"` string passed to the method tells Auth0 to use any of the configured factors. Alternatively, you can pass a string identifying a specific provider. Check out [the documentation to learn the  available values for MFA providers](https://auth0.com/docs/customize/actions/triggers/post-login/api-object).

> To make your Action available to the Login Flow in your production environment, you have to click the *Deploy* button and drag the newly created Action into the Flow editor, as explained in [the introduction to Auth0 Actions](https://auth0.com/blog/introducing-auth0-actions/#Creating-Your-First-Auth0-Action).

## Recap

In conclusion, throughout this article, you learned the main reasons you may want to control user access to your application on a country-based criterion and how you can implement it with Auth0 Actions. You learned the geolocation features of the `event.request.geoip` object and how to leverage them to block users or enable MFA when they come from specific countries.

However, remember that while the geolocation approach is pretty straightforward, it is not infallible.


Country-Based Access with Auth0 Actions

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'><strong><b>egghead.io</b></strong></a>.


Developer Advocate

Will Johnson

Use Auth0 Actions with webhooks to send a Slack message after a new user signs up.

Having a new person sign up for your website is an exciting experience. You feel a rush of energy every time someone chooses your service, enters their email and password into a "Log in" form, and clicks "Sign Up." Get that jolt of excitement in real-time by creating an Auth0 Action to send a message to Slack when a new user registers an account.

## What You Need

* Auth0 Account. If you do not have one, you can sign up for a <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">free Auth0 account</a>.

* Application in our Auth0 tenant. Any web-based, mobile, or desktop application will work. If you don't have any applications that use Auth0, you can download one from the [Auth0 Quickstarts](https://auth0.com/docs/quickstarts/) page.

* Slack account. If you belong to a Slack workspace, you already have one. If you don't have a Slack account, don't worry — you can create one after creating a Slack workspace.

* Slack workspace. You need access to a Slack workspace where the admins will approve your app, or one where you're an admin. If neither of these apply to you, follow the steps in the next section, where you'll set up a Slack workspace under your administrative control.


## Create a Slack Workspace

To approve apps in Slack, you need admin permissions. If you don't have a Slack workspace that you are the admin of, you can create your own free Slack workspace that will give you admin privileges. Go to the Slack [Get Started page](https://slack.com/get-started#/createnew). 

Enter your email address and click **Continue**, or continue with Apple or Google. Check your email for a confirmation code. Enter your code, then click **Create a Workspace**. Go through the following pages to name the workspace and a channel. You can skip inviting people for this example. Congrats! Now you have a workspace, and you can create a Slack webhook.

## Create a Slack Webhook

To post messages into Slack from outside sources, you need a webhook URL. [Webhooks](https://en.wikipedia.org/wiki/Webhook) enable apps to "talk" to each other when something new happens. In this post, you'll take the email address the user entered into the Auth0 login box and send it to Slack as a message.

First, you'll need an app in your Slack workspace to send the webhook information to your Slack channel. Go to [api.slack.com](https://api.slack.com) and click **Create an app**.

![Slack API homepage](https://images.ctfassets.net/23aumh6u8s0i/1r6NCn0k67X5fm6n418hPm/2bccddd6addc4eab2a8d312ad130adca/api.slack.com.png)

This will bring up the _Create an App_ modal. Click **From scratch**. 

The next modal you'll see is _Name app & choose workspace_. Fill in an app name; you can use "slack-test" if you can't come up with something better. You can always change the name later when you think of something else. 

Then select the workspace that you want to connect the app to. Make sure this is the correct app because you can't change the app's workspace later. After you pick a workspace, click **Create App**.

![Slack Name app & create workspace modal](https://images.ctfassets.net/23aumh6u8s0i/2gEJlNDHCE4pAVsnVK5pQ5/3820f59a4a5517fc32bfaff0dae304e6/name_app_workspace_page.png)

You'll be taken to the Basic Information page. This page is where you turn on the ability to use webhooks and get your webhook URL. On the left side of the page, Click **Incoming Webhooks**. Click the toggle button on, and Slack will create a bot user if you don't already have one.

![Slack Activate Incoming Webhooks page](https://images.ctfassets.net/23aumh6u8s0i/7GDOR9bo5twAIA9dyfSzx6/4d594a84e30394351cf05e8a0fb35611/turn_on_webhooks.png)

The page will refresh, and a shiny new section, _Webhook URLs for Your Workspace,_ will appear. To activate the webhook and create the URL used in your Auth0 Action, scroll to the bottom of the page and click **Add New Webhook to Workspace**. This button makes a shortcut to install Slack apps, and using it means you don't have to write any code to generate a webhook URL.

![Slack Add New Webhook to Workspace section](https://images.ctfassets.net/23aumh6u8s0i/234YTEWqT0T66SvEvnXb3p/8f64036f18b0a291e21a84eef10679ce/add_webhook_to_workspace.png)

This next screen lets you know that your app wants to access the workspace. It will ask you what channel you want the app to post and give you a drop-down to choose what channel in your workspace you want the app to post in. Once you have selected the channel, click **Allow**.

![Slack app permissions page](https://images.ctfassets.net/23aumh6u8s0i/1Xv1RqErttgUYQyCDEQzVn/babd1c8c1e20a3ad2dfdb8a3edf8131f/permissions_page.png)

You're taken back to the _Incoming Webhooks_ page. You'll now see the webhook URL has been filled in with a value, with the channel you selected for it and the date it was added. Copy and save the webhook URL somewhere safe; you'll need that later when you create a new Auth0 Action.

![Slack webhooks URL section](https://images.ctfassets.net/23aumh6u8s0i/4VU8xMikQhXe20WvoNgMg6/0a5e8a29057ca51f305c45ef7af23a4b/webhooks_url.png)

> Your webhook URL contains a secret. Don't share it online, including public Git repositories.

Now that you have your webhook URL created for Slack, you need to head to [Auth0.com](https://auth0.com/), sign in, and create an Auth0 Action that will send Slack messages.

## Create Post User Registration Action

Auth0 Actions allow you to customize events like login and registration to add behaviors that go beyond the default Auth0 features. Actions have an in-browser code editor where you can write Node.js code that is stored and runs on infrastructure owned and maintained by Auth0.

Create your Action by clicking **Actions > Library** on the left side of the Auth0 Dashboard.

![Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/1z3vTIqDIBzrT29Q3xI6IW/f7918c0dbcbac8bfc0583ad4f56b76c1/action_library.png)

This page lists the Actions that have already been installed, and there's a **Custom** tab for actions you created. On the upper right side, click **Build Custom**. You'll see the _Create Action_ modal, which asks to name your Action, assign when you want it to run, and which Node.js version you wish to use.

First, give your Action a name like "Slack Message." Next, select the event that will cause the Action to run from the **Trigger** drop-down. For this example, select **Post User Registration**. Leave the **Runtime** selection set to the recommended version (Node 16 at the time of writing). Finally, with all those details filled in, click **Create**.

![Auth0 Create Action Modal](https://images.ctfassets.net/23aumh6u8s0i/5Y0Jsw8yiTyxk8oFDd2rxX/bf1ffda407d666b3e9b6c2552df4ff3f/create_action_modal.png)

You'll now see the in-browser code editor where you write the code that will run when your Action is triggered. Take a look around the code editor first. You'll see a "play button" icon for testing your Action before deploying it on the left. Under that, you'll see a key icon to enter secrets (such as webhook URLs). The box icon is where you click to add modules from NPM.

Above the code editor and to the right, there are three buttons. **Version history** lets you see and revert back to previous versions of the Action. Next is **Save Draft**; if you're not ready to finalize everything in your Action, you can save it as a draft to work on later. Lastly, there's **Deploy**, which you use when you've tested your Action and it's ready for prime time!

The code editor is pre-populated with the appropriate code for the kind of Action you're writing. In this case, it contains the `onExecutePostUserRegistration` function. Inside this function, you'll write the code to run after the user registers a new account.

![Actions Code Editor](https://images.ctfassets.net/23aumh6u8s0i/2ch3BgnVO8yVTMQUV5zld9/265f5d7076d825e224736fb8e4add861/actions_code_editor.png)

### Add webhook URL as a Secret

Time to use that webhook URL you've been keeping safe! Click the key icon on the left side of the code editor. This will open the side menu; click the blue **Add Secret** button. This opens up the **Define Secret** modal, which has fields for the name of the secret and the value it will hold. 

Name the secret `SLACK_WEBHOOK_URL` in the key field, then paste your Slack webhook URL into the value field. Now click **Create**.

![Auth0 Actions Define Secrets Modal](https://images.ctfassets.net/23aumh6u8s0i/3a0jfV88wbvNLC0f7WiypP/754705989067ae70d60cc1e5e8c21b37/define_secret_modal.png)

The page will refresh, and you'll see your secret has been added to the _Secrets_ menu.

> When secrets are created, their values are never revealed. Auth0 encrypts and stores all secrets securely.

### Add npm package

With Actions, you can choose from over 1,000,000 public npm packages and add their functionality to your Action. This action will use the 'slack-notify' npm package. It's a Node.js wrapper around the Slack webhook API that makes it easy to send notifications to Slack from external applications.

Click the box icon to bring up the _Modules_ side menu and click the blue **Add Module** button. In this modal, you add the name and version of the npm package. Enter **slack-notify** for the name. The name has to match the package's name as listed in npm, so make sure you check its name to be sure you're providing the correct one. The version is set to the latest by default. Now click **Create**, and all the pieces to write the code that will send a message to Slack will be in place.

![Auth0 Actions add module modal](https://images.ctfassets.net/23aumh6u8s0i/2w6qekeLIQ9Uz0csHjBbsu/83e7cdf29cc6a511afa9de96921fdf0d/add_module_modal.png)

### Write custom logic

The in-dashboard code editor works like your own editor that you know and love. The code that you enter into it is hosted and maintained by Auth0. Whenever you want to make changes to your Action in the future, you can do so without touching your codebase.

First, you'll add the slack-notify npm package at the top of the code editor by typing `const initSlackNotify = require(slack-notify).`

Next, you'll see the `onExecutePostUserRegistration` function. This async JavaScript function will run after a user is registered and saved to the database. Create a `slack` variable and pass the slack-notify module with your secret webhook URL inside this function.

Every Action has an `event` object that has information related to the trigger. You'll use it to get access to the webhook URL you stored as a secret earlier. The code will look like this:

```js
const slack = initSlackNotify(event.secrets.SLACK_WEBHOOK_URL)
```

Then, below the `slack` variable, create a `message` variable that will include the text to be sent to the Slack channel. Set it to a template string with the text "New User" and the user's email address. The `event` object has the newly registered user's email address. You can display it by passing `event.user.email` to the template.

```js
const message = `New User: ${event.user.email}`
```

Lastly, write the code to actually send the message. The slack-notify npm package has 3 different notification methods bundled already: `bug,` `success,` and `alert`.

* `bug` - used for errors.
* `alert` - used for when something important happens.
* `success` -  used for when messages go through with no errors.

You'll use the `success` method in this example. Within the `success` method, pass in an object with a key of `text` (which is one of the built-in custom fields of the slack-notify package) set its value to the `message` variable.

```js
slack.success({
    text: message
  })
};
```

With this code, when a new user successfully signs up, a message with the user's email will be sent to Slack. 

You should make sure it works as intended before deploying it. You can do this inside the Auth0 dashboard without having to leave the site. Click **Save Draft** in the upper right corner before starting the test.

Here is the complete code for the Action:

```js
const initSlackNotify = require('slack-notify')

exports.onExecutePostUserRegistration = async (event) => {
  const slack = initSlackNotify(event.secrets.SLACK_WEBHOOK_URL);
  const message = `New User: ${event.user.email}`

  slack.success({
    text: message
  })
};
```

## Test the Action, Then Deploy It

With Actions, you can run tests right in the browser without making any changes in your app or "live-testing" with users. Click the "play button" icon on the left side of the code editor. With this section open, you can see the contents of the event object in case you want to use some of the other information. At the bottom of the page, click the **Run** button at the bottom of the screen. The "Test Results" screen slides up, and the _Commands_ and _Error_ fields should be empty.

![Auth0 Actions Test Results](https://images.ctfassets.net/23aumh6u8s0i/WvnMTcD6Vy7g1dA3ppecN/5a0e10a1dcfee7b03b24b83c9bbd796a/actions_test_results.png)

Go to the Slack workspace you created earlier, and see the new message with the sample email address provided by the test event object.

![Slack test message](https://images.ctfassets.net/23aumh6u8s0i/4FjY3CKPEtfhejwhf2fWqP/d124c092d3a71d7b6a444e0cf75d43fe/slack-test-message.png)

With everything in working order, click **Deploy**. This will record the Action and give it a version number. This way, you can continue to make changes to the Action without affecting the deployed version. 

Now that the Action is deployed, it's time to add it to your Auth0 tenant so you'll get notified when a new user signs up for your site!

## Add the Action to the Post User Registration Flow

The last thing to do is attach your new Action to a flow. Flows are different points in the Auth0 lifecycle, from logging in to saving a new user to the database. When you add an Action to one or more of these points, the Actions will trigger in the order in which they are listed.

You'll use the _Post User Registration_ flow in this tutorial. On the left side of the screen, click **Actions > Flows**. This will display all the currently available flows. Select **Post User Registration**, which executes after a user is added to the tenant’s user database.

![Auth0 Actions Choose Flow page](https://images.ctfassets.net/23aumh6u8s0i/6yrPstgkYrypbQvBm3rl36/1e4994a13aea747e09854d79ea5aab99/choose_flow.png)

The following pages show the Actions drag and drop flow visualizer. Here you can add one or more Actions that will run in order after the selected trigger. The Actions are on the right; this section has a tab for installed Actions from the Auth0 marketplace and a custom tab for Actions you created. Click **Custom**, then drag and drop your Slack action between the _Start_ and _Complete_ points.

![Auth0 Actions Flow visualizer](https://images.ctfassets.net/23aumh6u8s0i/3FULQXi17MPJEnpIcAFo7B/50c27ca253d113dc8dac29a215b04ae1/actions_flow.png)

Once that is done, click **Apply**. Now the Action is ready for prime time and real users! 

Sign up a new user on any of the sites in your Auth0 tenant, and you should see that user’s email address appears in Slack.

> You could also use the _Try your Login_ box option in the Auth0 dashboard's _Getting Started_ page.

## Conclusion

Actions offer you new opportunities to build authentication experiences that are truly unique to you and your application. The access to npm packages lets you add custom code and reduce maintenance for you. Testing your code in the browser without running a local build saves you time. The drag-and-drop editor lets you add a new feature without touching your own codebase, because the Actions code is hosted by Auth0!

Now that you know to create a custom Action, check out the [_Actions Triggers_ page](https://auth0.com/docs/customize/actions/triggers) in the Auth0 docs to see what other kinds of Actions you could develop.

Send Slack Message After New User Sign Up with Auth0 Actions

josh-cunningham

I’ve been working on the web since 2007 as an engineer, designer, strategist, user interface consultant, team lead, project manager, and product builder. I’m currently the lead engineer on our Marketplace team helping partners design, build, and publish integrations to the Auth0 platform. I’m fascinated by current trends in digital identity, how we communicate asynchronously in our personal and professional lives, how software gets made on a team, and note-taking techniques.

Lead Ecosystem Engineer

Josh Cunningham

Are you considering migrating your Auth0 Rules to Auth0 Actions? Here are some guidelines to do it successfully.

<div class="alert alert-danger alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>We are deprecating Auth0 Rules and Hooks by November 18, 2024. To learn more about what's changing, check out the <a href="https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/">deprecation announcement blog post</a>.</strong>
</div>

<AmpContent>
<amp-youtube
    data-videoid="B5pzpPqPbbM"
    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/B5pzpPqPbbM' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>

Auth0 Actions offer many advantages over Rules. If you are using Rules to customize your Auth0 integration experience, you should consider migrating to Actions. Learn how to plan and implement this migration.



## Comparing Auth0 Rules and Actions

One of Auth0's strengths is its focus on extensibility, i.e., the ability for the user to customize the standard behavior of Auth0's identity solutions. [Auth0 Rules](https://auth0.com/docs/customize/rules) was the first tool that enabled users to run custom code to extend Auth0 authentication. Rules are serverless code blocks executed right after successful authentication but before tokens are issued.

To satisfy the widest range of extensibility needs, Auth0 has constantly worked on improving this tool. Recently, it consolidated the acquired experience on customization and provided developers with [Auth0 Actions](https://auth0.com/actions), a solid environment for most code-based customization needs.

Auth0 Actions offer a lot of benefits over Rules. So, if you are about to start your customization, Actions are the recommended tool. On the other hand, if you have already implemented your customization through Rules, you are strongly encouraged to migrate to Actions. Let's look at a few advantages you can get by switching to Actions:

- Rules let you handle just the authentication flow. **Auth0 Actions let you handle multiple flows**: authentication, pre and post user registration, password change, client credential exchange, phone message sending.
- Rules don't have an integrated version control system. Actions do. **You can modify an Action without affecting the one in production**, create multiple versions, and restore a previous one. 
- Unlike Rules, the Actions editor supports code hints, all npm packages, and isolated secrets management. **The developer experience is significantly improved**.

Read [this blog post for a quick introduction to Auth0 Actions](https://auth0.com/blog/introducing-auth0-actions/).

> While Auth0 Actions bring you an improved customization environment, Rules and Hooks are still available, and they all can live together. <u>Just remember that Rules and Hooks are executed before Actions.</u>

You can use Actions to replace your Rules, but be aware of some limitations:

- In Rules, you can share data with other Rules in the pipeline by adding properties to the `user` and `context` objects. These properties are accessible in subsequent Rules. In Actions, you can't do this, although changes to the user's metadata can be accessed by subsequent Actions.
- Rules can [modify SAML assertions or attributes](https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions). Actions can't.
- Rules have [limited access to the Auth0 Management API](https://auth0.com/docs/customize/rules/use-management-api) and [the `global` and `auth0` objects](https://auth0.com/docs/customize/rules/rules-best-practices/rules-environment-best-practices#global-object). Actions can't, but have an alternative approach for doing similar tasks, as you will learn in the following.

Take a look at [the full list of limitations of the current implementation](https://auth0.com/docs/customize/actions/limitations).

With these caveats in mind, let's take a look at how you can convert your Rule into an Auth0 Action.

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>No-Code Solution</strong><br> 
  When migrating from Rules to Actions, a developer may also want to consider a no-code Integration - including Actions Integrations - from the <a href="https://auth0.com/resources/whitepapers/broken-auth-checklist">Auth0 Marketplace</a>. These Partner-built integrations solve common identity use cases such as consent management, progressive profiling, and user verification, enabling developers to go-to-market faster while reducing development and maintenance costs associated with custom code.<br> 
</div>

## Code Conversion Guidelines

Auth0 Rules allow you to customize the authentication flow. That means you can convert a Rule into an Auth0 Action handling [the Post Login trigger of the Login Flow](https://auth0.com/docs/customize/actions/triggers/post-login).

> This article will not guide you step-by-step through creating an action or migrating a rule. It assumes that you have a basic understanding of how to create a Rule and how to create an Action.
> If not, please refer to Auth0 documentation about [Rules creation](https://auth0.com/docs/customize/rules/create-rules) and [Actions writing](https://auth0.com/docs/customize/actions/write-your-first-action).
> In both cases, you need an Auth0 account. If you don't have it, <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 get one for free</a>.

The Actions editor for the Post Login trigger looks like the following:

![Auth0 Action editor](https://images.ctfassets.net/23aumh6u8s0i/29HiQQis75pvxp6arSitxM/4927a37ca2557f8567bd838b8c8cb6c0/auth0-action-editor.png)

Conceptually, to migrate your Rule, you need to move the body of the function that implements it into the body of the following function:

```javascript
exports.onExecutePostLogin = async (event, api) => {
};
```

This is not just a matter of copy and paste. You need to apply some changes to make the conversion effective. So, let's focus on the specific changes you should apply to your Rule's code.

> You can have multiple Rules handling your authentication flow. You can map these Rules to as many Actions by keeping the same order. This will ensure you keep the same functionality.

### Mapping parameters

An Auth0 Rule is a JavaScript function with three parameters: `user`, `context`, and `callback`. The `onExecutePostLogin()` function implementing the Action has two parameters: `event` and `api`. Besides the different names, how can you map those parameters? How can your Action retrieve the same data from the parameters as your Rule?

Actually, the design of Actions brought you consolidation of the data passed by the running environment to the Action function. As a general rule, all read-only properties of the `user` and `context` objects in Rules have been moved to the `event` object in Actions. Any interaction with the running environment, like failing a login or updating user metadata, is implemented through methods of the `api` object.

Please refer to the documentation to learn more details about [the `event` object](https://auth0.com/docs/customize/actions/triggers/post-login/event-object) and [the `api` object](https://auth0.com/docs/customize/actions/triggers/post-login/api-object).

### Accessing user data

In Rules, you get data about the current user by accessing the `user` object parameter. In Actions, you need to access the `event.user` object. Here you can find the same data as the `user` object except the attributes added by an external identity provider or custom database script.

To give you an example, if you have the following Rule implementation:

```javascript
function myRule(user, context, callback) {
	const userEmail = user.email;
	const userId = user.user_id;
	
	// ... additional code
}
```

You can convert it into an Action implementation as follows:

```javascript
exports.onExecutePostLogin = async (event, api) => {
	const userEmail = event.user.email;
	const userId = event.user.user_id;
	
	// ... additional code
};
```

> Notice that while the `user.app_metadata` object could be undefined in Rules, the counterpart `event.user.app_metadata` will always be defined in Actions.

### Accessing context data

In Rules, the `context` object stores data about the current login session. In Actions, you can find the same data in the `event` object.

Consider the following Rule function:

```javascript
function myRule(user, context, callback) {
	const clientId = context.clientID;
	const clientMetadata = context.clientMetadata || {};
	
	const connectionId = context.connectionID;
	const connectionMetadata = context.connectionMetadata || {};
	
	const protocol = context.protocol;
	
	const tenant = context.tenant;
	
	// ... additional code
}
```

In an Action, it will become as shown below:

```javascript
exports.onExecutePostLogin = async (event, api) => {
	const clientId = event.client.client_id;
	const clientMetadata = event.client.metadata;
	
	const connectionId = event.connection.id;
	const connectionMetadata = event.connection.metadata;
	
	const protocol = event.transaction.protocol;
	
	const tenant = event.tenant.id;
	
	// ... additional code
};
```

As you can see, some properties of the `context` object have become properties of a few objects attached to the `event` object. For example, you have the `client` object, the `connection` object, and so on. In other words, the login session data has been refactored to be more clearly organized.

Be aware that some property names have different spellings. For example, `clientID` becomes `client_id`, `connectionMetadata` becomes `connection.metadata`, etc.

Please compare the documentation of [the `context` object in Rules](https://auth0.com/docs/customize/rules/context-object) and [the `event` object in Actions](https://auth0.com/docs/customize/actions/triggers/post-login/event-object) to learn more about the differences.

### Dealing with dependencies

Auth0 Rules allow you to include dependencies to power up your code. You can leverage thousands of npm packages, but not all the packages available in the [npm registry](https://www.npmjs.com/). If you need a package that is not available for Rules (or even just a specific version of an npm package), you need to request it to Auth0.

In Actions, you can add dependencies for all the available packages in the npm registry, which means over one million.

Also, unlike Rules, in Actions you don't need to specify the package version in the code. That means, for example, that in Rules you have to declare a dependency this way:

```javascript
function myRule(user, context, callback) {
	const axios = require("axios@0.22.0");
	
	// ... additional code
}
```

In Actions, you specify the package version just in the editor's module manager and your code looks like the following:

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

exports.onExecutePostLogin = async (event, api) => {
	// ... additional code
};
```

Notice that you import the dependency outside the function's body, more in the style of a Node.js module.

### Converting Rules' callbacks

In Rules, you use the `callback` parameter to pass back the result of your processing. For example, in order to pass the control to the Auth0 authentication process, which will possibly run the next Rule, you should invoke the `callback()` function by passing the current `user` and `context` objects. In case you want to stop the current login process, you need to call the `callback()` function with an error instance.

With Actions, everything is more straightforward. To pass control, simply use `return`. To stop the login process, call the `api.access.deny()` method.

Consider the following Rule function:

```javascript
function myRule(user, context, callback) {
	const userAppMetadata = user.app_metadata || {};

	if (userAppMetadata.condition === "success") {
		// This Rule succeeded, proceed with next Rule.
		return callback(null, user, context);
	}
	
	if (userAppMetadata.condition === "failure") {
		// This Rule failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}
	
	// ... additional code
}
```

This code succeeds or fails based on the value of the `condition` property of the `app_metadata` object. You can convert this code into the following Action function:

```javascript
exports.onExecutePostLogin = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		return;
	}
	
	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the login with an error response.
		return api.access.deny("Failure message");
	}
	
	// ... additional code
};
```

In summary, you should replace any instance of `callback()` in your Rule with a call to `api.access.deny()`, in case of failure, or with `return`, in case of success. You can also omit the `return` statement if your code runs to the end of the function's body.

## Conversion Examples

Now that you have some general guidelines to convert the code of your Rules into Actions, let's take a look at some examples.

### Adding custom claims to a token

One of the most common use cases for Rules is the ability to add custom claims to a token, either an ID token or an access token. For example, the following code snippet shows a Rule adding two custom claims to the ID token:

```javascript
function myRule(user, context, callback) {
  const namespace = 'https://myapp.example.com/';
  
  context.idToken[namespace + 'favorite_color'] = user.user_metadata.favorite_color;
  context.idToken[namespace + 'preferred_contact'] = user.user_metadata.preferred_contact;
  callback(null, user, context);
}
```

This Rule can be converted into an Action as follows:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://myapp.example.com/';
  
  api.idToken.setCustomClaim(
    `${namespace}/favorite_color`,
    event.user.user_metadata.favorite_color
  );
  
  api.idToken.setCustomClaim(
    `${namespace}/preferred_contact`,
    event.user.user_metadata.preferred_contact
  );
};
```

While the Rule assigns the values directly to the `context.idToken` object, in the Action you have to use the `api.idToken.setCustomClaim()` method. Notice how the invocation of `callback()` disappears in the Action.

### Updating metadata

You can manage users' and applications' metadata using Rules. The following example shows how to store the font size preference in the user's metadata:

```javascript
function myRule(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

The corresponding Action's code looks like the following:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  const userPreferences = event.user.user_metadata.preferences || {};
  
  userPreferences.fontSize = 12;
  
  // persist the user_metadata update
  api.user.setUserMetadata("preferences", userPreferences);
};
```

While the Rule's code needs to access the `auth0.users.updateUserMetadata()` method, which returns a promise, the Action's code just assigns the metadata value by using the `api.user.setUserMetadata()` method. Notice how simplified the Action's code is compared to the Rule's one.

> In Rules, each invocation of `auth0.users.updateUserMetadata()` makes an HTTP request to the [Auth0 Management API](https://auth0.com/docs/api/management/v2). Instead, all the invocations of `api.user.setUserMetadata()` occurring in one or more Actions will result in a single API call at the end of the Actions execution. This contributes to mitigating the risk of [rate limit](https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits) errors.

### Redirecting users

When you need to redirect the user to a different page to complete the login process and then resume authentication, your Rule may look as shown below:

```javascript
function myRule(user, context, callback) {
  if (context.protocol === "redirect-callback") {
    // User was redirected to the /continue endpoint
    user.app_metadata.wasRedirected = true;
    return callback(null, user, context);
  } else if (
    context.protocol === "oauth2-password" ||
    context.protocol === "oauth2-refresh-token" ||
    context.protocol === "oauth2-resource-owner"
  ) {
    // User cannot be redirected
    return callback(null, user, context);
  }

  // User is logging in directly
  if (!user.app_metadata.wasRedirected) {
    context.redirect = {
        url: "https://example.com",
    };
    callback(null, user, context);
  }
}
```

This Rule and any other previous Rule will run twice: before the redirection and on the response. Typically, you need to put the logic for handling the redirection and the response in the same Rule. Also, you need to manually check if the current protocol is eligible for a user redirect.

The conversion of this Rule into an Action becomes as follows:

```javascript
exports.onExecutePostLogin = async (event, api) => {
    if (!event.user.app_metadata.wasRedirected && api.redirect.canRedirect()) {
        api.redirect.sendUserTo("https://example.com");
    }
};

exports.onContinuePostLogin = async (event, api) => {
    api.user.setAppMetadata("wasRedirected", true);
};
```

You have different functions handling the redirection (`onExecutePostLogin()`) and the response (`onContinuePostLogin()`). Also, the burden to check if the current protocol is eligible for a user redirect is assigned to the `api.redirect.canRedirect()` method. Also, notice that Actions use the `api.redirect.sendUserTo()` method to redirect users instead of the `context.redirect` object.

To learn more about [user redirect with Actions, check out the documentation](https://auth0.com/docs/customize/actions/triggers/post-login/redirect-with-actions).

## Plan Your Migration Strategy

At this point, you should have a clearer understanding of the main differences between the code used in Rules and Actions. However, knowing how to translate a Rule into an Action is not the only thing you should care about. You also need to plan a strategy to migrate your code from Rules to Actions in order to avoid issues in the production environment.

Check out [the documentation for guidelines to define your Rules to Actions migration strategy](https://auth0.com/docs/customize/actions/migrate-from-rules-to-actions#complete-the-migration).

## Summary

This article gave you the foundations to set up your migration process from Auth0 Rules to Actions. You learned the main reasons to migrate and the basic differences between coding for Rules and coding for Actions.

A few conversion examples showed you how Actions generally simplify the code. You can find more conversion examples and additional information in [the Auth0 Rules to Actions migration guide](https://auth0.com/docs/customize/actions/migrate-from-rules-to-actions).

Migrating Auth0 Rules to Auth0 Actions

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Senior Developer Advocate

Joey deVilla

Learn how to use Auth0 Actions to redirect users to an announcement web page and back to the application (or just redirect them to Rick Astley’s video).

Use Actions to Show Users an Announcement after Logging in (Or Rickroll Them)

Learn how to customize the user registration experience with Auth0 Actions.

Did you know that you can customize some of the features Auth0 provides? You can do it with Actions. Are you looking for an example? Let me show you how to customize the user experience when they register with an application.

## Auth0 and User Registration

Using Auth0 to secure your application offers a lot of simplification right from the user's initial visual impression: the login page. The [Auth0 Universal Login](https://auth0.com/docs/login/universal-login) page not only relieves you of the burden of authenticating users but also of the task of managing their self-registration. In fact, in the default configuration, if the user doesn't have an account to access your application, they have the opportunity to register themselves through the *Sign up* link highlighted in the following picture:

![Auth0 Universal Login page with user registration](https://images.ctfassets.net/23aumh6u8s0i/6VizfIqgyfJkvIBtrOqrYt/f17bdf6d9f3d8f19f0d33cb1f880c9d4/auth0-universal-login-page.png)

Following that link, the user can provide an email address and a password to start the registration and authentication process in no time.

All this happens without any intervention on your side. It's all-inclusive!

## Customize the User Registration Experience

That's pretty fine, but maybe you are wondering how to customize the user registration experience, for example, by sending a custom welcome email message. Say you want to thank the user for registering and make them aware of the terms and conditions for using the application. This is what you are going to learn right in this article!

You will learn that you can extend Auth0 standard flows and customize them for your needs. In particular, you will use [Auth0 Actions](https://auth0.com/docs/actions) to send your welcome email message after the user signs up for your application.

Let's start!

## The Sample Application

For this purpose, you will use a sample application that will let you experience the proposed solution firsthand.

> The sample application you are going to use in this article is built with C# and requires [.NET](https://dotnet.microsoft.com/en-us/download) installed on your machine. However, <u>the user registration customization you are going to implement is independent of your application's specific programming language and framework.</u>

To get that sample application, clone it from GitHub with the following command:

```bash
git clone https://github.com/auth0-blog/acme-aspnet-mvc.git
```

After you download the application, follow the instructions in the [README file](https://github.com/auth0-blog/acme-aspnet-mvc/blob/main/README.md) to configure it in order to use Auth0. Of course, you need an Auth0 account. If you don't have it, <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 get one for free</a>.

> If you want to learn more about how the sample application was built, you can check out [this blog post](https://auth0.com/blog/add-authentication-aspnet-core-mvc).

After configuring the sample application, you can run it with the following command:

```bash
dotnet run
```

Pointing your browser to the [https://localhost:7095/](https://localhost:7095/) address, you should get the following page:

![Sample app home page](https://images.ctfassets.net/23aumh6u8s0i/5yO9ER9JsSrsFGXj5e1w6e/3c4f71b3286b43249d0e89a3e7e44c70/acme-homepage-login.png)

## What Are Auth0 Actions?

As said, you are going to use Auth0 Actions to customize the user registration process.

Auth0 Actions are JavaScript functions running in a Node.js environment executed when specific events happen in some internal Auth0 flows.

For example, you can run one or more Auth0 Actions when a user authenticates or change their password. You can run them before or after the user registers or when you send an SMS to your provider for multi-factor authentication. You can see Actions as event handlers that run when a specific Auth0 event fires. For example, in our specific case, you want to handle the event that fires right after the user registers with Auth0. When this event happens, you want to run your code to send a customized welcome email message. You can imagine this event handling as shown by the following picture:

![Post user registration Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/5RPXK0K8xtuQTljcOSYYFH/5e6705b448cfc558a31533aee1d819ce/post-registration-auth0-action.png)

To implement this behavior, you are going to use the Auth0 Dashboard, which provides you with an editor, a test environment, an integrated deployment environment, and a versioning tool.

You can check out these blog posts for [a quick introduction to Auth0 Actions](https://auth0.com/blog/introducing-auth0-actions/) and how they [compare with the deprecated Rules and Hooks](https://auth0.com/blog/actions-now-generally-available/).

## Implement the Email Sender Action

Let's start implementing our customization. Go to your [Auth0 Dashboard](https://manage.auth0.com/) and select [Library under the Actions item](https://manage.auth0.com/#/actions/library) from the left side menu. You will access a page where all your Actions are located. If you have never created any Actions, the page will appear as in this picture:

![Auth0 Actions Library page](https://images.ctfassets.net/23aumh6u8s0i/3BA4BOqfV2JXCZbcmhMBrA/08201459e1b678f8fef5501e8663ba8e/auth0-actions-library-page.png)

You can create your own Action or install a [third-party Action from the Auth0 Marketplace](https://marketplace.auth0.com/features/actions). In the first case, you will start by clicking the *Build Custom* button, and the resulting Action will be listed in the *Custom* tab. In the second case, you will start by clicking the *+ Add Action* button, selecting one of the ready-to-use available Actions, and the new Action will be listed in the *Installed* tab.

### Create a new Action

For the current project, you will build a custom Action. So, click the *Build Custom* button and fill the pop-up form. You should provide a friendly name for the Action and select the trigger that will run it, i.e., the event you are going to handle with this Action. For our project, you should select the *Post User Registration* trigger, as shown below:

![Create custom Action dialog](https://images.ctfassets.net/23aumh6u8s0i/6TzhULLz688fdjQxJqm8Yb/02a5f3c416c5b4a31c358171308dd0d6/create-custom-action-dialog.png)

Once you click the *Create* button, you enter the Action editor, where you find the following code:

```javascript
exports.onExecutePostUserRegistration = async (event) => {
};
```

This is the JavaScript function that will be executed after the user registers with your application. This function will be exported in the Node.js environment running on the Auth0 side.

As you can see, the function has an `event` parameter, which provides some information about the current running environment. For example, it allows you to access the current user's data, the current request, the tenant, etc. For more details about [the Post User Registration event object, check out the documentation](https://auth0.com/docs/actions/triggers/post-user-registration/event-object).

To go straight to the solution, replace the current code in the Action editor with the following:

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

exports.onExecutePostUserRegistration = async (event) => {
  try {
    axios.post('https://api.sendgrid.com/v3/mail/send',
      {
        personalizations: [{
          to: [{ email: event.user.email }]
        }],
        from: { email: 'no-reply@acme-demo-corporation.com' },
        subject: 'Welcome to ACME Corporation website',
        content: [{
          type: 'text/html',
          value: `Hello ${event.user.name},<br>
          Welcome to our website!<br>
          As an ACME user, you can take advantage of our catalog and services.
          Please, take a look at our <a href="https://acme-demo-corporation.com/terms-and-conditions">terms and conditions</a>.<br>
          <br>          
          Kind regards,<br>
          ACME Corporation<br>`
        }]
      },
      {
        headers: {
          'Authorization': 'Bearer ' + event.secrets.SENDGRID_API_KEY
        }
      }
    );
  } catch (err) {
    console.log(`Error sending email to ${event.user.email}:`, err.message)
  }
};
```

This code uses [Axios](https://axios-http.com/) as the HTTP client that makes requests to the [SendGrid API](https://sendgrid.com/solutions/email-api/) to send your welcome email message.

> The Action implemented in this example uses SendGrid to send emails. Of course, you can adapt the code to use your favorite email provider.

Basically, the Action's code sends an HTTP POST message to SendGrid's `mail/send` endpoint with some data that define the email. To learn more about the specific SendGrid API, check out [the official documentation](https://sendgrid.api-docs.io/v3.0/mail-send/v3-mail-send).

### Configure your Action

Looking at the Action's code, there are a couple of things you should pay attention to:

- You get the user's email and name by accessing `event.user.email` and `event.user.name`, respectively.
- You use the `event.secrets.SENDGRID_API_KEY` property to access the API key required by SendGrid to authorize your requests.

While the user's data are automatically provided by Auth0 through the `event` parameter, you need to manually configure the SendGrid API key as a secret. For this purpose, click the key icon on the left side of the Action editor and then click the *Add Secret* button in the sliding panel that opens. You should get a pop-up window similar to the following:

![Configure Auth0 Action secret](https://images.ctfassets.net/23aumh6u8s0i/7hI5RucTwqPP6XTDBPZEDt/773ed0952c252f848c415e346108c040/configure-auth0-action-secret.png)

Fill the form with `SENDGRID_API_KEY` in the *Key* field and your SendGrid API key in the *Value* field.

To complete the Action configuration, you need to make the Axios library available to the Node.js environment. So, click the cube icon on the left side of the Action editor and then click the *Add Module* button in the sliding panel that opens. This time you should see a pop-up window like the following:

![Add Auth0 Action dependency](https://images.ctfassets.net/23aumh6u8s0i/7clXWV3UNjHqaeNWs36cyq/2966b30f21df9f257db625845c908769/add-auth0-action-dependency.png) 

Fill the form with the `axios` string in the *Name* field. Unless you want to install a specific version of the library, you don't need to specify anything else.

Save your current work by clicking the *Save Draft* button.

### Test your Action

Now your Action is ready to run. However, before putting it into production, it is appropriate to do some tests and make sure that everything works as expected.

Click the triangle icon on the left side of the Action editor. A panel opens with an event instance as shown in the following picture:

![Testing an Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/7fXpzlolnINotm8DRlaQsz/287e377b8184c048c6353764c3e18a62/test-auth0-action.png)

This event object is the argument that will be passed to your Action when you click the *Run* button at the bottom of the test panel. Before running the test, you have the opportunity to modify that event object. For example, you can detect the `user` object within the event and change its `email` property with your personal email address. This way, by running the test, you can  receive the email sent by the Action and verify that it works.

So, change the user's email address in the event object and click the *Run* button. If everything works as it should, you should see a window at the bottom right, as this picture shows:

![Test results of an Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/5y06GPj4vRRMYBiaSXM895/1e3bd365d3c177ff0e773754927f744d/test-result-auth0-action.png)

This new window gives you some feedback on test execution. Of course, your test is successful if you receive the expected email in your mailbox.

### Deploy your Action

So far, your Action lives just in your development environment. You can't still use it in production. To make it available to your Auth0 production environment, you need to deploy it. That is easily achievable by clicking the *Deploy* button above the Action editor.

Separating the development and production environments is crucial, especially when you already have a working Action in production and need to apply some changes. You can apply your changes to the Action and test them in the editor without worrying about breaking the production environment. When you are confident with the changes, you can deploy the new version of the Action to update it in production.

Also, the Action editor keeps track of the various versions of your Action. You can see them by clicking the *Version history* button. You will see the list of your current and previous versions as in the following picture:

![Auth0 Action version history](https://images.ctfassets.net/23aumh6u8s0i/5Yi9izjH5jgVP1zW7VPYQY/5d64d0d6a2733be39956412e9dc474f3/auth0-action-version-history.png)

Through this list, you can inspect the Action's previous versions, and, if needed, you can revert the current version with one of them.

### Add your Action to the Post User Registration Flow

Once deployed, your Action will be available in the *Custom* tab of the [Action's Library page of the Auth0 Dashboard](https://manage.auth0.com/#/actions/library). The next step to achieve the goal stated at the beginning of this article is to make the just-created Action run right after the user registers with your app.

For this purpose, select [*Flows* under the *Actions* item](https://manage.auth0.com/#/actions/flows) from the left side menu of the Auth0 Dashboard. You will see a page showing the possible flows you can configure:

![Auth0 flows](https://images.ctfassets.net/23aumh6u8s0i/2kEyKU7ezUFe8xQjAazjCO/7ee44da12d808eaf393bf8aa409a5397/auth0-flows.png)

For your goal, you will choose the *Post User Registration* flow. You will enter the flow editor, which provides you with a visual diagram of the flow, as in the following picture:

![Auth0 flow editor](https://images.ctfassets.net/23aumh6u8s0i/3NTsE7zdq101rOObLXMjZE/3ca40fe50dcb291d13a88dd2a1ae001e/auth0-flow-editor.png)

On the right side of the editor, you have the list of the available Actions. As with the Library page, you have the Actions classified as *Installed* and *Custom*. You will find your *Send Welcome Message* Action in the *Custom* tab. All you need to do at this point is to drag the *Send Welcome Message* box from the right side of the editor and drop it in the middle of the flow diagram, between the *Start* and the *Complete* node. Your final result will look like the following picture:

![Post user registration Auth0 flow with Action](https://images.ctfassets.net/23aumh6u8s0i/58igmA2MYoMejsd9dAN1Mm/fe160aaddb6913b4736cecc2699be266/post-user-registration-auth0-flow-with-action.png)

Keep in mind that, in general, you can add as many Actions as you need to an Auth0 Flow.

## The New User Registration at Work

Now, everything is ready. Move back to [your sample application](https://localhost:7095/), click the *Login* link on the upper right corner of the page, and click the *Sign up* link in the Auth0 Universal Login page:

![Auth0 Universal Login page with user registration](https://images.ctfassets.net/23aumh6u8s0i/6VizfIqgyfJkvIBtrOqrYt/f17bdf6d9f3d8f19f0d33cb1f880c9d4/auth0-universal-login-page.png)

Create a new user by providing an email and a password. After a minute, you should receive the welcome email message you created in the *Send Welcome Message* Action.

That's all! Now you have the basic knowledge to create your own Auth0 Actions to customize the various Auth0 flows.

## Recap

At the end of this article, I'm sure you learned a lot of things. You learned what Actions are and how to create them to customize your user experience with their registration process. Although this article focused on a specific example of Action, you learned features that are valid for Auth0 Actions in general. For example, you learned how to manage dependencies and store secrets for an Action, test it and deploy it into production, check the Action's version history and possibly revert to a previous version, and add an Action to an Auth0 flow.

By using Auth0 Actions, you will be able to customize the default Auth0 behavior to fulfill your specific needs.

Customize User Registration Experience with Auth0 Actions

Use Auth0 Actions to enable SMS-based MFA with Plivo.

Logging into a website with your username and password is a straightforward way to log in and access your content. You've been doing it for years, you've created several passwords, and it works. Logging in with **just** a password isn't as secure for your users as it used to be. Hackers can steal passwords from one site and use [credential stuffing](https://auth0.com/blog/what-is-credential-stuffing/) to pose as your user and gain access to other sites. It's common for your users to re-use passwords since they have several to remember across all their applications. You can help keep your users' data secure by offering another layer of protection by enabling Multi-factor Authentication (MFA).

> To learn more, read [this guide about MFA and its different methods on the Auth0 blog](https://auth0.com/blog/multifactor-authentication-mfa/).


You've likely experienced MFA in real life. For example, if you start working for a new company, they may ask for your ID card and a birth certificate. Those are two different *factors* of identification. It helps verify you are who you say you are to make sure your paycheck goes to you and lowers the success rate of someone posing as you.

In this blog post, you'll learn how to implement SMS-based MFA with Auth0 Actions and [Plivo](https://www.plivo.com/).

## Prerequisites

- An Auth0 account
- A Plivo account
- A Plivo phone number

If you do not have a Plivo account or an Auth0 account, you can sign up for a [free Plivo account](https://console.plivo.com/accounts/register/) and a <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">free Auth0 account</a>.

If you already have an application created in your Auth0 account, you can skip to [Create Action for MFA](#Create-Action-for-MFA).


## Set up & Configure a React App Application with Auth0

In the Auth0 dashboard, create a new application by clicking on **Applications > Applications > Create Application**. On the next screen, create a name for your application and select **Single Page Web Applications** since you're using a React app. 


![Auth0 Create Application Page](https://images.ctfassets.net/23aumh6u8s0i/7ffrE0TIKPuvwAmyAHETGV/3704b624e8b568fba9288b1c6236872d/auth0-create-application-page.png)


The next screen will ask you, "What technology are you using for your web app?" Select **React**.


![Auth0 Technology Selection Page](https://images.ctfassets.net/23aumh6u8s0i/3Is0KXk07ueIJadkrrHnbl/804f4ad53e8af5b28916481b92778fdc/auth0-technology-selection-page.png)


To get up and running quickly, you can download a sample [React application integrated with Auth0 on GitHub](https://github.com/auth0-samples/auth0-react-samples/tree/master/Sample-01).
Once it is downloaded, type `cd auth0-react-samples` on your terminal, then run `npm install` to install the dependencies.

## Configure Auth0 Credentials

For the authentication flow to work, the project needs your Auth0 domain and client ID. In your code editor, copy the content of `src/auth_config.json.example` into a new file in the same src folder called `auth_config.json`, and replace the values with your own Auth0 application credentials:

```js
{
  "domain": "{YOUR AUTH0 DOMAIN}",
  "clientId": "{YOUR AUTH0 CLIENT ID}",
}
```
You can get the client ID and domain from the settings tab on your new application page.

![Auth0 Application Settings Page](https://images.ctfassets.net/23aumh6u8s0i/1GFtgZeJursgHKHzNXQFVh/7496cb3bc06a7411096386c3109be8ed/auth0-application-settings.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_.

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


## Create Action for MFA

With an application linked to the Auth0 dashboard, you can create an Action that will run globally for all applications in your Auth0 tenant. Actions are functions written in Node.js that you set to run at specific events based on your users' actions. Actions let you write custom code that fits your needs and integrates third-party vendors with Auth0 to work together. This post is going to focus on integrating with Plivo. 

To get started with Actions, you need to add an Action to your library. On the Auth0 dashboard side menu, click **Actions > Library**.

![Auth0 Actions Selection](https://images.ctfassets.net/23aumh6u8s0i/6q9LRH1DvQMiF3mU7t6Wy7/8481bc4376718299a2806a165e49ed56/auth0-action-selection.png)


On the Library Page, click **Add Action**. On the Browse Actions page, search for **Plivo** and click on it. On the next page, click on **Add Integration**.
You'll then be met with a prompt telling you, "Plivo will need access to: Read and share user profile information" if you agree, click **Continue**.

## Access and Add Plivo Credentials

This will bring up a page to enter your Plivo credentials such as Plivo authorization ID, Plivo phone number, and Plivo authorization token. You can find the authorization ID and Token on the Account and Payments section of your Plivo dashboard.

![Plivo Accounts and Payments Page](https://images.ctfassets.net/23aumh6u8s0i/3Dttg4mSQ9R20tnFzsRuVr/01c5fe787a262c6e5793642703785064/plivo-accounts-and-payments.png)

Access your Plivo phone number by clicking on **Phone Numbers** on the left side menu. If you don't have a Plivo phone number, you can rent one [following these instructions on the Plivo Docs](https://www.plivo.com/docs/numbers/guides/buy-a-number/).

> Make sure you add the phone number in the E.164 format(ex. +15554443232)

Then click **Create**, and you'll go to the Library page. You can create an Action Flow from here. You'll learn how to use flows next.

## Create Send Phone Message Flow

You should now see the Plivo Action on the installed tab of the Library page. Click the three dot menu on the right and select **Add to flow**. 

![Actions Library Page](https://images.ctfassets.net/23aumh6u8s0i/5IbEG0QKPAbyIoi9buA2NL/ba6df3e83c1cc498b248eafd48fc5362/auth0-add-to-flow.png)


This will take you directly to the **Send Phone Message** flow. Flows are the steps your application takes when using Auth0 as your identity provider. You'll see the **Start** and **Complete** trigger points in the flow in Action flow visualizer in the middle of the screen. On the ride side of the screen, you'll see the **Add Action** section. This will show a list of installed Actions like the Plivo one we created, and there is also a tab for custom Actions.

![Auth0 Actions Visualizer](https://images.ctfassets.net/23aumh6u8s0i/ITasqHfe5OIyRImhGGxis/0a125823cda2f4ee84c2f19d5f6b97ae/auth0-actions-flow-visualizer.png)

You can drag and drop the Actions to the point in the flow that you want them to trigger. Grab the Plivo Action and drop it in between **Start** and **Complete**, then click **Apply**.

![Auth0 Actions Flow Visulizer](https://images.ctfassets.net/23aumh6u8s0i/YYUxv5wmVMjjcFA6ictqN/0683342bf45d6a9e0661e7cbd0febd7e/auth0-actions-added.png)

Now, when an SMS message is requested, your application will signal Pilvo to send an SMS message. But how do you trigger the message request? You have to turn on SMS-based Multi-factor Authentication.

## Turn on MFA in Auth0 Dashboard

On the left side menu in the Auth0 dashboard, click **Security > Multi-factor Auth**. 

![Auth0 MFA page](https://images.ctfassets.net/23aumh6u8s0i/4UUXYlr7UjlSqt3mxPoyrq/17d0e5470369da629062de484fb59862/auth0-mfa-page.png)


In the **Factors** section, scroll down and click **Phone Message**. Click the toggle on the upper right side of the screen to enable Phone Message. With this turned on, it requests a phone message be sent to your users with a code to verify their login. 

Under **Choose a delivery provider**, select **Custom**, since you created the Plivo "Send Phone Message" hook to handle sending an SMS to users. For **Choose a delivery method**, choose **SMS**. 


![Auth0 Phone Message Screen](https://images.ctfassets.net/23aumh6u8s0i/3lfkktB82h2DkLrnl8OCBy/1fa9fb6ec90eb3519b6cc48546cbaeae/auth0-phone-message-screen.png)


Scroll to the bottom of the page and click **Save** to save these settings.

Return to the **Multi-factor Authentication** page and scroll down to the **Define policies** section. This section tells Auth0 when you want the Phone Message MFA request to trigger. For this example, select **Always** to ensure your users have an extra layer of protection each time they log in. Then click **Save**.

You will then be asked, "Are you sure you want to continue?" This prompt also lets you know that all users will be required to enroll in MFA and that all applications in your Auth0 tenant will now use MFA. Click **Continue**. 

You have everything set up to require your users to receive an SMS message with a verification code from Plivo after logging in. But it's always a good idea to test out new features after you add them.

## Test Your MFA Login Flow

Run your sample application locally by launching the `npm run dev` command in the project's root folder. Then, head your browser to the [http://localhost:3000](http://localhost:3000) address and click **Login** on the home page. On the login page, 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 revieve an SMS message with a verification code. Enter that code into the input box on your application.

You've successfully added another factor of protection for your users!

## Test MFA flow in Auth0 Dashboard

Another way you can test the MFA flow is by using the Auth0 dashboard. You can test Actions you created without having to run your entire application.

Click **Getting Started** at the top of the left menu on the Auth0 dashboard. You'll go to the **Getting Started** page, where you'll see the option to **Try your Login box**. Clicking **Try it out** will bring you to the login box that your app will use. 

![Auth0 Dashboard Getting Started page](https://images.ctfassets.net/23aumh6u8s0i/6x1ti069gOiQQEfKMxJOkA/1a574fcaa21a63c27af49c46f945ac5d/auth0-try-login-box.png)

Log in as one of the users in your tenant (If you don't have any users, click **Sign up**).

Once logged in, you'll be asked to provide a phone number. Enter the number for your mobile phone. You'll receive an SMS message from your Plivo phone number with a six-digit code. Enter this code into the Auth0 login box and click **Continue**. You'll be greeted with the **It Works** page, confirming that your MFA Action worked!

![Auth0 It Works web page](https://images.ctfassets.net/23aumh6u8s0i/2TPUwfu11Te9Yb27M3920C/34f3bc3c726eeb0b76cc971c7fd1f5c3/auth0-it-works-screen.png)

## Conclusion

Congrats! You just added another layer of protection to keep your users' data safe. First, you included the Plivo integration from Actions Library. You then created a "Send Phone Message" flow using the Plivo integration and the Actions drag and drop interface. After that, you enabled the Action by turning on MFA in the Auth0 dashboard. Finally, you tested everything out using "Try your Login box" in the Auth0 dashboard.


"auth0-actions"