A Guide for an Awesome Custom Auth0 Universal login
- Share:
Your login and sign-up screens are the gateway to your app - the first thing a person sees before entering your actual application. So, they better look amazing, if you want an awesome app.
While creating our own login screen at Permit.io, I had to review and collect data from multiple different guides, so I finally decided to incorporate them into one unified guide that will help you transform your own login screen completely.
In this guide, we will cover:
Using Auth0 authentication has its advantages - It’s fast, secure, and highly functional.
That being said, you can’t have the first thing your user sees when entering your app look like this:
5 reasons why you should customize the default Auth0 login -
While functional, using the default Auth0 login screen has some key issues:
While the login / sign-up screen is a crucial step in a user’s onboarding process, the default Auth0 login screen lacks some important elements - The company name is there, but the overall look is different. This makes the login screen seem like a foreign entity inside your application. And that’s not a good user experience.
The default option Auth0 provides in login through an external domain that belongs to Auth0, meaning each time someone wants to log in to use your application they are redirected to a domain outside that of your company. Your users might have no idea what Auth0 is, or why they are referred to this external website to provide their login information. This looks both unprofessional and unsecure.
This sense of unfamiliarity creates another issue: because the login screen doesn’t look like the rest of your company’s user interface, and it is based on a domain outside your company, it can be easily interpreted by the user as a phishing attack.
The message displayed reads: “Log in to ‘Company Name’ to continue to ‘Application Name’”. Not only is this not the most inviting message, changing it is no trivial task (As we will see later on).
The login interface uses only a small percentage of your screen, the rest of it being just one color, making it look quite dull and uninviting on one of the most important screens in your entire app.
While the good news is that most of these features are customizable, the bad news is that implementing these customizations is no easy feat, and far from intuitive. Hence this guide 😉
What can we do about this?
Overcoming these issues took me a while, but we were very pleased with the end result:
So how did we get here? Let’s review the steps:
1. Enabling custom domains
As we have stated before, having your login/signup based in a domain outside your company creates various issues. Apart from that, Auth0 only allows you to customize your login screen by using a custom domain - which is a paid feature.
To do this -
Choose the correct tenant (most likely production).
In the left sidebar go to Branding > Custom Domains.
(If you haven’t upgraded your plan to include custom domain support, you will need to do that first).
- Approve your custom domain through the instructions provided by Auth0 to prove that you actually own it (This includes adding some TXT entries to the domain).
This is what an approved custom domain should look like (notice the ready status):
2. Editing the login template
Now that we have a custom domain, we can get to editing the login screen itself.
If you check out Auth0’s documentation you will notice they suggest using POST requests to update the template. This means posting all of the code for the entire page every time we want to make the smallest of changes. That can be a huge hassle.
To overcome this issue, I used Auth0 CLI (That’s still in beta, but works *almost* perfectly) which utilizes Storybook. Auth0 CLI allows you to edit the login template from your code editor while previewing those changes in Storybook as you go along.
How to do this:
Download Auth0 CLI:
On Mac:[brew tap auth0/auth0-cli && brew install auth0]On Linux:
[brew tap auth0/auth0-cli && brew install auth0]On windows (With Scoop):
[scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git scoop install auth0]Check this link for more options.
Login to your account using the following command:
auth0 loginRun the following command:
auth0 universal-login templates updateThis will open your default code editor (I recommend setting VSCode as your default editor), and a Storybook window in your browser, previewing the current state of your login screen.
When you make changes in your code editor, you see them updated live in the Storybook preview window.
This is how the StoryBook preview looks like
Remember to add
{%- auth0:head -%}in the HTML head tag
and{%- auth0:widget -%}where you want the Auth0 widget to be injected.
This is an example of a basic template that displays the Auth0 login:html <!DOCTYPE html><html> <head> {%- auth0:head -%} </head> <body> {%- auth0:widget -%} </body></html>When you close the editor, Auth0 CLI will ask you if you want to update the login template.
- Approve, and you’re done!
Important note:
The authentication widget previewed on Storybook is not identical to the actual one that is going to appear on your website. These could also display a bit differently on mobile/different screens - so make sure to recheck everything in your real environment after updating your template.
Note the Storybook preview (Left) vs. the actual version (right).
3. Editing Auth0 widget default title and description
In this part, I’ll explain how to change the default text templates provided in the Auth0 login screen through API management. The default text will look like this:
Log in to `Company Name’ to continue to ‘Application Name’
To do this:
First, you will need to get your API management token: Go to Applications > APIs, click on Auth0 Management API. Go to the API Explorer tag, and copy the token by clicking the copy icon on the right.
Go to the Auth0 “prompt: login” Documentation, and get the names of the strings you want to change. For example, the key for the following login screen string:
Log in to ${companyName} to continue to ${clientName}
Isdescription.Go to “Set custom text for a specific prompt” in Auth0’s API management docs.
On the top left side of the screen, click “Set API Token”, and paste the API token you copied.
- Select the prompt you would like to make changes to (in our case: login)
Select the language (in our case: EN - English)
Under “body” - add all of the changes you wish to make in this prompt (in our case: description and title)
NOTE: If you want to change more than one prompt, you have to make both changes first, and then save them together. If you do them separately the first will revert to its original state.
Click TRY to save your changes.
You may want to repeat this process to edit your signup widget as well. To do this, locate the text you want to change here, and repeat the process while choosing signup instead of login
in all the steps.
4. Things you cannot do with Auth0 universal login
As of the writing of this guide, a feature to change the login widget to request the user to repeat the password on signup is not yet available. A GitHub issue for this has been open since 2014, yet no relevant action was taken.
I hope this guide enabled you to set up your own authentication via Auth0.
Usually, once you have authentication set up, the next step is to do authorization!
Check this guide to adding RBAC authorization to Auth0, or go to Permit.io to learn more about getting permissions as a service.
Got any other questions about Authentication or Authorization? Join our Slack Community!
You can check out our own template on GitHub.
Written by
Oded Ben David
First Developer @ Permit.io; building your next permissions solution
