Add Authentication to your Next.js / React Single Page Application (SPA)

Add authentication and user management to your Next.js React app using the new Next.js Edge Runtime and the Ory Kratos open source project! This example also contains end-to-end tests! To deploy the full and working project, hit the button:

If you like watching videos instead of reading text, watch Vincent's video tutorial!

Ory Kratos Open Source Identity Platform

Ory Kratos is a full-featured, free, and open source authentication and identity management platform. It supports multi-factor authentication with FIDO2, TOTP, and OTP; Social Sign In, custom identity models; registration, profile management, account recovery, administrative user management and so much more! In contrast to other identity systems, Ory Kratos enables you to build your own login, registration, account settings, account verification (e.g. email, phone, activate account), account verification (e.g. reset password) user interfaces and user flows using dead-simple APIs. This guide focuses on integrating with Ory Kratos' session and login APIs. If you are interested in building your own UI, check out Add Custom Login, Registration, User Settings to Your Next.js & React Single Page Application (SPA)

Before we start, let's get some terminology out of the way:

• At Ory, identity can mean any actor in a system (user, robot, service account, ...). The term user always refers to a human being sitting in front of a browser or mobile app.
• A session refers to a user's session in a browser or mobile app after they have authenticated.
• Self-Service refers to flows the user can do on their own - such as login, registration, and so on. It does not require administrative / support intervention.

Next.js Authentication with Ory Kratos

If you want to see a live demo right away, check out this app in action.

You can find the source code for this guide on GitHub. To give it a spin, clone it and run the following commands:

git clone https://github.com/ory/kratos-nextjs-react-example.git
cd kratos-nextjs-react-example
npm i

Per default, this app uses the public playground deployment of Ory Kratos at https://playground.projects.oryapis.com. To use it, simply run:

npm run dev

To use your own Ory Kratos instance, you can use the ORY_SDK_URL environment variable. To get started we recommend to run Ory Kratos in an Ory Network Project, which is free for developers. You can create a new project on console.ory.sh or you via the Ory CLI. Install the CLI with the package manager of your choice on Linux, macOs, or Windows.

Create a new developer project with just two commands:

# Download the Ory CLI to your local directory:
bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
# Log into an existing account or create a new one:
./ory auth
# Create a new project:
./ory create project --name <your-project-name>

After the project has been created the CLI displays the project details:

Project created successfully!
ID            a0c23a9d-bd3b-4a20-a6c0-00a1ada73f49
SLUG	        laughing-ardinghelli-cvaggbj1hi
STATE	        running
NAME	        Example

Copy the SLUG, and set the ORY_SDK_URL to the SDK URL of the project you just created:

# If you run Ory Kratos in the Ory Network:
export ORY_SDK_URL=https://YOUR_PROJECT_SLUG_HERE.projects.oryapis.com

# Start the app
npm run dev

Next head over to http://localhost:3000/ to see the app in action with login, registration - a working user management!

Ory Kratos on your Machine

You can also run Ory Kratos on your own machine and develop in a local environment. A quick way to begin is to run the Ory Kratos Docker quickstart as it includes all the necessary dependencies. You can run Ory Kratos without Docker as well!

git clone --depth 1 --branch master https://github.com/ory/kratos.git
cd kratos
git checkout master
git pull -ff
docker-compose -f quickstart.yml -f contrib/quickstart/kratos/cloud/quickstart.yml up --build --force-recreate -d

When deploying Ory Kratos yourself, set the ORY_SDK_URL to your local Ory Kratos instance:

# If you run Ory Kratos locally using the Docker quick start:
export ORY_SDK_URL=http://localhost:4455/

# Start the app
npm run dev

Next head over to http://localhost:3000/ to see the app in action with login, registration - a working user management!

Create a Next.js Single Page App with Ory Kratos from Scratch

To add login / auth to your Next.js app, first create a new Next.js project

npx create-next-app@latest --typescript

and install the Ory Kratos SDK as well as Ory's NodeJS integration helpers

npm i --save @ory/integrations @ory/kratos-client

