@skylab-kulubu/inscribed-auth

Skylab's opt-in NextAuth + Keycloak adapter for the inscribed CMS.

inscribed is auth- and vendor-neutral: out of the box it runs read-only/public. This package is the Skylab layer that plugs admin auth and the build-time service token into it, so a new Skylab Next.js app gets editing + sync by installing one package and setting env vars — no hand-copied auth files.

It ships two seam adapters:

| Seam | What this package provides | | --- | --- | | Auth | NextAuth options (JWT access/refresh persistence, silent refresh, Keycloak client- and realm-role extraction), the withCmsAuth adapter, the NextAuthCmsProvider client wrapper, and a one-route auto-signin handler. | | Service token | Keycloak client-credentials token for SSR content fetch + the cms-sync CLI. |

Transport is not provided — Skylab uses inscribed's default REST transport.

Install

npm install @skylab-kulubu/inscribed-auth

Peer dependencies (you already have most in a Next app):

npm install inscribed next next-auth@^4 react react-dom

Keep the app CommonJS (do not set "type": "module" in the app's package.json). next-auth v4's Keycloak provider only resolves through Webpack's CJS/ESM interop; an ESM app breaks it. The one exception is cms.config.mjs below, which is .mjs on purpose.

Entry points

| Import | Use from | Exports | | --- | --- | --- | | @skylab-kulubu/inscribed-auth | Client ("use client") | NextAuthCmsProvider | | @skylab-kulubu/inscribed-auth/server | Server only | createCmsAuthOptions, withCmsAuth, isCmsAdmin, readCmsAuthMeta, getClientCredentialsToken, debugServiceTokenClaims | | @skylab-kulubu/inscribed-auth/signin | Server route | GET, createSignInRoute | | @skylab-kulubu/inscribed-auth/config | cms-sync CLI / build-time | getServiceToken, onSyncError |

Wiring (the five files + env)

lib/auth.js — NextAuth options

The Keycloak provider instance stays here, on your side — never let it be bundled by a dependency, or it resolves to undefined at runtime.

import KeycloakProvider from "next-auth/providers/keycloak";
import { createCmsAuthOptions } from "@skylab-kulubu/inscribed-auth/server";

export const authOptions = createCmsAuthOptions({
  provider: KeycloakProvider({
    clientId: process.env.KEYCLOAK_CLIENT_ID ?? "",
    clientSecret: process.env.KEYCLOAK_CLIENT_SECRET ?? "",
    issuer: process.env.KEYCLOAK_ISSUER ?? "",
  }),
  adminRole: "cms:access", // Keycloak client role gating admin access (default)
});

By default createCmsAuthOptions also:

• sets pages.signIn to /api/signin so every sign-in redirect (including the silent re-auth after a token refresh fails) jumps straight into Keycloak instead of NextAuth's "Sign in with X" picker. Mount that route (next file) for it to work, or pass signInPage: false to keep the built-in picker.
• ends the Keycloak SSO session on sign-out (RP-initiated logout via id_token_hint), so signing out of the app also signs the user out of Keycloak — otherwise the next visit silently re-authenticates against the still-live SSO session.

app/api/auth/[...nextauth]/route.js — NextAuth handler

import NextAuth from "next-auth";
import { authOptions } from "../../../../lib/auth.js";

const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };

app/api/signin/route.js — one-click sign-in

/api/signin?callbackUrl=... jumps straight into the Keycloak flow, skipping NextAuth's provider-picker page. createCmsAuthOptions wires this as the default pages.signIn, so NextAuth sends unauthenticated users here automatically; you can also link to it from anywhere (<a href="/api/signin">). Mount it — with signInPage defaulting to /api/signin, sign-in 404s if this route is missing (or set signInPage: false).

export { GET } from "@skylab-kulubu/inscribed-auth/signin";

The page shows an animated Skylab loader and, if sign-in hasn't completed after 10 s (slow network, or a strict CSP that blocks the inline script), reveals a "continue to sign in" link so the user is never stuck. Its theming auto-adapts to light/dark (system canvas in light, a warm near-black #1c1815 in dark). Being a standalone document it can't read your app's CSS, so pass concrete values to match:

import { createSignInRoute } from "@skylab-kulubu/inscribed-auth/signin";

// background/color accept any CSS value (hex, rgb, gradient); the loader and
// text are drawn in `color`.
export const GET = createSignInRoute({ background: "#0b1020", color: "#e5e7eb" });

