@qavren/auth-next

Thin Auth.js v5 wrapper for Qavren (Keycloak) realms. One call wires the Keycloak provider for a realm as a public client (PKCE, no client secret) and surfaces the realm roles on the session.

Install

npm install @qavren/auth-next next-auth@beta

Use

// auth.ts
import { createAuth } from "@qavren/auth-next";

export const { handlers, auth, signIn, signOut } = createAuth({
  realm: "squarelog",
  // baseUrl defaults to QAVREN_AUTH_URL, then https://auth.qavrensolutions.com
});

// app/api/auth/[...nextauth]/route.ts
export { GET, POST } from "@/auth";

// anywhere server-side
const session = await auth();
session?.user.roles; // string[] from realm_access.roles

Convention (shared by all Qavren SDKs)

• Base URL: baseUrl param, else QAVREN_AUTH_URL, else https://auth.qavrensolutions.com.
• Issuer: {base}/realms/{realm}. Client ID: {realm}-web.
• Public client: no client secret; token_endpoint_auth_method: "none". PKCE plus the realm's redirect-URI allow-list carry the security.
• Roles: realm roles are read from the access token's realm_access.roles -- where Keycloak's default realm-roles mapper writes them -- unioned with any roles a custom ID-token mapper surfaces on the profile, then exposed as session.user.roles (typed via module augmentation this package ships). Reading the ID-token profile alone yields [] under the default Keycloak mapper config, so the access token is the source of truth.

Composition

createAuth accepts any NextAuthConfig override alongside realm/baseUrl (e.g. pages, extra callbacks). buildAuthConfig is also exported for callers who want the config object without instantiating NextAuth.

Scope of tests

This package's tests are unit-level: they assert the produced Auth.js config (issuer, public client id, no secret, PKCE, role callbacks). The end-to-end browser login flow against a live Keycloak is exercised by the demo app (Plan 03), not here.

Install

npm install @qavren/auth-next