@kingspanisoeste/keycloak-auth

This library aims to simplify the integration of Keycloak with NextJS applications. It provides a basic interface, provider and server actions to help you manage the authentication and authorization of applications

Keycloak configuration

Client configuration

• The client must use the implicit flow configuration to work with this library.
• The client must have the following scopes:
  • openid
  • profile
  • department

Installation

npm install @kingspanisoeste/keycloak-auth

Usage

1. Create a .env file

Create a .env file in the root of your project and add the following variables:

AUTH_SECRET=your-secret-key
AUTH_MAX_AGE=time-in-seconds
NEXT_PUBLIC_KEYCLOAK_URL=https://your-keycloak-url
NEXT_PUBLIC_KEYCLOAK_REALM=your-realm
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=your-client-id

2. Create a wrapper provider

Create a provider to wrap your application with the AuthProvider component. The AuthProvider component will manage the authentication and authorization of the application.

// providers.tsx
"use client";

import { AuthProviderProps, LoadingPage, AuthProvider as SessionProvider, useAuth } from "@kingspanisoeste/keycloak-auth";
import * as serverActions from "@kingspanisoeste/keycloak-auth/server";
import { PropsWithChildren, Suspense, useEffect, useState } from "react";

const keycloakConfig = {
  url: process.env.NEXT_PUBLIC_KEYCLOAK_URL!,
  realm: process.env.NEXT_PUBLIC_KEYCLOAK_REALM!,
  clientId: process.env.NEXT_PUBLIC_KEYCLOAK_CLIENT_ID!,
};

export function AuthProvider({ children }: PropsWithChildren) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, [])

  if (!mounted) {
    return <LoadingPage />
  }

  const authProviderProps: Omit<AuthProviderProps, "children"> = {
    config: keycloakConfig,
    profile: (
      { username, firstName, lastName, email },
      { realm_access, resource_access, sub },
    ) => {
      return {
        id: sub,
        username,
        firstName,
        lastName,
        email,
        realm_access,
        resource_access,
      };
    },
    serverActions
  };

  return (
    <SessionProvider {...authProviderProps}>
      <AuthGate>
        <Suspense>{children}</Suspense>
      </AuthGate>
    </SessionProvider>
  );
}


function AuthGate({ children }: PropsWithChildren) {
  const { authenticated, profile } = useAuth();

  if (!authenticated || !profile) {
    return <LoadingPage />;
  }

  return <>{children}</>;
}

3. Create a login callback page

Create a page to handle the login callback from Keycloak. This page will be used to redirect the user to the application after the login process is completed.

// app/auth/callback/page.tsx
import { CallbackPage } from "@kingspanisoeste/keycloak-js";

export default CallbackPage;

4. Use on server side

Create a server side page to get the user profile from the server side. This page will be used to get the user profile from the server side.

import { useServerAuth } from "@kingspanisoeste/keycloak-js/server";
import Link from "next/link";

export default async function Page() {
  const { profile } = await useServerAuth();
  return (
    <div>
      Page {profile?.username}
      <Link href={"/"}>Home</Link>
    </div>
  );
}

5. Use on client side

Create a client side page to get the user profile from the client side. This page will be used to get the user profile from the client side.

"use client";

import {useAuth} from "@kingspanisoeste/keycloak-js";
import Link from "next/link";

export default function Page() {
    const {profile} = useAuth();

   return (
    <div>
      Page {profile?.username}
      <Link href={"/"}>Home</Link>
    </div>
  );
}

Public Routes

To configure public routes, you can use the publicRoutes prop in the AuthProvider component.

// providers.tsx

const authProviderProps: Omit<AuthProviderProps, "children"> = {
    config: keycloakConfig,
    profile: (
      { username, firstName, lastName, email },
      { realm_access, resource_access, sub },
    ) => {
      return {
        id: sub,
        username,
        firstName,
        lastName,
        email,
        realm_access,
        resource_access,
      };
    },
    serverActions,
    publicRoutes: ["/public"],
  };

Custom scopes

To configure custom scopes, you can use the scopes prop in the AuthProvider component.

// providers.tsx

const authProviderProps: Omit<AuthProviderProps, "children"> = {
    config: keycloakConfig,
    profile: (
      { username, firstName, lastName, email },
      { realm_access, resource_access, sub },
    ) => {
      return {
        id: sub,
        username,
        firstName,
        lastName,
        email,
        realm_access,
        resource_access,
      };
    },
    serverActions,
    scopes: ["custom-scope"],
  };