The AuthKit library for Next.js provides convenient helpers for authentication and session management using WorkOS & AuthKit with Next.js.
Install the package with:
npm i @workos-inc/authkit-nextjs
or
yarn add @workos-inc/authkit-nextjs
![YouTube tutorial: Next.js App Router Authentication with AuthKit](https://private-user-images.githubusercontent.com/658360/351138006-ed67129b-3b27-4745-8960-64db4c8ab393.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUzNTE4NzYsIm5iZiI6MTcyNTM1MTU3NiwicGF0aCI6Ii82NTgzNjAvMzUxMTM4MDA2LWVkNjcxMjliLTNiMjctNDc0NS04OTYwLTY0ZGI0YzhhYjM5My5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwOTAzJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDkwM1QwODE5MzZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT05ZmM5NzA4NjUwZmE0ZGEzYjFhMjliYzE0OWQ3MDg1NWMwMWQ1ZWJlZTFmNjQ0ZjVmOTE0ZmE2MzBjOTI2M2E3JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.1CxFbO24xj91582oT4FJ_QdRvW_QOMPD5FiAxzse1Ao)
Make sure the following values are present in your .env.local
environment variables file. The client ID and API key can be found in the WorkOS dashboard, and the redirect URI can also be configured there.
WORKOS_CLIENT_ID="client_..." # retrieved from the WorkOS dashboard
WORKOS_API_KEY="sk_test_..." # retrieved from the WorkOS dashboard
WORKOS_REDIRECT_URI="http://localhost:3000/callback" # configured in the WorkOS dashboard
WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
WORKOS_COOKIE_PASSWORD
is the private key used to encrypt the session cookie. It has to be at least 32 characters long. You can use the 1Password generator or the openssl
library to generate a strong password via the command line:
openssl rand -base64 24
To use the signOut
method, you'll need to set your app's homepage in your WorkOS dashboard settings under "Redirects".
Certain environment variables are optional and can be used to debug or configure cookie settings.
WORKOS_COOKIE_MAX_AGE='600' # maximum age of the cookie in seconds. Defaults to 31 days
WORKOS_API_HOSTNAME='api.workos.com' # base WorkOS API URL
WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
WORKOS_API_PORT=3000 # port to use for API calls
WORKOS_COOKIE_DOMAIN
can be used to share WorkOS sessions between apps/domains.
Note: The WORKOS_COOKIE_PASSWORD
would need to be the same across apps/domains.
Not needed for most use cases.
WorkOS requires that you have a callback URL to redirect users back to after they've authenticated. In your Next.js app, expose an API route and add the following.
import { handleAuth } from '@workos-inc/authkit-nextjs';
export const GET = handleAuth();
Make sure this route matches the WORKOS_REDIRECT_URI
variable and the configured redirect URI in your WorkOS dashboard. For instance if your redirect URI is http://localhost:3000/auth/callback
then you'd put the above code in /app/auth/callback/route.ts
.
You can also control the pathname the user will be sent to after signing-in by passing a returnPathname
option to handleAuth
like so:
export const GET = handleAuth({ returnPathname: '/dashboard' });
This library relies on Next.js middleware to provide session management for routes. Put the following in your middleware.ts
file in the root of your project:
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
export default authkitMiddleware();
// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher: ['/', '/admin'] };
Use AuthKitProvider
to wrap your app layout, which adds some protections for auth edge cases.
import { AuthKitProvider } from '@workos-inc/authkit-nextjs';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<AuthKitProvider>{children}</AuthKitProvider>
</body>
</html>
);
}
For pages where you want to display a signed-in and signed-out view, use getUser
to retrieve the user profile from WorkOS.
import Link from 'next/link';
import { getSignInUrl, getSignUpUrl, getUser, signOut } from '@workos-inc/authkit-nextjs';
export default async function HomePage() {
// Retrieves the user from the session or returns `null` if no user is signed in
const { user } = await getUser();
if (!user) {
// Get the URL to redirect the user to AuthKit to sign in
const signInUrl = await getSignInUrl();
// Get the URL to redirect the user to AuthKit to sign up
const signUpUrl = await getSignUpUrl();
return (
<>
<Link href={signInUrl}>Log in</Link>
<Link href={signUpUrl}>Sign Up</Link>
</>
);
}
return (
<form
action={async () => {
'use server';
await signOut();
}}
>
<p>Welcome back {user?.firstName && `, ${user?.firstName}`}</p>
<button type="submit">Sign out</button>
</form>
);
}
For pages where a signed-in user is mandatory, you can use the ensureSignedIn
option:
const { user } = await getUser({ ensureSignedIn: true });
Enabling ensureSignedIn
will redirect users to AuthKit if they attempt to access the page without being authenticated.
The default behavior of this library is to request authentication via the getUser
method on a per-page basis. There are some use cases where you don't want to call getUser
(e.g. you don't need user data for your page) or if you'd prefer a "secure by default" approach where every route defined in your middleware matcher is protected unless specified otherwise. In those cases you can opt-in to use middleware auth instead:
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
export default authkitMiddleware({
middlewareAuth: {
enabled: true,
unauthenticatedPaths: ['/', '/about'],
},
});
// Match against pages that require auth
// Leave this out if you want auth on every resource (including images, css etc.)
export const config = { matcher: ['/', '/admin/:path*', '/about'] };
In the above example the /admin
page will require a user to be signed in, whereas /
and /about
can be accessed without signing in.
unauthenticatedPaths
uses the same glob logic as the Next.js matcher.
Use the signOut
method to sign out the current logged in user and redirect to your app's homepage. The homepage redirect is set in your WorkOS dashboard settings under "Redirect".
Render the Impersonation
component in your app so that it is clear when someone is impersonating a user.
The component will display a frame with some information about the impersonated user, as well as a button to stop impersonating.
import { Impersonation } from '@workos-inc/authkit-nextjs';
export default function App() {
return (
<div>
<Impersonation />
{/* Your app content */}
</div>
);
}
Sometimes it is useful to obtain the access token directly, for instance to make API requests to another service.
import { getUser } from '@workos-inc/authkit-nextjs';
export default async function HomePage() {
const { accessToken } = await getUser();
if (!accessToken) {
return <div>Not signed in</div>;
}
const serviceData = await fetch('/api/path', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
});
return <div>{serviceData}</div>;
}
Use the refreshSession
method in a server action or route handler to fetch the latest session details, including any changes to the user's roles or permissions.
The organizationId
parameter can be passed to refreshSession
in order to switch the session to a different organization. If the current session is not authorized for the next organization, an appropriate authentication error will be returned.
To enable debug logs, initialize the middleware with the debug flag enabled.
import { authkitMiddleware } from '@workos-inc/authkit-nextjs';
export default authkitMiddleware({ debug: true });
Wrapping a getUser({ ensureSignedIn: true })
call in a try/catch block will cause a NEXT_REDIRECT
error. This is because getUser
will attempt to redirect the user to AuthKit if no session is detected and redirects in Next must be called outside a try/catch.