Create Light Auth

Understanding how to call the CreateLightAuth method.

Overview

The CreateLightAuth() method is the entry point for initializing Light-Auth in your application. It allows you to configure authentication providers and set up the necessary options for your authentication flow.

Light-Auth uses Arctic v3 for OAuth provider integration. Arctic is a collection of OAuth 2.0 clients for popular providers.

Configure Providers

Set up one or more authentication providers (Google, Microsoft, GitHub, etc.) with their respective credentials.

Call CreateLightAuth

Initialize Light-Auth with your providers and configuration options to get access to authentication methods and utilities.

Configuring Providers

To configure providers, you need to create an instance of the Provider class for each provider you want to use. Each provider requires specific credentials and options.

More information about the providers and their options can be found in the Arctic documentation.

./src/app/auth.ts

import { Google, MicrosoftEntraId } from "arctic";
import { CreateLightAuth } from "@light-auth/nextjs";
import { LightAuthProvider } from "@light-auth/core";

// Configure Google provider
const googleProvider: LightAuthProvider = {
  providerName: "google",
  arctic: new Google(
    GOOGLE_CLIENT_ID, 
    GOOGLE_CLIENT_SECRET, 
    "http://localhost:3000/api/auth/callback/google"),
  searchParams: new Map([["access_type", "offline"]]),
};

// Configure Microsoft provider
const microsoftProvider: LightAuthProvider = {
  providerName: "microsoft",
  arctic: new MicrosoftEntraId(
    process.env.MICROSOFT_ENTRA_ID_TENANT_ID,
    process.env.MICROSOFT_ENTRA_ID_CLIENT_ID,
    process.env.MICROSOFT_ENTRA_ID_CLIENT_SECRET,
    "http://localhost:3000/api/auth/callback/microsoft"
  ),
  scopes: ["offline_access"],
};

The two previous code snippets are also configuring each provider for offline access.
This means that the access token will be refreshed automatically when it expires, allowing you to make API calls without requiring the user to log in again.
More information about refresh tokens can be found in the refresh token documentation.

Option	Type	Description
providerName	`string`	Unique identifier for the provider
arctic	`ArcticProvider`	Instance of an Arctic OAuth provider
scopes	`string[]`	Optional Additional OAuth scopes to request
searchParams	`Map<string, string>`	Optional Additional parameters for the authorization URL
headers	`Map<string, string>`	Optional Additional headers for the authorization request

CreateLightAuth

After configuring your providers, call the CreateLightAuth method to initialize Light-Auth and get access to authentication utilities:

./src/app/auth.ts

import { CreateLightAuth } from "@light-auth/nextjs";
import { LightAuthProvider } from "@light-auth/core";
import { Google, MicrosoftEntraId } from "arctic";

// Provider configurations (from previous step)
const googleProvider: LightAuthProvider = { /* ... */ };
const microsoftProvider: LightAuthProvider = { /* ... */ };

export const { 
  providers,  // Array of configured providers
  handlers,   // API route handlers
  signIn,     // Function to initiate sign-in
  signOut,    // Function to sign out
  getAuthSession, // Function to get the current session
  getUser     // Function to get the complete user data
} = CreateLightAuth({
  providers: [googleProvider, microsoftProvider],

  // Optional configuration options:
  basePath : "/api/auth",
  env : process.env,
  router :  exampleRouter ,
  sessionStore : exampleSessionStore,
  userAdapter : exampleUserAdapter,

  // Optional callbacks:
  onSessionSaving: async (session, tokens) => {},
  onSessionSaved: async (session, tokens) => {},
  onUserSaving: async (user, tokens) => {},
  onUserSaved: async (user, tokens) => {},

});

Option	Type	Description
providers	`LightAuthProvider`	List of configured providers
basePath	`string`	Optional Base path for the API routes. Default: `"/api/auth"`. See the API handlers for more information.
env	`[key: string]: string \| undefined`	Optional Object containing environment variables. Default: `process.env`.
router	`LightAuthRouter`	Optional Router instance for handling redirects and navigation.
sessionStore	`LightAuthSessionStore`	Optional Session store instance for persisting user sessions.
userAdapter	`LightAuthUserAdapter`	Optional Default NULL User adapter instance for handling user data.

All the optional features are implemented by your specific light-auth package (e.g., light-auth-nextjs, light-auth-express, light-auth-astro) except for the user adapter, which is null by default.

Option	Type	Description
onSessionSaving	`(session, claims) => LightAuthSession`	Optional Callback for modifying the session before saving it.
onSessionSaved	`(session) => void`	Optional Callback for actions after the session is saved.
onUserSaving	`(user, claims) => LightAuthUser`	Optional Callback for modifying the user before saving it.
onUserSaved	`(user) => void`	Optional Callback for actions after the user is saved.