Passport-Keycloak-Bearer is an HTTP Bearer authentication strategy designed for Passport.js, enabling Node.js applications to authenticate requests against a Keycloak identity provider using OAuth 2.0 bearer tokens. This package, currently at version 2.4.1, integrates seamlessly with Connect-style middleware frameworks like Express.js. It focuses on extracting, validating, and propagating JWT claims from access tokens to a `verify` callback, allowing developers to process user information and attach it to `req.user`. While there isn't an explicit release cadence mentioned, the versioning suggests ongoing maintenance. Its key differentiator is the direct integration with Keycloak's token validation, simplifying the setup for Keycloak-backed applications compared to generic JWT strategies that require manual configuration of Keycloak's public keys and issuer metadata.
npm install passport-keycloak-bearerVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.
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.
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.
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).