Next.js Quickstart

In the following, we will integrate User Management with a Next.js application.

Check out the example repository on GitHub

Before we get started

For this quickstart guide, we'll use Upstash as our database provider. Upstash is a serverless Redis-as-a-Service provider that offers a free tier. Using Upstash is not required, but you'll need some way to store your users. If you already have a database, you can use that instead.

Check out the example repository

To get up to speed, it's easiest to check out the example repository. It contains a fully working Next.js application with User Management integrated.

# only include the nextjs-user-management folder
git clone https://github.com/anzuhq/examples.git --depth 1
cd examples/nextjs-user-management
bash

Install dependencies

This project has been tested with Node.js 16.17 and pnpm 7.9.5, please make sure that your system is compatible. After cloning the repository, we can install all required dependencies, which may take a while.

pnpm install
bash

Set up the database

Create a .env.production file in the current directory and add the following:

UPSTASH_REDIS_REST_URL=<redis-rest-url>
UPSTASH_REDIS_REST_TOKEN=<redis-rest-token>
env

You can find the redis-rest-url and redis-rest-token in your Upstash dashboard.

Deploy the project initially

To receive a URI to redirect our users back to, we need to deploy the project once. We'll use Vercel for this.

$ pnpm run deploy

> nextjs-user-management@0.1.0 deploy /examples/nextjs-user-management
> vercel

Vercel CLI 28.2.2
? Set up and deploy “~/examples/nextjs-user-management”? [Y/n] y
? Which scope do you want to deploy to? demo-scope
? What’s your project’s name? demo-nextjs-user-management
? In which directory is your code located? ./
Local settings detected in vercel.json:
Auto-detected Project Settings (Next.js):
- Build Command: next build
- Development Command: next dev --port $PORT
- Install Command: `yarn install`, `pnpm install`, or `npm install`
- Output Directory: Next.js default
? Want to modify these settings? [y/N] n
🔗  Linked to demo-scope/demo-nextjs-user-management (created .vercel)
🔍  Inspect: https://vercel.com/demo-scope/demo-nextjs-user-management/... [1s]
✅  Production: https://demo-nextjs-user-management.vercel.app [41s]
📝  Deployed to production. Run `vercel --prod` to overwrite later (https://vercel.link/2F).
💡  To change the domain or build command, go to https://vercel.com/demo-scope/demo-nextjs-user-management/settings```
bash

Make sure to copy the production URL (https://demo-nextjs-user-management.vercel.app in the example above), we'll need it later.

Set up User Management

Configuring the Hosted Page URL

By default, you will be assigned a random tenant alias for the hosted auth page. You can enter a custom alias if needed. Copy the Hosted Page URL and add it to your .env.production file as NEXT_PUBLIC_HOSTED_AUTH_PAGE_URL.

Configuring the Redirect URL

In the Redirect URI section, add the deployment URL to the list of Allowed Redirect URIs and click Save. Add the Redirect URI to your .env.production file as NEXT_PUBLIC_REDIRECT_URI.

Configuring an auth provider

For the beginning, we'll use email authentication with magic links. For this, navigate to the Auth Providers section, expand Email (with Magic Links), tick the Enabled checkbox and click Save. You should see a checkmark next to the Email (with Magic Links) entry.

Configure user provisioning

In the next section, we will look at user provisioning. Whenever a new user signs up to your application via the hosted auth page, Anzu will notify your application via a webhook.

Configure a provisioning webhook

Click on your name to get back to the main navigation, then click on Developers to go to the webhook settings. Create a new webhook and enter the deployment URL from before followed by /api/provisioning.

From the events section, choose the User Identity Created event.

After creating the webhook, copy the secret over to your .env.production file as WEBHOOK_SECRET.

Note: The webhook will be disabled until you tick the Enabled checkbox and click Save. This is designed for you to configure the webhook secret in your application before enabling it.

Create a provisioning token

To let Anzu know the user was provisioned in your application, we send an API request. This request has to be sent with a valid access token. For the time being, you can use your user's access token from Settings in the Access Tokens section.

Copy the created token over to your .env.production file as ANZU_ACCESS_TOKEN.

Configure JWT verification

Last but not least, we need to set the secret Anzu uses for signing JWTs for your users. This can be found in the User Management settings under Access Tokens and should be copied over to your .env.production file as JWT_SIGNING_SECRET.

Verify all variables have been set

Before we deploy again, please make sure the following variables have been defined in your .env.production file:

UPSTASH_REDIS_REST_URL=<redis-rest-url>
UPSTASH_REDIS_REST_TOKEN=<redis-rest-token>

WEBHOOK_SECRET=<secret copied from webhook details page>
JWT_SIGNING_SECRET=<secret copied from user management settings>

ANZU_ACCESS_TOKEN=<token copied from team settings>

NEXT_PUBLIC_HOSTED_AUTH_PAGE_URL=<the hosted auth page URL copied from the user management settings>
NEXT_PUBLIC_REDIRECT_URI=<where this page is hosted>
env

Deploy again

Deploy your application again by running pnpm run deploy --prod in your terminal. This will create a new deployment and update the production deployment.

Enable the webhook

Now that the webhook secret has been set in your application, we can enable the webhook. Navigate to the Webhooks section, open your newly-created webhook, and tick the Enabled checkbox. Click Save to enable the webhook.

After enabling the webhook, you should see a new webhook delivery appear. This is a test delivery to make sure the webhook is working. If this is successful, you are ready to move on to the next section!

If the test delivery failed, please check the following:

You can access the webhook endpoint from your browser (it should return Method not allowed)
You configured the correct WEBHOOK_SECRET

If you are still having trouble, please check your deployment logs for further hints.

Trying it out!

Now that everything is set up, we can try the example application. Navigate to the deployment URL, which should show a page asking you to sign in.

After entering your mail and confirming the code, you will be redirected to a waiting room page, until your application has provisioned the user. After a couple of seconds, you should be redirected back to the starting page, which now displays your email fetched from the application database. The request is sent to a Next.js API route which verifies the token using the shared secret.

Next steps

Now that your users can sign in with their emails, you could add more authentication providers, such as Google or GitHub.
Your users should know what they're signing up to. Add more details to the hosted page appearance section of the user management settings