This is a simple example of how to use @curveball/a12n-server
with a Next.js project using:
- OAuth2 authorization code flow
- OIDC
next-auth@beta
/authjs/dev
v5.
If you've been using next-auth
v4, checkout their "Upgrade Guide (NextAuth.js v5)".
Pre-requisites:
pnpm
- node >= 20
From this workspace root:
pnpm install
to install dependencies.
pull the latest changes for the @curveball/a12n-server
submodule:
# initialize and update the submodule
git submodule init
git submodule update --rebase
In separate Terminal tabs:
pnpm start:server
to start server (will open at http://localhost:8531/
)
pnpm start:client
will open Next at http://localhost:3000/
pnpm lint
to lint all projects
From inside each project, running pnpm <command>
for respective package.json
scripts will also act on each project.
cp .env.local.example .env
to copy the default environment variables.
Note: you can delete .env.local.example
or comment out all variables in .env.local.example
to avoid namespace conflicts while running locally.
Environment variables prefixed with AUTH_
are used by authjs/next-auth
. See "Environment Variable Inference"
- Generate the server env variables
cd a12n-server
node ./bin/a12n-server
This creates a .env with a JWT private key and also autostarts the server.
The default settings are configured to use a sqlite database, which is fine for dev environments, but not intended for production use.
- Opening
http://localhost:8531
will prompt you to create an admin user.
If you for whatever reason lock yourself out or forget your admin password, you can start over by deleting the a12nserver.sqlite
file.
For next-auth to work, you need to obtain a OAuth2 client id and secret.
To quickly do this, you can open the following URL in your browser, which should take you through all the steps.
🗒️ Make note of the client_id
and client_secret
values, at the end of this process.
http://localhost:8531/app/new?nickname=MyNextApp&allowedGrantTypes=authorization_code,refresh_token
&redirectUris=http://localhost:3000/api/auth/callback/a12n-server&url=http://localhost:3000/&clientId=nextjs-app
Or manually create the client by following the steps below:
- Go to
http://localhost:8531/app/new
to register a new app as client.
You will need to provide the:
- client name (this will become known as the
nickname
on a12n-server) - client URL (
NEXTAUTH_URL
).
The client_id
is used in the client to authenticate with the server.
The client URL is used to redirect the user back to the client after authentication.
- You'll be directed to configure the client.
Select "authorization_code" and "refresh_token" as grant types.
For a valid redirectUrl
make sure you entered: http://localhost:3000/api/auth/callback/a12n-server
- Click "Add"
Your client is now registered and you can use the clientId
and clientSecret
in your client-side app.
Hang onto the values of clientId
and clientSecret
for the next step.
You can also add more apps by selecting "Manage Clients" from the a12n-server
dashboard.
-
Update your
.env
file with:AUTH_A12N_ID
with the value forclient_id
AUTH_A12N_SECRET
with theclient_secret
value. -
Restart your client and server to continue development.
Note: this setup is intended for easy development and scaffolding. This is not a recommended setup for production environments.
For first-time setup
# For first-time setup:
# initialize and update the submodule
git submodule init
git submodule update --rebase
# For updates
# switch to the submodule directory
cd a12n-server
# pull the latest changes for the submodule
git pull origin main
If you made changes and want to commit them
# return to root of project
cd ..
# add the submodule
git add a12n-server
git commit -m "Update submodule"
## this updates the submodule in the parent repo,
## not the original @curveball/a12n-server
git push origin main