Auth0 badgeAuth0 University

Getting Started with the lock

Getting Started with the lock

  1. Course Catalog
  2. Getting Started with the lock
  3. How to use Auth0's Rules feature

How to use Auth0's Rules feature

Auth0 provides a simple way to customize the login process with a feature we call Rules. Rules are code snippets written in JavaScript that run on Auth0's servers. These customizable code snippets can be tailored to handle your specific requirements. The Rules you decide to use can do unique things. For example, you could limit logins to people located within a certain geographic region by using the geolocation information Auth0 provides for the user. You could add additional information to a user's profile such as setting the user's security roles. You could record a login even with a third-party service and much more.

Let's look at how easy it is to add custom rules to your login process. Let's say we'd like to add a specific user to the admin role when thy log in based on their email address. This is easily accomplished by creating a custom rule in the Auth0 dashboard. To do this, we'll click the "Rules" link in the menu and then the "create your first rule" button. When you start a new rule, you'll be prompted to either pick an empty rule, allowing you to build the rule from scratch or choose one of the existing templates that you can then adapt to suit your needs.

Let's pick the "set roles to a user" template found under the "Access Control" heading. A role just to function must pass three parameters. The first parameter is the user object as it comes from the identity provider. The second parameter is the context object which contains information about the current login attempt such as whether it was done from a mobile device and which application the user is trying to log in. The last parameter is the callback function that must be called from within the rule to indicate either success or an error. If there's an error, that error will get shown to the user in lock. The Auth0 login box.

This template has a function assigned to the variable "add roles to user" which we can modify to meet our specific requirements. The way the template is written, it will simply check the email address of the user and assign roles based on their email address. However, keep in mind you could easily change this to query one of your databases or make an API call to an external server as needed. For now, we'll keep it simple and just modify the conditional logic to check the email address So now when Arthur logs in, he'll be assigned the admin role, but all other users will be assigned the user role.

We can manually test this by clicking the "try this rule" button. Before running the test, you can modify the user and context objects that will be passed to our new rule as test data. Let's plug this user's user ID and email into user object to set up our test data, then we'll click the "try" button. And as you can see in the output area, the admin role is assigned to the user's profile.

The next question you probably have have is, Where in my application can I access the user's assigned roles? This is made available by default in the user's profile that's provided by Auth0 after a successful login. To show this to you, I'll use this simple application I created in the "create your first app screen cast." I'll make one small modification to the app, logging the user's profile to the console so we can inspect it. Now let's save the file, open this app in the browser and log in.

Next, we'll look at the console in the Chrome developer tools, and as you can see, the assigned roles are included in the user's profile. Let's add another rule to send a sign in event to Mixpanel, a third-party analytic platform. We'll head back over to the "Rules" area of the Auth0 dashboard and we'll click the "new rule" button, but this time we'll use the tracks login events template under the "webhooks" heading. Now, we'll simply add our Mixpanel-provided token into the rule. Next, we'll try it out. Now let's look at the Mixpanel admin area under the "live view" section. And as you can see, we have a sign in event.

One of the benefits of using rules to trigger events like the one we just set up is improved reporting accuracy. The reason being server-triggered events complete with a high degree of confidence, whereas clients side initiated events which are commonly used fail much more frequently due to outside factors such as blocking firewalls, browser extensions or client side code errors.

I'll try this with a web app we used a few moments ago, but I'll place our web app and Mixpanel on the screen side by side so we can see the event logged in Mixpanel in real time when I log in. I'll refresh the page, log in again, and over in Mixpanel you'll see a new sign in event show up. And as you can see, rules are a great way to extend Auth0's login process to suit your specific needs, and they're easy to create with many ready-to-use templates.