Passport Keycloak Bearer Strategy

Common errors

• Error: bearer token not found

  cause The incoming HTTP request does not contain an `Authorization` header with a `Bearer` token, or the token is malformed.
  fix Ensure the client is sending a request with an `Authorization: Bearer <your_jwt_token>` header. Verify the token format and that it's present in the request.

• JsonWebTokenError: invalid algorithm

  cause The JWT token's signing algorithm does not match any of the algorithms specified in the `algorithms` option passed to `KeycloakBearerStrategy`.
  fix Check the `alg` header in your JWT token and ensure it's included in the `algorithms` array option when initializing `KeycloakBearerStrategy`. For Keycloak, this is typically `RS256` or `PS256` for production environments.

• TokenExpiredError: jwt expired

  cause The provided JWT bearer token has exceeded its `exp` (expiration) claim and is no longer valid, and `ignoreExpiration` is not set to `true`.
  fix Obtain a new, valid (unexpired) JWT token from Keycloak. Implement a token refresh mechanism on the client side to proactively renew tokens before they expire. If strictly necessary for testing, set `ignoreExpiration: true` (with caution).

Warnings

• breaking Older versions (pre-2.x) of `passport-keycloak-bearer` might have different constructor signatures or option configurations. Always consult the specific version's README for exact usage, especially when upgrading across major versions.
  Fix: Refer to the documentation for the specific major version you are targeting. Upgrade to the latest stable version and adapt your code as per the new API.
• gotcha The `url` and `realm` options are critically important and must accurately point to your Keycloak server and specific realm. Misconfigurations here will lead to failed token validation or inability to retrieve public keys.
  Fix: Double-check `url` and `realm` against your Keycloak server's configuration. Ensure the URL points to the base authentication endpoint (e.g., `https://keycloak.dev.org/auth`) and not directly to realm-specific endpoints or token URLs.
• gotcha By default, `passport-keycloak-bearer` validates the token's expiration. If `ignoreExpiration` is set to `true` (which is generally discouraged in production for security reasons), expired tokens will still be accepted.
  Fix: Avoid setting `ignoreExpiration: true` in production environments. Ensure your client applications handle token refreshing proactively before expiration. If you must ignore expiration (e.g., for specific testing), understand the security implications.
• gotcha The `verify` callback is responsible for determining if a user is successfully authenticated and what user object should be attached to `req.user`. Incorrectly calling `done(null, false)` or `done(error)` can lead to unexpected authentication failures or errors.
  Fix: Always ensure your `verify` callback calls `done(null, user)` for a successful authentication, `done(null, false)` for failed authentication (e.g., invalid credentials or insufficient roles), and `done(error)` for an error during verification (e.g., database lookup failure). Review Passport's documentation for `done` callback patterns.

Install

• npm install passport-keycloak-bearer npm
• yarn add passport-keycloak-bearer yarn
• pnpm add passport-keycloak-bearer pnpm

Imports

• KeycloakBearerStrategy
  wrong:

  import { KeycloakBearerStrategy } from 'passport-keycloak-bearer'

  correct:

  import KeycloakBearerStrategy from 'passport-keycloak-bearer'

  The strategy is exported as a default export, not a named export. It should be imported directly.
• passport
  wrong:

  const passport = require('passport')

  correct:

  import passport from 'passport'

  While CommonJS `require` still works in Node.js, modern projects typically use ESM imports. Passport itself is commonly imported as a default export.
• Strategy Options (Type)

  import type { IKeycloakBearerStrategyOptions } from 'passport-keycloak-bearer'

  For TypeScript users, import type definitions for options to ensure type safety without bundling the actual strategy code.

Quickstart

This quickstart demonstrates how to set up an Express application with Passport.js and `passport-keycloak-bearer` to protect an API endpoint. It initializes the strategy with Keycloak URL and realm, defines a `verify` callback to process the JWT payload and attach a user object to `req.user`, and uses `passport.authenticate` middleware to secure a route.

import express from 'express';
import passport from 'passport';
import KeycloakBearerStrategy from 'passport-keycloak-bearer';

const app = express();

// --- IMPORTANT: Replace with your actual Keycloak configuration ---
const KEYCLOAK_URL = process.env.KEYCLOAK_AUTH_URL ?? 'https://your-keycloak-instance.com/auth';
const KEYCLOAK_REALM = process.env.KEYCLOAK_REALM ?? 'your-realm';
// ------------------------------------------------------------------

passport.use(new KeycloakBearerStrategy({
    url: KEYCLOAK_URL,
    realm: KEYCLOAK_REALM,
    passReqToCallback: false // Set to true if your verify callback needs the request object
}, (jwtPayload, done) => {
    // In a real application, you would fetch user details from a DB
    // or create a user object based on the JWT payload (e.g., jwtPayload.sub)
    const user = { id: jwtPayload.sub, username: jwtPayload.preferred_username, roles: jwtPayload.realm_access?.roles };
    
    // Example: only allow users with 'api-user' role
    if (user.roles && user.roles.includes('api-user')) {
      return done(null, user); // User authenticated successfully
    } else {
      return done(null, false, { message: 'User does not have required roles.' }); // Authentication failed
    }
}));

app.use(passport.initialize());

// A protected route
app.get('/api/protected', passport.authenticate('keycloak-bearer', { session: false }), (req, res) => {
    // req.user will contain the user object returned from the verify callback
    res.json({ message: 'Access granted!', user: req.user });
});

// Public route
app.get('/api/public', (req, res) => {
    res.json({ message: 'This is a public endpoint.' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
    console.log(`Test with curl -H "Authorization: Bearer <YOUR_KEYCLOAK_JWT_TOKEN>" http://localhost:${PORT}/api/protected`);
});