A technical overview of the Auth0 login flow

In recent years, Auth0 has become a very popular authentication system. It avoids the costs of building a login system from scratch, and allows developers to focus on writing application code. Out of the box, it supports multiple login methods including social login with OAuth2 (Google, Facebook, etc), and username/password. If configured correctly, it is secure, flexible and can simplify your application design.

Auth0's Complexity

But integrating with an external login provider actually turns traditional authentication on its head. It relies on cryptographic signatures and quite an involved authentication handshake. Auth0 has built SDKs for popular programming languages which manage the complexity of this flow. This makes it possible to integrate with Auth0 without understanding how it works. Many developers set up Auth0 hoping to simplify their lives, only to find that they have no idea what's happening when things get more complex.

This blog post explains the OpenId Connect handshake that happens between your user, Auth0s SDK running in your application, and Auth0s authorization servers. It's nothing new, but just focuses on the minimum required to understand the default Auth0 login flow.

Key Concepts

Before getting into the login flow, let's define some terminology:

• Client/Application: This is your app that requires authentication, including the Auth0 SDK libraries you've installed.

• User: The person who is trying to access your application.

• Identity Provider (IdP): The service that authenticates the user. This might be a social login provider (Google, Facebook), or the username/password database

• JWT (JSON Web Token): A signed token used to prove authentication and identity claims. Auth0 issues JWTs after successful authentication. JWT Spec.

• OpenId Connect: The standard that describes this login flow. It has many variations but the default for most applications that integrate with Auth0 is the "code" variation.

The Auth0 Login Flow

The login flow involves several steps, which can vary slightly depending on the specific authentication method used. Here's a high-level overview of a typical OAuth authorization code flow with Auth0:

1. User Initiates Login: The user clicks the "Login" button in your app.

2. Redirect to Auth0: Your app redirects the user to Auth0's `/authorize` endpoint.

3. User Authenticates: The user logs in using one of the available identity providers. The Application doesn't need to know the details of how the different identity providers work with Auth0.

4. Auth0 Redirects Back with Authorization Code: Upon successful authentication, Auth0 redirects the user back to a `/callback` URL in your application with an authorization code

5. Exchange Authorization Code for JWTs: Your app's backend calls Auth0's `/token` endpoint and exchanges the authorization code for an access_token and id_token.

6. Access Protected Resources: Your app uses the access token to call protected APIs and the ID token to get user information.

This is an illustration from the Auth0 site

Let's break down each step in detail.

Step-by-Step Breakdown

Step 1: User Initiates Login

The process begins when a user tries to access a protected resource or explicitly clicks a login button in your application.

Step 2: Redirect to Auth0

You redirect the user to the Auth0 /authorization endpoint. This URL includes several query parameters:

• client_id: Your Auth0 application's Client ID.

• redirect_uri: The URL to which Auth0 will redirect the user after authentication.

• response_type: The type of response you expect (e.g., `code` for authorization code flow).

• scope: The level of access being requested (e.g., openid profile email).

• state: A unique string to prevent replay attacks.

Example redirect URL:

https://YOUR_DOMAIN.auth0.com/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL&scope=openid%20profile%20email&state=YOUR_UNIQUE_STATE

Step 3: User Authenticates

Auth0 presents the user with a login page. Depending on your configuration, the user can log in using various identity providers (e.g., Google, Facebook, username/password). Part of the value of Auth0 is that it provides multiple login providers out of the box.

Step 4: Auth0 Redirects Back

Auth0 redirects the user back to your application using the redirect_uri provided in the initial request. The redirect URL includes the authorization code and a unique state param.

Example callback URL:

https://YOUR_APP.io/callback?code=AUTHORIZATION_CODE&state=NONCE

Step 5: Exchange Authorization Code

Your application now needs to exchange the authorization code for an access_token and id_token. This is done by making a POST request to Auth0's token endpoint.

e.g.

POST https://YOUR_DOMAIN.auth0.com/oauth/token
content-type: application/json
{
  "grant_type" : "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope": "openid profile email",
  "redirect_uri": "https://YOUR_APP.io/REDIRECT_URI"
}

Auth0 responds with a JSON object containing the access_token, id_token, and other information.

{ 
  "access_token": "...",
  "expires_in": 360000,
  "id_token": "...",
  "scope": "openid profile email",
  "token_type": "Bearer"
}

Step 6: Accessing Protected Resources

Once you have the tokens, the user is logged in to your app. The access_token is used to call APIs, while the id_token contains signed user information (such as name, email) that you can use within your app.

Next things to explore:

Probably the easiest way to explore Auth0's APIs and develop a deep understanding is to set up a test account and install their HTTP debugger extension. This allows you to explore the API flows described in their API documentation.

Conclusion

The benefits of Auth0 are that it speeds up and simplifies your application development, and it makes the resulting login system more secure than what you might have built yourself. But if you don't have a good understanding the underlying OpenId Connect flow, you may end up making your application more complex, slow down development, and make your application less secure due to misconfiguration.

The pre built SDKs that Auth0 offers can make integration seem simpler than it really is. Hopefully by understanding what's going on under the hood, Auth0 becomes a well integrated part of your solution and not just a black box that noone wants to touch.

The next thing I want to explore in some depth is the tokens which are used to control access and share secure information once the user is logged in.