passport-keycloak-oauth2-oidc-portable

Passport strategy for authenticating with Keycloak using OAuth2/OIDC.

Table of Contents

1. Why I Did This
2. What's New
3. Installation
4. Usage
   • Create an Application
   • Configure Strategy
   • Public Client
   • Confidential Client
   • Complete Example
5. Development Environment
   • Docker Services
   • Available Scripts
6. Testing
   • Test Environment
   • Running Tests
7. Understanding PKCE
8. Additional Information
9. License

Why I Did This

The original passport-keycloak-oauth2-oidc wasn't up to date. I modernized it with improved PKCE support, standalone client examples, and TypeScript support. Check out my blog for tutorials: blog.brakmic.com.

What's New in This Fork?

• TypeScript Only: The project is now TypeScript-based, with no JavaScript code.
• PKCE Support: Full Proof Key for Code Exchange (PKCE) implementation for public clients.
• Standalone Public Client: A single self-contained example demonstrating PKCE.
• Keycloak via Docker Compose: Simplified container-based setup.

Installation

npm install passport-keycloak-oauth2-oidc-portable

pnpm add passport-keycloak-oauth2-oidc-portable

yarn add passport-keycloak-oauth2-oidc-portable

Usage

Create an Application

1. Configure your Keycloak realm
2. Create a client (public or confidential)
3. Set valid redirect URIs
4. Enable PKCE if using public client

Configure Strategy

import passport from 'passport';
import KeycloakStrategy from 'passport-keycloak-oauth2-oidc-portable';

passport.use(new KeycloakStrategy({
    clientID: 'your-client-id',
    realm: 'your-realm',
    publicClient: true,
    authServerURL: 'http://localhost:3000',
    callbackURL: 'http://localhost:3002/auth/callback',
    pkce: true,
    state: true
  },
  (accessToken, refreshToken, profile, done) => {
    return done(null, profile);
  }
));

Complete Example

import express from 'express';
import session from 'express-session';
import passport from 'passport';
import KeycloakStrategy from 'passport-keycloak-oauth2-oidc-portable';

const app = express();

app.use(session({
  secret: 'your-secret',
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: false,
    maxAge: 1000 * 60 * 60 * 24
  }
}));

app.use(passport.initialize());
app.use(passport.session());

passport.serializeUser((user, done) => done(null, user));
passport.deserializeUser((user, done) => done(null, user));

passport.use(new KeycloakStrategy({
  clientID: 'test-client',
  realm: 'TestRealm',
  publicClient: true,
  authServerURL: 'http://localhost:3000',
  callbackURL: 'http://localhost:3002/auth/callback',
  pkce: true,
  state: true
}, (accessToken, refreshToken, profile, done) => {
  return done(null, { ...profile, accessToken });
}));

app.get('/auth/keycloak', passport.authenticate('keycloak'));

app.get('/auth/callback',
  passport.authenticate('keycloak', {
    successRedirect: '/profile',
    failureRedirect: '/login',
    failureFlash: true
  })
);

app.get('/profile',
  ensureAuthenticated,
  (req, res) => {
    res.json({ user: req.user });
  }
);

function ensureAuthenticated(req, res, next) {
  if (req.isAuthenticated()) return next();
  res.redirect('/auth/keycloak');
}

app.listen(3002);

Development Environment

Docker Services

Service	Internal URL	External URL	Purpose	Ports	Networks
Keycloak	http://testcloak:8080	http://localhost:3000	Auth Server	8080, 9000	devnetwork
NGINX	http://test-proxy:8080	http://localhost:3000	Proxy	3000, 8080	devnetwork
E2E Server	http://e2e-server:4000	N/A	Protected API	4000	devnetwork
Public Client	http://localhost:3002	http://localhost:3002	Example App	3002	host

Available Scripts

Script	Purpose	Usage
setup:test-env	Start test environment	yarn setup:test-env
setup:test-env:force	Force restart environment	yarn setup:test-env:force
start:public-client	Run example client	yarn start:public-client
test:integration	Run integration tests	yarn test:integration
test:e2e	Run E2E tests	yarn test:e2e
test:unit	Run unit tests	yarn test:unit
test	Run all tests	yarn test

Testing

Test Environment

The test environment consists of:

• Keycloak server (authentication)
• NGINX proxy (routing)
• E2E server (protected resources)
• Test realm with predefined users

Running Tests

# Start environment
yarn setup:test-env

# Run specific tests
yarn test:unit
yarn test:integration
yarn test:e2e

# Run all tests
yarn test

Understanding PKCE

PKCE (Proof Key for Code Exchange) is a security extension for OAuth 2.0 used with public clients. The implementation:

1. Generates a code verifier (random string)
2. Creates a code challenge (SHA-256 hash of verifier)
3. Sends challenge with auth request
4. Sends verifier with token request

// PKCE Implementation Example
const { code_verifier, code_challenge } = generatePkcePair();
// code_verifier is stored in session
// code_challenge is sent with authorization request

Additional Information

Accessing Services

• Keycloak Admin: http://localhost:3000/admin
• Public Client: http://localhost:3002
• E2E Server: http://localhost:4000

Default Credentials

• Keycloak Admin: admin/admin
• Test User: test-user/password

License

MIT