Then we will add Ory's Next.js Edge-Integration helpers to our project, which will act as a tunnel to Ory Kratos. You can either conveniently copy this route from our reference application

curl -o "pages/api/.ory/[...paths].ts" --create-dirs \
  https://raw.githubusercontent.com/ory/kratos-nextjs-react-example/master/pages/api/.ory/%5B...paths%5D.ts

or manually create a file called pages/api/.ory/[...paths].js in your NextJS project and copy the following contents:

Add the Ory Kratos SDK to your Next.js App

Great, now you have a NextJS app with a login route. If the user is authenticated we want to show the session. If the user is not signed in, we want to offer a way to sign up or sign in! Let's take a look at the home page. First, we need to add the Ory Kratos SDK to our Next.js app:

Easy, right? The package @ory/integrations takes care of all the heavy lifting for you and sets up the SDK so that it connects with the Next.js Edge function we created in the step prior.

React Hook to Find Out if a User is Authenticated

Next let's figure out if the user is authenticated. We will use a React Hook to check this. We also want to track any errors that may happen as well as creating a logout url.

Adding Login and Registration Links if the User is Not Authenticated

Let's also show the user a login and registration link if the user has no login session yet

or the account settings and logout link if the user is authenticated!

As you can see, it is really easy to initialize login, registration, and profile updates. Just create a link!

• <a href="/api/.ory/self-service/login/browser"> will initialize the login flow.
• <a href="/api/.ory/self-service/registration/browser"> will initialize the registration flow.
• <a href="/api/.ory/self-service/settings/browser"> will initialize the account settings flow (needs login).
• <a href="/api/.ory/self-service/verification/browser"> will initialize the (email, phone, ...) verification flow.
• <a href="/api/.ory/self-service/recovery/browser"> will initialize the (password, 2fa, ...) recovery flow.

Adding a Logout Link for Authenticated Users

To prevent certain types of attack vectors, such as Denial of Service, Ory Kratos provides a secure logout mechanism. This involves first fetching a logout URL from the Ory Kratos API and then redirecting the user to that URL if logout is requested:

If we do not bind the logout URL to the user's session, it means that anyone could load e.g. an image with the logout URL and logout the user without user interaction:

<img src="https://www.example.org/my-vulnerable-logout-command" />

Ory Kratos protects you from these type of attacks with the flow shown above.

Putting it all Together

You've made it! Clone the app and try it out right now!

git clone https://github.com/ory/kratos-nextjs-react-example.git
cd kratos-nextjs-react-example
npm i

Or look at the code we wrote above in full below:

Deploy to Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js. If you have never deployed on Vercel, check out the Next.js deployment documentation for more details. Ensure that your build works:

npm run build

Then, set up your Vercel account and create a new app. You will need to configure your The Ory Network Project SDK URL or the URL of your self-hosted Ory Kratos instance in your Vercel deployment:

If you want to call the Ory Network's Admin APIs from your Next.js Edge serverless functions, optionally set up the Ory Personal Access Token:

Next all you need to do is to run the deploy command and connect it to the project you created:

npx vercel deploy --prod

This also works with Vercel PR Preview!

End-to-End Tests

Adding end-to-end tests is also straightforward! Clone the repository and run the following commands:

git clone https://github.com/ory/kratos-nextjs-react-example.git
cd kratos-nextjs-react-example
npm i

Then export the ORY_SDK_URL, as described above (switch out with your project SLUG):

export ORY_SDK_URL=https://YOUR_PROJECT_SLUG_HERE.projects.oryapis.com

Then, build and start the server

npm run dev

and in a new shell run the end-to-end tests:

npm run test:dev

You can find the full spec file in the cypress/integration/pages.spec.js file:

The GitHub Action file is also straight forward and contains two configurations, one for running Ory Kratos locally and one for running Ory Kratos in the Ory Network:

Conclusion

Adding login and registration to your Next.js app is a breeze with open source technology like Ory Kratos and Next.js.

We hope you enjoyed this guide and found it helpful! If you have any questions, check out the Ory community on Slack and GitHub!