How to Use Keycloak with Node.js

Keycloak is a powerful open-source identity and access management solution that offers robust security features for your applications. Integrating Keycloak with Node.js can provide a secure authentication and authorization system. Here's a guide to help security experts use Keycloak with Node.js.

Set Up a Realm

Once Keycloak is installed, you need to set up a realm. A realm is a security domain where your applications and users reside. To create a realm, access the Keycloak administration console and follow the steps below:

1. Log in to the Keycloak administration console using the admin credentials.
2. Click on the "Add realm" button and provide a name for your realm.
3. Configure other settings according to your requirements, such as token lifespan, password policies, etc.
4. Save the realm configuration.

Create a Client

After setting up the realm, you need to create a client for your Node.js application. The client represents your application within the Keycloak realm. To create a client, follow these steps:

1. In the Keycloak administration console, navigate to the "Clients" section within your realm.
2. Click on the "Create" button to add a new client.
3. Provide a name for your client and select the appropriate client protocol (e.g., OpenID Connect).
4. Configure other settings as per your application requirements.
5. Save the client configuration.

Install the express-openid-connect Package

To integrate Keycloak into your Node.js application, you need to install the express-openid-connect package. Open your terminal and navigate to your project's directory. Run the following command to install the package:

npm install express-openid-connect

Set Up Authentication Middleware

In your Node.js application, you need to set up authentication middleware to handle user authentication. Import the necessary modules and configure the Keycloak middleware as follows:

const express = require('express');
const app = express();
const { auth } = require('express-openid-connect');

const config = {
  issuerBaseURL: 'http://localhost:8080/auth/realms/your-realm',
  clientID: 'your-client-id',
  baseURL: 'http://localhost:3000',
  secret: 'your-client-secret',
};

app.use(auth(config));

Replace 'http://localhost:8080/auth/realms/your-realm', 'your-client-id', and 'your-client-secret' with your actual Keycloak realm URL, client ID, and client secret, respectively.

Protect Routes

Once the authentication middleware is set up, you can protect specific routes in your application by adding the auth middleware to the route definition. For example:

const { requiresAuth } = require('express-openid-connect');

app.get('/protected-route', requiresAuth(), (req, res) => {
  res.send('This is a protected route');
});

This ensures that only authenticated users can access the protected route.

User Data

To access user data, you can use the req.oidc.user object, which contains information about the authenticated user. For example, to display the user's name on a page, you can use:

app.get('/profile', requiresAuth(), (req, res) => {
  const { name } = req.oidc.user;
  res.send(`Hello, ${name}!`);
});

Handle Logout

To handle user logout, you can add a route that triggers the logout process. For example:

app.get('/logout', (req, res) => {
  req.logout();
  res.redirect('/');
});

Test the Integration

At this point, your Node.js application is integrated with Keycloak. You can now test the integration by accessing the protected route defined in your application. When accessing the protected route, Keycloak will handle the authentication process and grant access only to authenticated users.

Congratulations! You have successfully integrated Keycloak with your Node.js application. Now, you can leverage Keycloak's security features, such as role-based access control, single sign-on, and more, to enhance the security of your application.

---