Integrating Calimatic Identity with Next.js: A Complete Guide

Next.js is one of the most popular frameworks for building modern web applications, and integrating it with an identity provider is one of the first things you'll need to do. In this guide, we'll walk through connecting a Next.js app to Calimatic Identity using our OAuth2/OIDC server.

Prerequisites

• A Next.js 14+ application with App Router
• A Calimatic Identity account (free tier works)
• An app client registered in the Calimatic admin panel

Step 1: Register an App Client

In the Calimatic admin panel, navigate to App Clients and create a new client:

• Name: My Next.js App
• Type: Confidential (since Next.js has a server-side component)
• Redirect URIs: http://localhost:3000/api/auth/callback/calimatic
• Allowed scopes: openid, profile, email

Note your Client ID and Client Secret — you'll need these in the next step.

Step 2: Install NextAuth.js

NextAuth.js (Auth.js) is the standard authentication library for Next.js. Install it:

npm install next-auth

Step 3: Configure the OIDC Provider

Create your auth configuration. Calimatic Identity supports OIDC discovery, so configuration is minimal:

// src/lib/auth.ts
import NextAuth from "next-auth";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: "calimatic",
      name: "Calimatic Identity",
      type: "oidc",
      clientId: process.env.CALIMATIC_CLIENT_ID,
      clientSecret: process.env.CALIMATIC_CLIENT_SECRET,
      issuer: process.env.CALIMATIC_ISSUER_URL,
      checks: ["pkce", "state", "nonce"],
    },
  ],
  session: { strategy: "jwt" },
});

The issuer URL points to your Calimatic Identity instance. NextAuth will automatically discover all endpoints from the .well-known/openid-configuration document.

Step 4: Set Up Environment Variables

CALIMATIC_CLIENT_ID=your-client-id
CALIMATIC_CLIENT_SECRET=your-client-secret
CALIMATIC_ISSUER_URL=https://auth.yourdomain.com
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-random-secret

Step 5: Create the API Route

// src/app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/lib/auth";
export const { GET, POST } = handlers;

Step 6: Protect Your Pages

Use the auth() function in server components to check authentication:

// src/app/dashboard/page.tsx
import { auth } from "@/lib/auth";
import { redirect } from "next/navigation";

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

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

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Email: {session.user.email}</p>
    </div>
  );
}

Step 7: Add Middleware for Route Protection

For protecting multiple routes, use Next.js middleware:

// src/middleware.ts
import { auth } from "@/lib/auth";

export default auth((req) => {
  if (!req.auth && req.nextUrl.pathname.startsWith("/dashboard")) {
    const loginUrl = new URL("/api/auth/signin", req.url);
    return Response.redirect(loginUrl);
  }
});

export const config = {
  matcher: ["/dashboard/:path*"],
};

Step 8: Access User Roles and Permissions

Calimatic Identity includes roles in the OIDC token. Access them in the JWT callback:

callbacks: {
  async jwt({ token, profile }) {
    if (profile) {
      token.roles = profile.roles ?? [];
    }
    return token;
  },
  async session({ session, token }) {
    session.user.roles = token.roles;
    return session;
  },
},

Now you can check roles anywhere in your app:

const session = await auth();
const isAdmin = session?.user.roles.includes("admin");

What's Next

This guide covers the basics of connecting Next.js to Calimatic Identity. For more advanced scenarios, check our documentation:

• Multi-tenant routing — Route users to the correct organization based on their email domain
• API route protection — Validate tokens on API routes
• Role-based UI rendering — Show/hide components based on permissions
• Token refresh — Handle token expiration gracefully

Calimatic Identity's OIDC server is fully standards-compliant, so any OAuth2/OIDC library will work. NextAuth.js is just one option — you can also use openid-client, passport, or any other library you prefer.