Authentication

This guide explains how to configure authentication for the Zero Kelvin web application. The application uses Auth.js (NextAuth.js v5) for authentication, supporting multiple OAuth providers including social login and OIDC.

Overview

The authentication system provides:

• Social authentication (Google, Facebook, Apple, LinkedIn)
• OpenID Connect (OIDC) support (including self-hosted providers like Authelia)
• Session management with JWT
• Gravatar-based user avatars
• Secure sign-in and sign-out flows

Quick Start

1. Copy the example environment file:

cp apps/web/.env.example apps/web/.env.local

2. Generate an AUTH_SECRET:

openssl rand -base64 32

3. Add your OAuth provider credentials (see provider-specific guides below)

4. Start the development server:

nx dev web

Environment Variables

Variable	Description	Required
AUTH_SECRET	Secret key for encrypting tokens and cookies	Yes
AUTH_GOOGLE_ID	Google OAuth Client ID	For Google auth
AUTH_GOOGLE_SECRET	Google OAuth Client Secret	For Google auth
AUTH_FACEBOOK_ID	Facebook App ID	For Facebook auth
AUTH_FACEBOOK_SECRET	Facebook App Secret	For Facebook auth
AUTH_APPLE_ID	Apple Service ID	For Apple auth
AUTH_APPLE_SECRET	Apple Private Key	For Apple auth
AUTH_LINKEDIN_ID	LinkedIn Client ID	For LinkedIn auth
AUTH_LINKEDIN_SECRET	LinkedIn Client Secret	For LinkedIn auth
AUTH_AUTHELIA_ISSUER	Authelia instance URL	For Authelia OIDC
AUTH_AUTHELIA_ID	Authelia Client ID	For Authelia OIDC
AUTH_AUTHELIA_SECRET	Authelia Client Secret	For Authelia OIDC

Architecture

The authentication system consists of:

• /apps/web/src/auth.ts - Auth.js configuration
• /apps/web/src/app/api/auth/[...nextauth]/route.ts - API route handler
• /apps/web/src/components/auth-provider.tsx - React context provider
• /apps/web/src/components/user-menu.tsx - User menu component
• /apps/web/src/app/auth/signin/page.tsx - Custom sign-in page

Adding a New Provider

To add a new authentication provider:

1. Import the provider in auth.ts:

import NewProvider from "next-auth/providers/newprovider";

2. Add the provider to the providers array:

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    // ... existing providers
    NewProvider({
      clientId: process.env.AUTH_NEWPROVIDER_ID,
      clientSecret: process.env.AUTH_NEWPROVIDER_SECRET,
    }),
  ],
});

3. Add the environment variables to .env.local

4. Update the sign-in page to include the new provider button

Custom OIDC Provider

To add a custom OpenID Connect provider:

import NextAuth from "next-auth";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: "my-oidc-provider",
      name: "My OIDC Provider",
      type: "oidc",
      issuer: "https://my-oidc-provider.com",
      clientId: process.env.AUTH_OIDC_ID,
      clientSecret: process.env.AUTH_OIDC_SECRET,
    },
  ],
});

Session Management

Server Components

Access the session in server components:

import { auth } from "@/auth"

export default async function Page() {
  const session = await auth()

  if (!session) {
    return <div>Not authenticated</div>
  }

  return <div>Hello, {session.user?.name}</div>
}

Client Components

Access the session in client components using the useSession hook:

"use client"
import { useSession } from "next-auth/react"

export function MyComponent() {
  const { data: session, status } = useSession()

  if (status === "loading") {
    return <div>Loading...</div>
  }

  if (!session) {
    return <div>Not authenticated</div>
  }

  return <div>Hello, {session.user?.name}</div>
}

Protecting Pages

Protect pages by checking the session:

import { auth } from "@/auth"
import { redirect } from "next/navigation"

export default async function ProtectedPage() {
  const session = await auth()

  if (!session) {
    redirect("/auth/signin")
  }

  return <div>Protected content</div>
}

User Avatars

The application automatically generates Gravatar URLs based on the user's email address. If the OAuth provider returns a profile image, that will be used instead.

import { getGravatarUrl } from "@/lib/gravatar";

// Generate a Gravatar URL
const avatarUrl = getGravatarUrl(user.email, 80);

Troubleshooting

Common Issues

1. "Invalid OAuth credentials" - Verify your client ID and secret are correct
2. "Redirect URI mismatch" - Check that your OAuth app's redirect URI matches http://localhost:3000/api/auth/callback/{provider} for development
3. "Session not persisting" - Ensure AUTH_SECRET is set and consistent across deployments

Debug Mode

Enable debug logging by adding to your .env.local:

AUTH_DEBUG=true