Auth0 and Custom Rules
Several months ago I was tasked with writing some custom rules in Auth0. This post is an overview of how I did it, the challenges, and the things I learned along the way. I also have other information available about the Auth0 deploy-cli and a sample of a tenant configuration yaml file.
The Task
The company I was working for uses Auth0 as an identity provider for a third party application that they license to customers. It is important to note that not having control of the application or the ability to change it’s source code requires some workarounds. The task I was assigned was to write a custom rule for password expiration.
The Conditions
- When a user logs in 90 days or more since their last password reset they are given a message that their password has passed expiration and will only work for 72 more hours.
- The user is also emailed a password reset link.
- Once the user logs in again after the 72 hour period they are kicked off and they can not log in again until they reset their password.
The task seems simple enough but without any previous Auth0 experience I ran into several tricky spots that required a lot of reading documentation and forums. I hope I can save someone else some time by providing some answers here. As I previously stated I could not make any changes to the third party application so that meant that I had to do everything in the Auth0 rules dashboard.
Using the Auth0 rules dashboard you can create your own custom rules or use one of the pre-made templates. Auth0 rules are hosted on your auth0 tenant and require no provisioning of resources on your part. You just have to write the code. The rules are written in Node.js and each rule acts as a standalone function that accepts a user object, a context object and a callback. They can also have environment variables that can be set before running.
The rules are triggered when a user successfully authenticates and they execute in the same order as you see in your dashboard.
The user object that is passed in has information about the user including the timestamp for the last password reset. This is what I used to determine the age of the password. From there just applying the logic described above is fairly straight forward until it came to actually kicking the user off until they change their password.
I tried using the Auth0 Management API to reset the user’s password and it took me a long time to figure out why it was not working. The Auth0 rules only have a limited access or scope of permissions on the management API by default. If you want to elevate the permissions so that you can access more management API endpoints you need to create a Machine2Machine application in your Auth0 tenant. Your rule can use the application credentials to authenticate with the management API and make use of it’s endpoints.
This sounds much harder than it is and I will take it step by step and provide links to the documentation and screen shots to make it even easier.
- Navigate to the applications page of your Auth0 tenant and click create application. Give it a name, select MachineToMachine application and create.
2. Select the Management API and then decide which permissions you would like your application to have. Mine has fairly wide permissions because it is the rules engine for my entire tenant but as a rule grant as few permissions as possible to complete the task.
3. That’s it for the new application. Now you have a MachineToMachine application. You can use the client id and client secret to exchange for a bearer token. This token can then be used to make requests to the management api.
4. Navigate to the rules page and click create new rule. From here you can either create an empty rule or start with a template. This is what you should see after that.
5. Give your rule a name and start writing your code.
- As a side note, writing code in this horrible little window is the worst. I tried to do it but as my function grew in size I could not keep track of it and you can not expand the window size. You also can not unit test. So I started writing code in my editor and copy + pasting it in. This is bad. Not only do you now have two places to maintain your code, there is room for error and all code should be in source control. There is a solution to this using the deploy-cli tool. I have another post about this and some resources on my github.
6. The below screenshot shows how you can pass encrypted environment variables to your function. These environment variables will be available to all rules so keep that in mind when it comes to least trust principals. And follow other security practices like setting short timeouts for tokens and frequent automated password rotation.
That should give you plenty to get started with Auth0 rules. Look out for other posts and tutorials on Auth0. I will be doing one about the Auth0 deploy-cli and other password rules.
Feel free to reach out if you have any questions or would like to talk about Auth0, AWS, Docker, Hashicorp products, Jenkins, or pretty much all things software engineering.
https://www.linkedin.com/in/terrence-jones-ii/
https://github.com/tjones-commits
