keycloak-koa

A simple, secure Keycloak authentication library for Koa applications with TypeScript support.

Installation

npm install keycloak-koa

Quick Start

import Koa from "koa";
import Router from "koa-router";
import koaCookie from "koa-cookie";
import keycloak from "keycloak-koa";

const app = new Koa();
app.use(koaCookie());

const router = new Router();

// Initialize Keycloak
const auth = keycloak({
  keycloakUrl: "https://auth.example.com/realms/my-realm",
  clientId: "my-client",
  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
});

// Protect routes
router.get("/api/profile", auth.middleware.extractJwtToken, async (ctx) => {
  ctx.body = { user: ctx.state.user };
});

app.use(router.routes());
app.listen(3000);

Complete Example

Here's a complete example showing all the endpoints you'll need:

import Koa from "koa";
import Router from "koa-router";
import koaBody from "koa-body";
import koaCookie from "koa-cookie";
import session from "koa-session";
import keycloak from "keycloak-koa";

const app = new Koa();
app.keys = ["your-secret-key"];

app.use(koaBody());
app.use(koaCookie());
app.use(session(app));

const router = new Router();

// 1. Initialize Keycloak
const auth = keycloak({
  keycloakUrl: "https://auth.example.com/realms/my-realm",
  clientId: "my-client",
  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
});

// 2. Login endpoint - redirect users to Keycloak
router.get("/login", async (ctx) => {
  const redirectUri = `${ctx.protocol}://${ctx.host}/auth/callback`;

  // Generate a random state for CSRF protection
  const state = auth.generateRandomState();
  ctx.session.authState = state; // Store in session

  // Use the helper to generate the auth URL
  const authUrl = auth.getAuthUrl(redirectUri, { state });
  ctx.redirect(authUrl);
});

// 3. Callback endpoint - handle the code from Keycloak
router.get("/auth/callback", async (ctx) => {
  try {
    const { code, state } = ctx.query;

    // Verify state parameter to prevent CSRF attacks
    if (state !== ctx.session.authState) {
      return ctx.redirect("/login?error=invalid_state");
    }

    const redirectUri = `${ctx.protocol}://${ctx.host}/auth/callback`;

    // Exchange code for tokens and set cookies
    const { user } = await auth.handleTokenExchange(
      code as string,
      redirectUri,
      ctx
    );

    // Redirect to the application
    ctx.redirect("/dashboard");
  } catch (error) {
    console.error("Authentication error:", error);
    ctx.redirect("/login?error=auth_failed");
  }
});

// 4. Protected API routes
router.get("/api/profile", auth.middleware.extractJwtToken, async (ctx) => {
  ctx.body = {
    user: ctx.state.user,
    message: "This is a protected endpoint",
  };
});

// 5. Logout endpoint
router.get("/logout", async (ctx) => {
  auth.logout(ctx);

  // Use the helper to generate the logout URL
  const redirectUri = `${ctx.protocol}://${ctx.host}`;
  const logoutUrl = auth.getLogoutUrl(redirectUri);

  ctx.redirect(logoutUrl);
});

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

API Reference

keycloak(options)

Initializes the Keycloak integration with your configuration.

Options:

• keycloakUrl (required): Keycloak server URL with realm
• clientId (required): Your application's client ID
• clientSecret (required for confidential clients): Client secret

Returns an object with:

• middleware.extractJwtToken: Middleware to protect routes
• handleTokenExchange(code, redirectUri, res): Helper to exchange code for tokens
• logout(res): Helper to clear auth cookies
• getAuthUrl(redirectUri, options): Helper to generate Keycloak authorization URL
• getLogoutUrl(redirectUri, options): Helper to generate Keycloak logout URL
• generateRandomState(length): Helper to generate random state for CSRF protection

URL Helper Functions

These functions are also available directly from the module:

getAuthUrl(options)

Generates a Keycloak authorization URL.

const { getAuthUrl } = require("keycloak-koa");

const authUrl = getAuthUrl({
  keycloakUrl: "https://auth.example.com/realms/my-realm",
  clientId: "my-client",
  redirectUri: "https://myapp.com/callback",
  scope: "openid profile email",
  state: "random-state-string",
  prompt: "login", // Force login even if already authenticated
});

getLogoutUrl(options)

Generates a Keycloak logout URL.

const { getLogoutUrl } = require("keycloak-koa");

const logoutUrl = getLogoutUrl({
  keycloakUrl: "https://auth.example.com/realms/my-realm",
  redirectUri: "https://myapp.com/logged-out",
  idTokenHint: "optional-id-token",
});

generateRandomState(length)

Generates a random string for CSRF protection.

const { generateRandomState } = require("keycloak-koa");

const state = generateRandomState(32); // Default length is 32

Security Features

• HTTP-only cookies prevent JavaScript access to tokens
• Automatic token verification using Keycloak's JWKS endpoint
• Protection against token tampering and replay attacks
• Secure cookie settings with sameSite and secure flags

License

MIT