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

This guide shows you how to permit or deny login requests by utilizing deny or allow lists. With step-by-step instructions, you'll create a new Auth0 Action, work with lists, and delegate list management to an external API.

Auth0 provides a robust set of tools and features to enhance authentication and authorization in applications. One such feature is Auth0 Actions, which allows you to customize and extend the behavior of the Auth0 platform. This article will explore using Auth0 Actions to permit or deny login requests based on specific criteria, such as a denied and allowed list.

## Prerequisites

Before diving into the implementation, there are a few prerequisites to ensure you have in place. 

- **Auth0 account.** If you don’t have one already, you can <a href="https://a0.to/blog_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>.
- **Basic JavaScript knowledge**: Auth0 Actions are functions you can program using JavaScript. In this tutorial, I’ll provide you with the examples. However, to further customize them for your use case, it is important to have basic JavaScript knowledge.

## Create a New 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/6Urd7xOI45T2kfVRnSYVfg/2deba4f6affc4cf234e5874d99999ba2/select_the_login_flow.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/7lgp4OyGh5EigXd8W6yZ8n/6c9dd5f1b3a162d8654fd97dcb629369/login_flow_page.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 to even 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 Custom".

![Create a custom Action using the Actions panel](https://images.ctfassets.net/23aumh6u8s0i/4AlGcWH9I7XWxYaG9BGpgt/7bc82776e321c1fe97b3e91a06667439/add_action.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 “Validate User Login”.

![Enter the Action name and click create](https://images.ctfassets.net/23aumh6u8s0i/54faDAu75f8xpX1WjMnblt/717dd9e1d20658fedcc03e8271f64143/create-auth0-action-modal.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/5qe9QL6Iefmin0HFmRyQ5A/376010f5d460bbc7c034ad644f0543e7/auth0-actions-code-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.

## Working with a Deny List

A deny list is a common way to block specific users or IP addresses from logging in. To implement a deny list using Auth0 Actions, you can leverage the context available to the Action's code through the `event` parameter. The `event` object contains information about the incoming authentication request, such as user details and IP address. By accessing this object, you can compare the values against your deny list and take appropriate action just as denying the authentication request.

Before we start writing the code for our deny list, we need to know how to cancel the user’s login request. For that, we make use of the `api` parameter as follows:

```javascript
api.access.deny('reason');
```

With a single line of code, we can deny the login request. The `deny` method expects a single parameter `reason`, which is a human-readable explanation for the rejection.

Now, let’s start updating our function to support a deny list:

```javascript
// Array containing the email addresses that are blocked from logging on.
const denyList = ['myemail@example.com']

exports.onExecutePostLogin = async (event, api) => {
  if (denyList.find(email => email === event.user.email)) {
    api.access.deny("Your email address is blocked from logging in to our systems.");
  }
};
```

In this simple function, we have a hardcoded list of email addresses that are forbidden from logging in to our system, and the `onExecutePostLogin` simply looks if the user’s email address on the login event is in the list. If so, it denies the user’s access.

Once you add the code to the Action’s editor, it’s time for testing, and the best way to do it while in development mode is with the test panel.

You can access the test panel by clicking the play button on the editor’s sidebar, as shown below:

![Access the Auth0 Actions test panel by clicking the play button on the left sidebar](https://images.ctfassets.net/23aumh6u8s0i/5aZkR41jz9C6UjtuZizGCm/26ec7df5b28c78639e4701a1624a2dad/actions-test-panel.png)

Once you expand the panel, you can customize a test event object to your needs; for example, you can look for the `user` object, which contains all user properties such as `given_name`, but more importantly for our use case, `email`.

By clicking the "Run" button at the bottom of the test panel, Auth0 will execute the Action on the given data and output the test results on the test result window. If the given user is not part of our denied list, you’ll see the following test output:

![Auth0 Action’s test result for a successful execution](https://images.ctfassets.net/23aumh6u8s0i/2pX163YMm8dq9OPvbMIXz9/37f82cec86640e560a4bb2fd3543074d/auth0-action-ok-test-result.png)

On the contrary, if you update the event JSON to include one of the denied user email addresses, you’ll receive the following test output:

![Auth0 Action’s test result for a denied request](https://images.ctfassets.net/23aumh6u8s0i/7xGybOaomBF6ghtsP6l0i8/485440622fc08629927fae8eb3b820e8/auth0-action-denied-test-result.png)

Finally, once you complete your testing, you can deploy the function so it is available to add to the login flow.

## Working with an Allow List

On the other hand, an allow list specifies the users or IP addresses that are explicitly permitted to log in. Like working with a deny list, you can access the necessary information using the `event` object. Compare the values against your allow list and proceed with the login flow only if the user or IP address is found on the list. Otherwise, you can deny access by rejecting the authentication request.

Similarly to the deny list, the allow list will use the `deny` method to reject all requests except those from users in the allow list.

Here is the new code:

```javascript
// Array containing the email addresses that are allowed to log in.
const allowList = ['myemail@example.com', 'j+smith@example.com']

exports.onExecutePostLogin = async (event, api) => {
  if (!allowList.find(email => email === event.user.email)) {
    api.access.deny("Your email address is not authorized to log into our systems.");
  }
};```

Running the tests, as previously explained, should give similar results following the corresponding logic.

## Delegate List to an API

If you have many entries in your denied or allowed list, storing and managing the list in an external system, such as a database or an API, might be more practical. With Auth0 Actions, you can delegate the list retrieval and verification to an external API. Within your Action's code, make the necessary API calls to verify the user's status and subsequently reject or allow the authentication request.

For this exercise, we'll assume that you already have an API endpoint that, given a user's email address, will return if the user is authorized to access. Here is an example of what such an API could look like:

```bash
curl https://myaccessapi.com/users/is_authorized?email=myemail@example.com
{
  is_authorized: false
}
```

Given this simple example, let’s update our code:

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

exports.onExecutePostLogin = async (event, api) => {
  const auth_result = await axios.get(`https://myaccessapi.com/users/is_authorized?email=${event.user.email}`)
  if (!auth_result.is_authorized) {
    api.access.deny("Your email address is blocked from logging in to our systems.");
  }
};
```

Note that for calling an API, we are using the `axios` library, which is already available in your Actions environment. If you need access to other dependencies, you can simply add npm dependencies as part of your Actions bundle. You can learn more about dependencies on Actions on the [official documentation](https://auth0.com/docs/customize/actions/manage-dependencies).

## 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/eHb4lOXaXYvG3EdaVt6xM/aed46e987226df5b8ff5d41b03fd882c/apply-action-to-flow.gif)

## Summary

This article explored how to leverage Auth0 Actions to permit or deny login requests. By using a deny list or an allow list, you can enhance the security of your application and control access based on specific criteria. We also discussed delegating the list management to an external API, providing scalability and flexibility. With Auth0 Actions, you have the power to customize the login flow and add an additional layer of security to your application.

The examples I provided throughout the article are a good starting point. However, you can further customize them to meet your needs. For instance, you could use allow/deny lists by domains instead of emails or by IP addresses, country, day and time, etc.

Always thoroughly test your implementation and consider any potential edge cases specific to your application's requirements. By using Auth0 Actions effectively, you can ensure a robust and secure authentication experience for your users.

Thanks for reading!

Permit or Deny Login Requests Using Auth0 Actions

Andrew Whitman

Andrew is a Customer Identity and Access Management specialist at Okta and loves solving complex identity challenges for his customers. His background in mobile application architecture and development has given him the opportunity to keep pace with the rapid changes that have taken place with authentication over the last 10 years.

Senior Solutions Engineer

Extending core identity functions to fit your application’s unique needs

Identity is a complex domain, and beyond a set of foundational functions, every business has unique needs. But with finite resources (likely already stretched thin by other demands), how can developers build custom solutions that extend and integrate with core identity functions?

Or — put another way — how can development teams do more with less?

To help answer that question, we will explore [Okta Customer Identity Cloud (Auth0)](https://www.okta.com/customer-identity/) Redirect Actions capability with progressive profiling and coupon promotions as two example use cases.

## Actions and Actions Integrations

[Actions](https://auth0.com/docs/customize/actions) are secure, tenant-specific, versioned functions written in Node.js that execute at specific points in identity flows. Actions are used to customize and extend Auth0's capabilities with custom logic, providing developers with the versatility needed to achieve [a wide variety of use cases](https://auth0.com/docs/customize/actions/use-cases).

To accelerate your Identity innovations, the [Auth0 Marketplace](https://marketplace.auth0.com/) includes a long (and ever-growing) list of [Actions Integrations](https://marketplace.auth0.com/features/actions) — partner-built solutions that can be quickly added to extend your identity flow with no-code ease. We recommend looking at the Marketplace before embarking on any custom Actions development because there’s a good chance what you need is already waiting for you.

But, as identity continues to evolve, developers will also have new use cases. And we want to illustrate how Actions can do a lot of heavy lifting as you implement new use cases.

![Build Your Own Integration](https://images.ctfassets.net/23aumh6u8s0i/7hXtS4g7a9TUncVFswrY7Y/bb290371ce4bf09eb9682d1f9c339ea1/01_Build_Your_Own_Integration.png)

## Implementing Progressive Profiling with Redirect

[Progressive profiling](https://auth0.com/docs/manage-users/user-accounts/user-profiles/progressive-profiling) is the process of incrementally collecting additional information about your users as they engage with your website or application. For example, you could collect the user's name, email, and password during sign-up, then ask for their company’s name and job title the next time they log in. This bite-sized approach helps you avoid long sign-up forms that can negatively impact the customer experience (or maybe turn them off your service entirely).

Auth0 [introduced progressive profiling flows in 2020](https://auth0.com/blog/progressive-profiling/#Getting-The-Most-From-Your-Progressive-Profile-Funnel), and we’re happy to see this approach used by modern applications more frequently. But the platform has evolved since the feature debuted, so it’s time to revisit some details on setting up progressive profiling with Actions (versus the original implementation using Rules).

More than that, we also want to highlight how the Redirect flow can apply to more than just onboarding users. Or, put another way, the Redirect feature is powerful, and the progressive profiling use case will help us to illustrate some of its capabilities that developers may have overlooked.

### General approach

Redirects occur during login and allow you to take your user to an external page before granting access to the application. This technique can be useful for progressive profiling because, at this point of authentication, the user has already entered their proper credentials, they have a purpose for visiting the site, and they likely have the intrinsic motivation to answer questions presented to them so they can proceed.

The [Redirect with Actions](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/redirect-with-actions) documentation goes over this process in detail and discusses the various ways to pass data with this flow. For our purposes, we will use [the front channel approach](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/redirect-with-actions#send-data-on-the-front-channel) that roughly follows this sequence:

![Front Channel Approach](https://images.ctfassets.net/23aumh6u8s0i/ey2pLXDDxHwWxlgywXv16/5a18cb2bc6c68ed9a4b4f15abbe39bf7/02_Front_Channel_Approach.png)

Within this overall process, the Action flow itself has three main steps:

1. Determining if the Action should execute
2. Preparing, passing, and receiving the data
3. Utilizing the received data

### Action step #1: Determining if the Action should execute

We don’t want to use Redirect every time users access our application, so we need to make sure we have criteria at the start of our Action that will result in it only triggering when appropriate.

The criteria can come in many forms, giving developers precise control over Redirects. Examples include the number of times the user has logged in previously, the last time they received a prompt via a redirect, or the current state of their profile information. 

### Action step #2: Preparing, passing, and receiving the data

To ensure data is exchanged securely with our Redirect application, we first pass over an auto-generated state value and a signed JSON Web Token (JWT).

The signed JWT will use a shared secret to allow the Action to send over additional context to the URL and for the URL to do the same with the data the user has entered. 

### Action step #3: Utilizing the received data

When the user has finished interacting with the Redirect application and is brought back to complete their authentication journey, the Auth0 Action will first validate the state value and inspect the signed JWT.

If everything is valid, the Action can use the newly received data to update the user profile. Next, the Action can determine and flag if additional Redirects are required, after which the login flow proceeds to the next Action or completes the authentication.

### The user experience

Actions can be used to implement anything from simple flows to extraordinarily complex ones, but any complexity takes place behind the scenes. Here’s what the three-step flow above looks like to the end user.

![End User View](https://images.ctfassets.net/23aumh6u8s0i/1eBVWkKnfJ4d6KXv7d5HDY/021339a816c968f0ae2aab672b5b5237/03_End_User_View.png)

### Redirects to improve cart transactions

In addition to acquiring customer information and preferences, e-commerce sites can also utilize Redirect to help drive conversions — for example, by adding a coupon incentive when a user logs in for the first time and verifies their email.

Since Actions has context on the authenticating user and session, we can redirect to additional pages (e.g., a coupon code alert) to ensure the user is aware of the promotion and to encourage them to complete their first transaction.

And importantly, Actions can store (within a user’s profile) data that is exchanged during these Redirects, enabling other applications functions to interact with it. 

![Redirect end user](https://images.ctfassets.net/23aumh6u8s0i/TRrNbjiSqOljtxBFXKuWx/92f1ab43e68132302d42426514c9bf0b/04_Redirect_end_user.png)

## Let’s Dive In

Now, let’s build our own Redirect Action in our tenant.

This demo requires the following:

1. An Auth0 tenant (sign up and create one [here](https://manage.auth0.com/))
2. A remixed copy of [this Glitch App](https://glitch.com/edit/#!/okta-cic-pp-demo)
3. The following [Login Action code](https://github.com/awhitmana0/cic-redirect-actions/blob/main/redirect-intro-profile-data.js):

![action_example_1](https://images.ctfassets.net/23aumh6u8s0i/3aKYVGUzqjj3gIYehtsHS6/199a048f76b63a0010504693ba0b98b1/05_action_example_1.png)

### Instructions

1. Go to [**https://glitch.com/edit/#!/okta-cic-redirect-actions**](https://glitch.com/edit/#!/okta-cic-redirect-actions) and remix the app. Copy your remixed URL so we can add it to our Action.

![glitch-url-example](https://images.ctfassets.net/23aumh6u8s0i/iCyB2jcLxxgUOxTO7ABiM/9b5204fd30f2d581804607126908ec48/06_glitch-url-example.png)

2. We will use environment variables to configure this template to work with our application. 
 1. **Shared secret**: You will need to generate your own secured shared secret that only your app and tenant can access. Generate a string for `APP_SECRET_KEY` using openssl rand -hex 32 from your shell.
Take note of this value so we can add that to our Action and redirect page.
 2. **Auth0 Application domain, secret, client ID**: These can be found in your Auth0 tenant settings and will be set under `AUTH0_DOMAIN`, `AUTH0_CLIENT_SECRET`, `AUTH0_CLIENT_ID` respectively.
(Note: If you are linking from an existing app, you can ignore this step.)

![Glitch Environment Variables](https://images.ctfassets.net/23aumh6u8s0i/42UMb4cNEmrJrxTALZhFmJ/dde8474c199605a7fc9c4d910cd42540/07_Glitch_Environment_Variables_.png)

3. Copy the Action code from the starting section.
4. Create a new custom [login flow](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow) Action in your Auth0 tenant.
5. Paste the code copied in step 3 into your new login flow Action.
6. [Create two new secrets](https://auth0.com/docs/customize/actions/write-your-first-action#add-a-secret): `FORM_URL` and `SESSION_TOKEN_SECRET`. <br>
Set `FORM_URL` = `https://NEW-GLITCH-URL/prog/universal` <br>
Set `SESSION_TOKEN_SECRET` = secret created in step 2a <br>
7. Save and deploy the Action and add it to your login flow.
8. COMPLETE: Test your new login Redirect flow by signing up a new user!

## Extending the Flow: Checking Marketing Preferences

Since Actions are composed of code, we can build more complex use cases in our Auth0 environment.

This sample Action is set up to be extremely flexible and to let the receiving URL act as an empty vessel to display forms, and the configuration and theming of the page can all occur within the Action itself. In practical terms, this means that you can use the same URL with multiple different Actions to achieve different functionality.

For example, by slightly modifying the original Action, we can easily create a “marketing preferences check” that only triggers on the third login:

![Marketing permissions check](https://images.ctfassets.net/23aumh6u8s0i/ylYXM36ZyCWJXNOm1nfy0/8d9a06472cbafb2f157d87d4f234d2fb/08_Marketing_permissions_check_.png)

Use the [following Action code](https://github.com/awhitmana0/cic-redirect-actions/blob/main/redirect-marketing-consent.js).

![action_example_2](https://images.ctfassets.net/23aumh6u8s0i/4a3A2QV5JlY129nSA5FqJ7/8e794621354a1bd90e8c34255634aa9f/09_action_example_2.png)

<include src="Vidyard" id="iHp52FNwzSGRQGpW4pnFLb" />

## Only the Beginning...

The examples above represent only a fraction of what’s possible, as the Redirect capability can enable much more functionality that you may wish to leverage during a user’s authentication flow. For example, the same pattern can be used to:

* Require Identity proofing;
* Implement consent management;
* Integrate with customer data platforms;
* Trigger MFA protections; and
* Enable Web3 and decentralized identity
* Plugin data to the underlying connected system
* Prevent fraudulent user access
* Enrich uUser profiles
* and more

And Redirects are themselves only a small part of the larger set of Actions capabilities. Auth0 Actions open a large possibility of very sophisticated identity workflows that can be powered, hosted, and protected by Auth0. In addition, Auth0 Actions help to achieve many possible use cases throughout the sign-in flow; before, during, and after sign-in.

By design, the Auth0 platform is built so you can use Actions to solve a variety of problems that are unique — whether broadly or in the smallest details — to you.

Identity as a domain may be hard, but extending the Customer Identity Cloud’s core functions to meet your application’s specific needs is easy.

## Integrate with Auth0

Learn everything you need to know about our extensibility features, build your own solution, plus understand the process all the way to publishing. We’ve got you covered with helpful docs and resources. Visit [auth0.com/integrate](http://auth0.com/integrate) to learn more.

"demos"