FeaturesAuthentication

Integration

How to implement the authentication feature in an existing application.

This guide explains how to implement the authentication feature in a new/existing application using the @kit/auth package.

Installation

First, install the authentication package:


pnpm add '@kit/auth@workspace:*'

Configuration File

Create the authentication configuration in config/auth.config.ts.

This object will contain all customization options, allowing you to change the behavior of the authentication system.

You gonna pass this object to almost all the code coming from the @kit/auth package.

config/auth.config.ts


import { parseAuthConfig } from '@kit/auth/config';
 
export const authConfig = parseAuthConfig({
    scopePatterns: {
        auth: '/auth/*?',
        private: '/your-protected-website-endpoints/*?',
    },
    urls: {
        home: '/your-protected-website-endpoints',
        callback: '/auth/callback',
        signIn: '/auth/sign-in',
        signUp: '/auth/sign-up',
        forgottenPassword: '/auth/forgotten-password',
        verifyMfa: '/auth/verify-mfa',
    },
    captchaSiteKey: process.env.NEXT_PUBLIC_CAPTCHA_SITE_KEY,
    displayTermsCheckbox: true,
    providers: {
        password: true,
        oAuth: ['google'],
    },
    passwordRequirements: {
        minLength: 3,
        maxLength: 99,
        specialChars: false,
        numbers: false,
        uppercase: false,
    },
});

AuthConfig

Prop	Type	Default
`scopePatterns*`	`{ auth: string; private:...`
`providers*`	`{ password: boolean; oAuth:...`
`urls*`	`{ dashboard: string;...`
`captchaSiteKey`	`string`
`displayTermsCheckbox`	`boolean`
`passwordRequirements`	`{ minLength: number;...`

Middleware

middleware.ts

import { authMiddleware } from '@kit/auth/middleware/auth';
import { NextResponse, type NextRequest } from 'next/server';
import { authConfig } from './config/auth.config';
 
export async function middleware(request: NextRequest): Promise<NextResponse<unknown>> {
    const response = NextResponse.next();
 
    const authResponse = await authMiddleware(request, response, authConfig);
    if (authResponse) return authResponse;
 
    // ...other middleware logic
 
    return response;
}
 
export const config = {
    matcher: ['/((?!_next/static|_next/image|images|locales|assets|api/*).*)'],
};

When the authResponse is truthy, it means that the authMiddleware has handled the request and we don't need to execute other middleware.

Auth Provider

You must wrap your app with the AuthProvider component.

The AuthProvider component make sure that the user is authenticated.

For instance, if the user logout in another tab, the AuthProvider will redirect the user to the sign in page for all tabs opened in the browser.

app/layout.tsx

import React from 'react';
import { AuthProvider } from '@kit/auth/ui/auth-provider';
import { authConfig } from '~/config/auth.config';
 
export default function Layout({ children }: React.PropsWithChildren) {
    
    return (
        <html>
            <body>
                <AuthProvider authConfig={authConfig}>
                    {children}
                </AuthProvider>
            </body>
        </html>
    );
}

AuthProviderProps

Prop	Type	Default
`authConfig*`	`{ scopePatterns: { auth:...`
`onEvent`	`function`
`children`	`ReactNode`

The onEvent props may be useful trigger action for monitoring or analytics purposes. Check the source code of the kit in the dashboard app for more details.

Auth Pages

Now you need to create the authentication pages in a app/auth/ directory.

To simplify as much as possible the integration, we created the following helper functions to generate the authentication pages:

Function	Description
createSignInPage `(authConfig, joinOrganizationPath?)`	Generates the sign in page
createSignUpPage `(authConfig)`	Generates the sign up page
createForgottenPasswordPage `(authConfig)`	Generates the forgotten password page
createVerifyMfaPage `(authConfig)`	Generates the MFA verification page

You just gonna need to pass the authConfig object to the helper function to generate the page.

Example

app/auth/sign-in/page.tsx

import { createSignInPage } from '@kit/auth/pages/sign-in';
import { authConfig } from '~/config/auth.config';
 
export default createSignInPage(authConfig, '/dashboard');

Now do the same for the other pages:

app/auth/sign-up/page.tsx
app/auth/forgotten-password/page.tsx
app/auth/verify-mfa/page.tsx

The joinOrganizationPath is optional and will be used to redirect the user to the organization page after the sign in. See the organization feature integration guide for more details.

If you want to customize the authentication pages deeply. Look at the source code of the kit pages functions, all of their components are exported from the package.

Auth Routes

Same thing, we created the following helper functions to generate the authentication routes:

Function	Description
createCallbackRoute`(authConfig)`	Generates the callback route used at the end of sign in and sign up flows
createConfirmRoute`(authConfig)`	Generates the confirm route for the MFA flow

Example

Here is what the app/auth/callback/route.ts file will look like:

app/auth/callback/route.ts

import { createCallbackRoute } from '@kit/auth/routes/callback';
import { authConfig } from '~/config/auth.config';
 
export const GET = createCallbackRoute(authConfig);

Now do the same for the other route:

app/auth/confirm/route.ts

The createCallbackRoute and createConfirmRoute functions will return a function that can be used as a route handler.

Setup your authentication providers

You still need to set your environment variables and the supabase authentication providers.

Follow the previous page to setup your authentication provider.

What's Next

You've successfully integrated the core authentication system into your application. The integration guide has covered:

Now you users will be able to sign in and sign up to your application.

But you still need to get the user data and handle the user logout to have a fully working authentication system.

In the next pages, you will learn how to:

Page	Description
User Access	Learn how to retrieve, display user information and logout a user
Password Management	Change password functionality and security features
Session Management	View and manage active user sessions
MFA Security	Enable two-factor authentication
Account Deletion	Delete a user account

Authentication

The only authentication documentation page you need if you just want to setup the dashboard application.

Retrieve User

Retrieve the current user in your application.

How is this guide?

Last updated on 10/17/2025