About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
Tutorial
Building a JWT Login Flow with Auth0, Next.js, and GraphQL
Learn how to implement a robust JWT login flow using Auth0, Next.js, and GraphQL to enhance security in your frontend applications.
On this page
In the realm of frontend applications, robust authentication is a fundamental requirement. In this tutorial, learn how to build a JWT-based login flow using a combination of Auth0, Next.js, and GraphQL. Auth0, a leading authentication provider, offers versatile authentication methods, such as social login, passwordless login, and more, making it an ideal choice for securing your application. For the GraphQL implementation we'll be using IBM API Connect Essentials, a tool to declaratively build and deploy GraphQL APIs for any data source.
To simplify the integration with Next.js, you can use the Auth0 Next.js authentication library, known as nextjs-auth0
. This library, maintained by Auth0, streamlines the authentication process, ensuring a seamless experience for both developers and users.
You can access the full source code for this tutorial on our GitHub repository.
Understanding the login flow
The login process is based on OAuth 2.0, specifically utilizing the Authorization code grant flow. This flow includes the frontend and backend components of the application to secure user authentication.
- Frontend handling: The frontend application manages the login flow and guides the user to the backend for authentication.
- Backend exchange: The backend server exchanges the authorization code for a JSON Web Token (JWT) and transmits it back to the frontend.
- JWT usage: The frontend application uses the JWT to initiate requests to the backend, thus securing access to protected resources.
To facilitate this process, the frontend application is built using Next.js, with seamless authentication management provided by the nextjs-auth0
library. Users are presented with a user-friendly interface, guiding them to the Auth0 Universal Login page. Here, they can log in using their email and password or opt for the convenience of various social login providers offered by Auth0. After successful login, users are prompted to authorize access to their profile information, which is securely managed by the authorization server.
The backend IBM API Connect Essentials leverages an Auth0 JSON Web Key Set to validate the JWT, ensuring the integrity and security of sensitive data before delivering it to the frontend application.
Step 1. Setting up Auth0 for integration
Configuring Auth0 is a crucial step in the application setup. Learn how to set up Auth0, including creating an Auth0 account, defining an API, and setting up an application:
Create an Auth0 Account by following the instructions in the Auth0 website.
Create an API in Auth0. This API will represent our GraphQL API and allow it to interact with the Auth0 authorization server. Follow these steps in the Auth0 dashboard:
- Click Applications in the navigation pane.
- Next, click APIs link in the same navigation pane.
To create a new API, click + Create API. In the Name field, enter a name to identify this client, such as "My GraphQL API". In the Identifier field, specify a unique value, e.g., "https://my-graphql-api.com".
Click Create to complete the process.
- After this, you'll see a page displaying the
Identifier
andAudience
fields. TheIdentifier
identifies your API when requesting an access token. Make sure to copy these values as you will need them later.
Note: It is important to create this API to avoid Auth0 generating an opaque access token, which can only be validated by Auth0 but not by the GraphQL API.
Create an Application in Auth0. This application will serve as the authorization server for generating access tokens for the GraphQL API. Follow these steps:
- Return to the Applications page in Auth0.
- Click + Create Application.
- Fill in the following details: In the Name field, specify a name to identify this client, such as "My GraphQL App". For the Application Type, select Single Page Web Applications (or Regular Web Applications if needed).
- Click Create.
- Navigate to the Settings tab to locate the configuration information required for integrating with API Connect Essentials: Domain, Client ID, and Client Secret.
- Copy the values of these fields as they will be used during frontend application setup.
To enable redirection to the frontend application, go to the
Allowed Callback URLs
field and add the following URL: "http://localhost:3000/api/auth/callback".
With these configurations, you have successfully set up your Auth0 account and are ready to proceed to the next steps in the integration process.
Step 2. Creating a Next.js application
To implement the login flow, develop a Next.js frontend application that uses the nextjs-auth0
library. This library streamlines the login process, handles tasks such as redirecting users to the Auth0 Universal Login page and handling callbacks from the Auth0 authorization server. Additionally, it manages the secure storage of JSON Web Tokens (JWTs) in the user's browser and can refresh them when they expire. This setup ensures a smooth login experience while maintaining the security of sensitive user data.
Begin by creating a new Next.js application by running the following command:
During the setup, you might be prompted with questions about your application, including its name, whether you want to use TypeScript, and if you want to enable experimental features. For this tutorial, you can accept the default settings by pressing Enter.
To enable authentication, install the necessary dependency by running:
Add your Auth0 API and application configuration to the
.env
file. Include the following variables:Note: You can execute the following command to generate a suitable string for the
AUTH0_SECRET
value:Now that the configuration is set up, add the code to the Next.js application for using the
nextjs-auth0
library to manage the login flow.Create a new file named
pages/api/auth/[...auth0].ts
(or create the file as`.js
if you are not using TypeScript). The nextjs-auth0 library will use this file to handle the login flow and act as the callback URL for the Auth0 authorization server.Add the following code to the new
pages/api/auth/[...auth0].ts
file:Wrap the application with the
UserProvider
component. This component stores the user information within the React context. This enables you to access user information in any component across the application, making use of the various Hooks provided bynextjs-auth0
. To implement this, include the following code in thepages/_app.tsx
file:
Add a login button and some style to the application.
To add a login button to the application, replace the contents in the
pages/index.tsx
file with the following code:Add some styles to the application. Open the file named
styles/Home.module.css
and append the following code to the end of the file:
Run the application by executing the following command:
Open the application in your web browser by navigating to
http://localhost:3000
. You will find a login button on the page:After clicking the Login button, you will be redirected to the Auth0 Universal Login page. Here, you can either log in using your existing account or sign up for a new one, which will be added to your linked Auth0 account.
After clicking Continue, you will be redirected back to the application. If you open your browser's developer tools and inspect the cookies, you will notice a new cookie containing your JWT. This JWT cookie is used to authenticate you within the application.
You have completed the initial phase of the login flow and obtained a JWT through Auth0. The next step is to use this JWT for authenticating the user within the API Connect Essentials GraphQL API. This authentication will enable you to retrieve the user's profile information from the Auth0 API.
Step 3. Creating a GraphQL API using API Connect Essentials
Use API Connect Essentials (formerly StepZen) to generate a GraphQL API for various data sources, including REST APIs, databases, and more. In this phase, you will establish a GraphQL API that uses the Auth0 JWT for user authentication. This GraphQL API allows you to retrieve the user's profile information from the Auth0 API.
Notice: StepZen was acquired by IBM in 2023 and renamed to API Connect Essentials. Some artifacts still use the StepZen name.
To begin, create a new API Connect Essentials project using the CLI. This involves creating a new directory named
graphql
in the root of your project and run the following command in your terminal:This action generates a new configuration file. Define the endpoint name as
api/jwt-login-flow
. Choose an alternative name if you prefer.To set up the GraphQL API, complete the following steps:
Generate a new schema file named
api.graphql
. This file will house the GraphQL schema for the API, including a query to get user information from the Auth0 API. Remember to substituteYOUR_AUTH0_DOMAIN
with your Auth0 account's domain:API Connect Essentials needs an
index.graphql
file that links to theapi.graphql
file. Create a new file namedindex.graphql
and include the following code in it:To validate the Auth0 JWT, create a new file named
config.yaml
. In this file, configure the validation of the JWT using the JSON Web Key Set (JWKS) endpoint from Auth0 and define the security measures for the GraphQL queryme
to ensure that only authenticated users can access it. Make sure to replace the placeholderYOUR_AUTH0_DOMAIN
with the actual domain of your Auth0 account:
Now, run the following command to deploy your new GraphQL API:
In your terminal, you should receive a message containing the URL of your GraphQL API. Copy the URL, which should start with
https://YOUR_USERNAME.stepzen.net/api/******``, and paste it into the
.env` file:
You now have a functional GraphQL API that can validate the Auth0 JWT and retrieve user information from the Auth0 API.
In the next section, learn how to use this GraphQL API to retrieve the user's profile information within the Next.js application.
Step 4. Retrieving user information in the Next.js Application
In this section, learn how to use GraphQL API established in the previous section to retrieve the user's profile information within the Next.js application. We will use the nextjs-auth0
library to obtain the Auth0 token for authenticating the user in the GraphQL API.
To accomplish this, follow these steps:
Create a new file named
pages/api/graphql/index.ts
. This file will serve as the API route for sending requests to the GraphQL API. It uses thewithApiAuthRequired
function from thenextjs-auth0
library, ensuring that the JWT is accessible in the request. You can extract it using thegetAccessToken
function. We are using an API route here because executing data fetching server-side is the recommended approach in Next.js. The JWT will then be forwarded to the GraphQL API along with the GraphQL query. Add the following code to this file:Note: You can also generate a code snippet to connect to the API Connect Essentials GraphQL API from the dashboard. To do this, navigate to the Explorer tab in the left pane of the dashboard and click Connect in the top navigation.
In the
pages/index.tsx
file, use the new API route to fetch the user's profile information. When sending a request to this API route, include the GraphQL query to retrieve the user's name and picture. Add the following code to this file:After retrieving the user's profile information, you can display it in the UI. Add the following code to the pages/index.tsx file:
Note: Next.js recommends using the
Image
component fromnext/image
to render images. However, when rendering remote sources, you need to allow access to the remote URLs of these sources. Therefore, use theimg
tag instead.Finally, add the styling for the profile information. Add the following code to the
Home.module.css
file:Now, if you open the application in the browser again and click Login with Auth0, you will be redirected to the Auth0 login page. After logging in, you will see the user's profile information displayed in the UI.
You can also show a loading indicator while the application checks if the user is authenticated and fetches the user's profile information. To achieve this, import the
useUser
hook from@auth0/nextjs-auth0/client
, and use theisLoading
property to check if the user is authenticated. Add the following code to thepages/index.tsx
file:
With these steps, you have successfully implemented the login flow using Auth0 and IBM API Connect Essentials. You can access the complete source code for this tutorial on GitHub.
Conclusion
The flow implemented in this tutorial represents a common pattern for frontend applications that offers secure user authentication. It uses the @auth0/nextjs-auth0
package for handling the authentication flow and an API Connect Essentials GraphQL API for server-side JWT verification. This approach enables the application to access user profile information both on the client side and in requests to the GraphQL API.
If you have any thoughts or questions, we encourage you to join our Discord community to share your feedback and stay updated on our latest developments.