lib/cms.jsx — the CMS page factory

import { revalidateCmsSlug } from "inscribed/actions";
import { createCmsPage } from "inscribed/page";
import { NextAuthCmsProvider } from "@skylab-kulubu/inscribed-auth";
import { withCmsAuth, getClientCredentialsToken } from "@skylab-kulubu/inscribed-auth/server";

import { authOptions } from "./auth.js";

export const CmsPage = createCmsPage({
  Provider: NextAuthCmsProvider,
  config: {
    baseUrl: process.env.CMS_URL ?? "http://localhost:5000",
    cdnUrl: process.env.CMS_CDN_URL,
  },
  // Service token for the public SSR content fetch (no session required).
  getServiceToken: getClientCredentialsToken,
  // Adapts NextAuth into inscribed's auth-agnostic callbacks
  // (getSession / deriveAdmin / deriveUserSub).
  ...withCmsAuth(authOptions),
  // Must come through inscribed's `actions` entry so its "use server"
  // directive survives bundling.
  onAfterSave: revalidateCmsSlug,
});

cms.config.mjs — cms-sync CLI wiring (project root, .mjs)

The CLI is plain Node and import()s this file. One line:

export { getServiceToken, onSyncError } from "@skylab-kulubu/inscribed-auth/config";

.env.local

# Keycloak (same client serves login + client_credentials sync)
KEYCLOAK_CLIENT_ID=<your-client-id>
KEYCLOAK_CLIENT_SECRET=<your-client-secret>
KEYCLOAK_ISSUER=https://<keycloak-host>/realms/<realm>

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<run: openssl rand -base64 32>

# CMS backend
CMS_URL=https://<your-cms-host>
# Optional:
# CMS_CDN_URL=https://<your-cdn-host>

| Var | Required | Purpose | | --- | --- | --- | | KEYCLOAK_CLIENT_ID | ✅ | Keycloak client (both grants) | | KEYCLOAK_CLIENT_SECRET | ✅ | Client secret | | KEYCLOAK_ISSUER | ✅ | Realm issuer URL | | NEXTAUTH_URL | ✅ | App base URL for NextAuth | | NEXTAUTH_SECRET | ✅ | NextAuth JWT/session secret | | CMS_URL | ✅ | inscribed backend base URL (→ config.baseUrl) | | CMS_CDN_URL | — | Asset CDN base (→ config.cdnUrl) |

Session shape

createCmsAuthOptions augments the NextAuth session with these fields (on top of NextAuth's defaults):

const session = await getServerSession(authOptions); // server
// or useSession() on the client

session.accessToken;        // string — the raw Keycloak access token
session.user.id;            // string — Keycloak subject (`sub`)
session.user.clientRoles;   // string[] — roles aggregated across every client
                            //   in `resource_access` (includes `cms:access`)
session.user.realmRoles;    // string[] — `realm_access.roles` (realm-wide roles)

Both role arrays are extracted from the access token on sign-in and re-extracted on every silent refresh, and default to [] (never undefined). Use clientRoles for resource-server permissions like cms:access (see below) and realmRoles for realm-wide roles. For admin gating specifically, prefer isCmsAdmin(session, meta) / withCmsAuth over checking the arrays by hand.

Admin access

Admin operations require the cms:access Keycloak client role, both for the logged-in user (admin UI) and the service account (sync). The role belongs to the inscribed backend's Keycloak client (the resource server, e.g. skycms) — not the frontend login client (KEYCLOAK_CLIENT_ID). As long as the backend client is mapped into the token audience, the role rides along under resource_access["<backend-client>"]; the SDK reads roles from every client in resource_access, so it doesn't matter that the role isn't keyed under the frontend client / token azp.

Grant the backend client's cms:access role to each principal in Keycloak Admin:

• Admin users → Users → <user> → Role mapping → assign cms:access
• Service account (sync) → Clients → KEYCLOAK_CLIENT_ID → Service account roles → assign cms:access

If sync still returns 403, onSyncError dumps the service token's azp / aud / resource_access claims and reports which client (if any) actually holds cms:access.

License

MIT © Skylab Kulübü — see LICENSE.

Uses inscribed (LGPL-3.0-or-later) as a peer dependency (not bundled); that license governs inscribed itself, not this adapter.