Skip to main content

Keycloak Setup Guide

How to install and configure Keycloak for LibreApps Desktop.

Overview​

Keycloak is the heart of LibreApps Desktop's security. This guide covers the basic steps to get Keycloak running and configured for your dashboard.

Installation​

The easiest way to run Keycloak is using Docker:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

Configuration Steps​

1. Create a Realm​

A realm is a space where you manage your users, roles, and clients. Create a new realm named LibreApps Desktop.

2. Create a Client​

Create a new client for LibreApps Desktop frontend:

  • Client ID: LibreApps Desktop-web
  • Client Protocol: openid-connect
  • Access Type: public
  • Valid Redirect URIs: http://localhost:3000/*

3. Define Roles​

Create the following realm roles:

  • admin: Full access to all features.
  • user: Standard access to dashboard features.
  • viewer: Read-only access.

4. Create a User​

Create a test user and assign them the user role. Ensure you set a password for the user.

Connecting LibreApps Desktop to Keycloak​

Update your frontend .env.local file:

NEXT_PUBLIC_KEYCLOAK_URL=http://localhost:8080
NEXT_PUBLIC_KEYCLOAK_REALM=LibreApps Desktop
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=LibreApps Desktop-web

Update your backend application.yml (for the Gateway and microservices):

keycloak:
  auth-server-url: http://localhost:8080
  realm: LibreApps Desktop
  resource: LibreApps Desktop-backend
  credentials:
    secret: your-client-secret

Best Practices​

  • ✅ Do this: Use a production-grade database (like PostgreSQL) for Keycloak in a real environment.
  • ✅ Do this: Enable HTTPS for all Keycloak communication.
  • ❌ Don't do this: Use the admin user for day-to-day application tasks; create specific users with limited roles.