Getting Started

Let's discover Keycloak Connector in less than 15 minutes.

_{🕒 Can't wait? Run it now with Docker Quickstart.}

What you'll need

• Keycloak 16.0+
• Node.js 18.0+

Configure Keycloak

Following FAPI guidance, several changes to your Keycloak configuration may be required.

info

Changing Realm configurations may impact existing Clients if they are not similarly configured.

Realm Configuration

Sessions

• SSO Session Idle: 4 hours optional
• SSO Session Max: 1 day optional

Tokens

• Default Signature Algorithm: PS256
• Revoke Refresh Token: Enabled recommended
• Refresh token max reuse: 0 recommended
• Access Token Lifespan: 15 minutes optional

Client Configuration

Settings

• Root URL http://localhost:5000* your backend server
• Valid redirect URIs /auth/callback*
• Web origins +
• Admin URL /auth/k-admin-url*
• Client authentication On
• Authentication flow Standard flow
• Front channel logout Off

Backchannel logout URL

When running Keycloak in a Docker instance and your NodeJs server on your host machine, try: http://host.docker.internal:5000/auth/k_logout

• Backchannel logout URL http://localhost:5000/auth/k-logout
• Backchannel logout session required On

Credentials

warning

Clients must authenticate using Signed JWT (PS256) in production, Keycloak Connector will not start otherwise.

• Client Authenticator Client Id and Secret dev only
• Access token signature algorithm PS256
• ID token signature algorithm PS256
• User info signed response algorithm PS256
• Request object signature algorithm PS256
• Authorization response signature algorithm PS256
• Proof Key for Code Exchange Code Challenge Method S256

Configure Webserver

Express

server.js

import express from 'express';
import {keycloakConnectorExpress, lock} from "@dapperduckling/keycloak-connector-server";
import cookieParser from "cookie-parser"

const serverPort = 5000;

// Grab express app
const app = express();

// Register the cookie parser
app.use(cookieParser());

// Initialize keycloak connector server
await keycloakConnectorExpress(app, {
    realm: 'kcc-example',
    clientId: 'example-express-app',
    clientSecret: '***REPLACE WITH CLIENT SECRET FROM KEYCLOAK***', // Dev only
    DANGEROUS_disableJwtClientAuthentication: true, // Dev only
    fetchUserInfo: true,
    serverOrigin: `http://localhost:${serverPort}`, // This server's origin
    authServerUrl: 'http://localhost:8080',        // Your keycloak server here
});

// Register a public route on the app
app.get('/', (req, res) => {
    res.send(`Public route`);
});

// Create a new router to secure all routes behind
const router = express.Router();

// Only authentication required route
router.get('/private', (req, res) => {
    res.send(`Private route`);
});

// Lock all routes in the router behind a login page
app.use(lock(), router);

// Start the server
app.listen(serverPort, () => {
    console.log(`express :: listening at http://localhost:${serverPort}`);
});

Fastify

server.js

import Fastify from 'fastify';
import {keycloakConnectorFastify} from "@dapperduckling/keycloak-connector-server";
import cookie from '@fastify/cookie';

const serverPort = 5000;

// Configure fastify
const fastify = Fastify({
    pluginTimeout: 120_000,     // Allow for lengthy plugin initialization
});

// Add cookie support to fastify
await fastify.register(cookie);

// Initialize the keycloak connector
await fastify.register(keycloakConnectorFastify(), {
    realm: 'kcc-example',
    clientId: 'example-fastify-app',
    clientSecret: '***REPLACE WITH CLIENT SECRET FROM KEYCLOAK***', // Dev only
    DANGEROUS_disableJwtClientAuthentication: true, // Dev only
    fetchUserInfo: true,
    serverOrigin: `http://localhost:${serverPort}`, // This server's origin
    authServerUrl: 'http://localhost:8080',        // Your keycloak server here
});

// A public route
fastify.get('/', {config: {public: true}}, async () => {
    return `Public route`;
});

// Only authentication required for this route
fastify.get('/private', async () => {
    return `Private route`;
});

// Launch the server
await fastify.listen({
    port: serverPort,
    listenTextResolver: () => `Server listening at http://localhost:${serverPort}`
});

Launch the server

node server.js

Test it!

Purpose	Url
Public Route	http://localhost:5000
Private Route	http://localhost:5000/private
Login	http://localhost:5000/auth/login
Logout	http://localhost:5000/auth/logout