Welcome, ${req.kauth.grant.access_token.content.preferred_username ?? 'user'}!
`);\n});\n\napp.get('/login', keycloak.protect(), (req, res) => {\n res.send('You should be redirected to Keycloak for login, then back here if successful.');\n});\n\n// Error handling for Keycloak\napp.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {\n if (err && err.name === 'UnauthorizedError') {\n return res.status(401).send('Unauthorized');\n }\n next(err);\n});\n\nconst PORT = process.env.PORT ?? 3000;\napp.listen(PORT, () => {\n console.log(`Server running on http://localhost:${PORT}`);\n console.log('Ensure Keycloak is running and configured with a client named \\'my-express-app\\'.');\n});","lang":"typescript","description":"This quickstart demonstrates setting up `keycloak-connect` with an Express application, showing how to protect routes, configure session management, and handle basic authentication flows with a Keycloak server. It uses environment variables for sensitive Keycloak configuration."},"warnings":[{"fix":"Begin planning migration to a generic OpenID Connect client library for Node.js (e.g., `openid-client`) and integrate it directly with your application's authentication flow, or explore other Keycloak-maintained solutions if they become available.","message":"The `keycloak-connect` package is officially deprecated by the Keycloak project. It will be removed in the future, and users are strongly advised to migrate to alternative integration methods, likely involving generic OpenID Connect client libraries.","severity":"deprecated","affected_versions":">=26.0.0"},{"fix":"Ensure `express-session` is installed and configured with a persistent `store` option (e.g., `MemoryStore` for development, `connect-mongo`, `connect-redis` for production) and passed to the `Keycloak` constructor: `new Keycloak({ store: sessionStore }, config)`.","message":"Keycloak Connect requires a session store for proper operation, typically `express-session` with a compatible store. Without a properly configured and shared session store, authentication flows (like redirect after login) will fail or users will not maintain their authenticated state.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always consult the specific Keycloak documentation for the version of the server you are using and the corresponding `keycloak-connect` adapter version. Pay close attention to the client registration in Keycloak and its mirroring in your `keycloak-connect` configuration.","message":"Configuration structure and initialization might have subtle changes between major Keycloak versions and corresponding adapter versions. For instance, the expected content of `keycloak.json` or inline configuration objects can vary, especially regarding public vs. confidential clients and SSL settings.","severity":"breaking","affected_versions":">=20.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `keycloak.protect()` is invoked as middleware for routes requiring authentication (e.g., `app.get('/protected', keycloak.protect(), (req, res) => { ... })`). Also verify `express-session` and the Keycloak middleware are correctly initialized and ordered before protected routes.","cause":"`keycloak.protect()` middleware was not applied to the route, or the session was not correctly initialized, leading to `req.kauth` being undefined.","error":"TypeError: Cannot read properties of undefined (reading 'grant')"},{"fix":"Initialize `keycloak-connect` with an `express-session` compatible store: `const memoryStore = new session.MemoryStore(); const keycloak = new Keycloak({ store: memoryStore }, keycloakConfig);`","cause":"The `Keycloak` constructor was called without providing a `store` option, or the provided store was invalid.","error":"Error: `keycloak-connect` must be initialized with a session store."},{"fix":"Check your Keycloak client configuration in the Keycloak admin console. Ensure the 'Valid Redirect URIs' for your client includes the exact URL that Keycloak should redirect back to after successful authentication (e.g., `http://localhost:3000/*`). Also, verify the `auth-server-url` in your `keycloak-connect` config is correct.","cause":"The application is redirecting to the Keycloak authentication server, but the redirect might not be working as expected or the client configuration in Keycloak is incorrect (e.g., invalid redirect URIs).","error":"GET /protected 302 -"}],"ecosystem":"npm","meta_description":null}