Auth0, in short, is "authentication-as-a-service". When building an app or service, you let Auth0 handle the user registration, login, password resets etc. Alongside Auth0 taking care of those nitty-gritties, Auth0 also lets you quite easily add social logins, RBAC (Role-Based-ACcess) and permission management amongst other features.

Auth0 has a mountain of documentation and a vast trove of tutorials available. The very first time used Nest.js (and Auth0) it was according to one of their tutorials.

Auth0 are also the people behind the site jwt.io, which is incredibly useful for examining your JWTs (JSON Web Tokens) quickly and easily.

Despite all of this, while working with Auth0, it took me a while to get a handle on some of their documentation. My feeling is that, at times, they are quite verbose, and technical, but not "plain spoken". To me, they don't call a spade a spade. This lead to some confusion in understanding how to implement their "Auth0-risation".

What follows is my attempt to explain two of the primary Auth0 concepts in plain language.

When working with the Auth0 JS client, at least in my case, it is imperative to understand two things:

1. Not All Tokens Are The Same!

If Auth0 is talking about responseType, the main two types are:

• id token: This gives you the "user profile". Typically, this is what you would use with a SPA (single page application) where your "backend" is part of the same application or monolith. Critically, id token does NOT give you permissions in the JWT!
• token: This actually means access_token (Why did they not name it 'access token'?). If what you want to see permissions directly in your JWT - this is what you want! Also, you will NOT get personal details in this token. Generally, this is what you use when authorising access to API endpoints where you API is NOT part of the monolith. i.e. Your API is going to be consumed by multiple applications.

Note: Keep in mind, I am speaking broadly. In my case, I am working on a single application, served on one URL, but in fact, the client and the API are "microservices". While they "appear" as the same application, they are in fact separate apps. Similarly, I suppose there are ways to get permissions using id tokens. They just do not appear directly in the JWT as far as I have seen.

2. Custom Login Flow or Not?

It is not at all clear to me whether you can actually have a "custom designed login page/flow" using Auth0. Auth0 says that you can, and they have "examples" of this. However, I would argue that the documentation of the Authentication API contradicts this.

Now, before we begin, I need to explain what I mean when saying "custom designed login/flow". Effectively, what I mean is: The app will have a custom designed login page using "email" and "password" to login. At no point will the Auth0 "Lock" UI appear (Auth0 Lock is the Auth0 login UI). And at no point, will the user see anything that indicates Auth0 is being used.

With that out of the way, Auth0 basically says that if you do not want to use the "Lock UI", then you need to use the one of Auth0's APIs.

The crux of the Auth0 wording is this (emphasis added):

"With Auth0's library for Web, you can customize the behavior and flow of the process used to trigger signup and authentication. You can also directly use the Authentication API, without any wrapper at all, if you so choose."

Auth0 has two primary APIs. I would summarise them as follows:

1. Authentication API: The "Authentication API" for public-facing user login, registration etc.
2. Management API: The "Management API" is more for "internal" or "team" applications and lets you manage your Auth0 account.

In my case, I want to register and login everyday, public users. As the Auth0 documentation quote above indicates, if I want "custom ui" the "Authentication API" is what I need.

In order to implement a "custom" UI for my login - which I want to be done via email and password only. The Authentication API has 3 options for login.

1. Social - Google, Facebook, Twitter etc. There are a myriad of social providers.
2. Database/AD/LDAP (Passive) - This is your username/password or email/password combination.
3. Enterprise (SAML and Others) - Windows Azure Active Directory or similar.

Option 2 it is!

As such, to log a user in, the API endpoint I need is /authorize. The description of which says the following:

"Use this endpoint for browser based (passive) authentication. It returns a 302 redirect to the Auth0 Login Page that will show the Login Widget where the user can login with email and password."

Let's rewind. So, as Auth0 has told me, ff I want to create a "custom design login page" (as I have defined it), I need to use the "Authentication API", of which I need to use the /authorize endpoint, which, as described: "returns a 302 redirect the AUTH0 Login Page".

Custom? No...

To me, that is NOT what I am looking for when wanting a "custom designed login/flow". I suppose that technically, the "page" can be custom designed, but it still goes to the Auth0 page!

Going to an Auth0 branded page seems to defeat the entire purpose of having a custom UI! Why go to all the effort to make it custom when it goes to Auth0 anyway?

If I have misunderstood or misrepresented any of the above, please let me know. I am always eager to learn.