Keycloak Integration Guide

This comprehensive guide will walk you through setting up Keycloak for authentication in your Oversight platform.

Overview

Keycloak is an open-source Identity and Access Management solution that provides:

Single Sign-On (SSO)
Identity brokering and social login
User federation
Client adapters
Admin console and account management

Installation

Step 1: Download and Run Keycloak

Visit Keycloak Docker Registry and find the latest stable version.

# Pull and run Keycloak 26.5.2
docker run -d -p 8080:8080 --name keycloak \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.5.2 start-dev

Step 2: Access Keycloak

Open your browser and navigate to: http://localhost:8080

Login with default credentials:

Username: admin
Password: admin

Configuration

Step 3: Create a Realm

Important: Do NOT use the ‘master’ realm for your applications. Create a dedicated realm.

Click on the realm dropdown (top-left corner)
Click Create Realm
Set realm name: oversight
Click Create

Step 4: Create a Client

Clients are applications that will use Keycloak for authentication.

Navigate to Clients → Create client

General Settings

Client ID: oversight-app
Client type: OpenID Connect
Click Next

Capability Configuration

Client authentication: ❌ OFF (for public clients)
Standard flow: ✅ ON (OAuth 2.0 Authorization Code Flow)
Implicit flow: ❌ OFF (deprecated)
Direct access grants: ✅ ON (Resource Owner Password Credentials)
PKCE: Optional (can enable for enhanced security)
Click Next

Root URL: http://localhost:3002
Home URL: http://localhost:3002
Valid Redirect URIs: http://localhost:3002/*
Valid Post Logout Redirect URIs: http://localhost:3002/*
Web Origins: http://localhost:3002
Click Save

Step 5: Restart Keycloak

docker restart keycloak

Application Integration

React Application Setup

Prerequisites

npm install keycloak-js@26.2.2

Step 1: Create Environment Variables

Create a .env file in your React application directory:

cd your-app-directory
touch .env

Add the following variables to .env:

REACT_APP_KEYCLOAK_URL=http://localhost:8080
REACT_APP_KEYCLOAK_REALM=oversight
REACT_APP_KEYCLOAK_CLIENT_ID=oversight-app

Step 2: Create KeycloakService.js

Create a file src/KeycloakService.js:

import Keycloak from "keycloak-js";
 
const keycloak = new Keycloak({
  url: process.env.REACT_APP_KEYCLOAK_URL,
  realm: process.env.REACT_APP_KEYCLOAK_REALM,
  clientId: process.env.REACT_APP_KEYCLOAK_CLIENT_ID,
});
 
const initKeycloak = () =>
  keycloak.init({
    onLoad: "login-required",
    checkLoginIframe: false,
  });
 
export { keycloak, initKeycloak };

Step 3: Update App.js

import { useEffect, useState } from "react";
import { initKeycloak, keycloak } from "./KeycloakService";
 
function App() {
  const [ready, setReady] = useState(false);
 
  useEffect(() => {
    initKeycloak()
      .then(() => {
        setReady(true);
        console.log("Keycloak initialized successfully");
      })
      .catch(err => {
        console.error("Keycloak init failed", err);
      });
  }, []);
 
  if (!ready) return <div>Loading authentication...</div>;
 
  return (
    <div>
      <h1>Welcome, {keycloak.tokenParsed?.preferred_username}!</h1>
      <button onClick={() => keycloak.logout()}>Logout</button>
    </div>
  );
}
 
export default App;

Step 4: Update index.js

import ReactDOM from "react-dom/client";
import App from "./App";
 
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

Important: Do NOT use React.StrictMode when integrating Keycloak as it can cause double-initialization issues.

Clean Restart Procedure

If you encounter authentication issues, follow this clean restart procedure:

Stop React Server (Ctrl+C in terminal)
Close all browser windows
Clear browser data:
- Cookies
- localStorage
- sessionStorage
Restart Keycloak:
```
docker restart keycloak
```
Start React Server:
```
npm run dev
```
Open fresh browser window: http://localhost:3002

Advanced Configuration

User Management

Create Users

Navigate to Users → Add user
Fill in user details
Click Create
Go to Credentials tab
Set password and disable “Temporary”

Create Roles

Navigate to Realm roles → Create role
Define role name (e.g., admin, user, analyst)
Assign roles to users

Enable login with Google, GitHub, or other providers:

Navigate to Identity Providers
Select provider (e.g., Google)
Enter Client ID and Secret from provider
Configure redirect URIs

User Federation

Connect to existing user directories:

Navigate to User Federation
Select provider (LDAP, Active Directory, etc.)
Configure connection details

Custom Themes

Customize the login page appearance:

Create custom theme files
Place in Keycloak themes directory
Select theme in realm settings

Integration with Other Oversight Components

DataHub Integration

Configure DataHub to use Keycloak for SSO:

# datahub.properties
auth.oidc.enabled=true
auth.oidc.clientId=oversight-app
auth.oidc.clientSecret=your-client-secret
auth.oidc.discoveryUri=http://localhost:8080/realms/oversight/.well-known/openid-configuration

Langfuse Integration

Configure Langfuse to use Keycloak:

NEXTAUTH_URL=http://localhost:3000
AUTH_PROVIDER=keycloak
AUTH_KEYCLOAK_ID=oversight-app
AUTH_KEYCLOAK_SECRET=your-client-secret
AUTH_KEYCLOAK_ISSUER=http://localhost:8080/realms/oversight

Troubleshooting

Issue: Redirect URI Mismatch

Solution: Ensure all redirect URIs in Keycloak match your application URLs exactly.

Issue: CORS Errors

Solution: Add your application origin to the “Web Origins” field in client settings.

Issue: Token Expired

Solution: Implement token refresh logic:

// Refresh token before expiry
setInterval(() => {
  keycloak.updateToken(70).catch(() => {
    console.log('Failed to refresh token');
  });
}, 60000); // Check every minute

Solution: Remove React.StrictMode from your application.

Security Best Practices

Use HTTPS in production
Enable PKCE for public clients
Set short token lifespans
Implement refresh token rotation
Use strong admin passwords
Enable brute force detection
Regular security updates
Audit logs monitoring

Production Deployment

For production deployment:

# Use production-ready configuration
docker run -d \
  --name keycloak \
  -p 8443:8443 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=<strong-password> \
  -e KC_HOSTNAME=auth.yourdomain.com \
  -e KC_HTTPS_CERTIFICATE_FILE=/path/to/cert.pem \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/path/to/key.pem \
  -v /path/to/certs:/opt/keycloak/conf/certs \
  quay.io/keycloak/keycloak:26.5.2 start

Resources

Next Steps

Keycloak - Authentication Langfuse Setup