Configuration on GENIE.AI

Keycloak Admin Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to manage users, roles, and groups for GENIE.AI through the Keycloak admin console. Everything identity-related — sign-up, sign-in, password reset, role assignment — happens in Keycloak; no GENIE.AI-specific UI is needed for user administration.

Before proceeding: confirm KEYCLOAK_URL in your .env matches the public URL users reach your Keycloak at (default: https://localhost/auth for local dev). The BFF validates tokens against <KEYCLOAK_URL>/realms/<KEYCLOAK_REALM> — if the value does not match what users see in the browser, every login will be rejected with a JWT signature error. For the full Keycloak env-var list (realm, client IDs, secrets), see Reference → Environment variables.

External IdP Integration Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to connect an external identity provider (Google, Microsoft Entra, generic OIDC, SAML) to GENIE.AI through Keycloak. Once configured, users can sign in via the external IdP without any GENIE.AI code or configuration changes — Keycloak brokers the entire flow and issues a standard OIDC token to GENIE.AI.

Before you start

Before configuring an external IdP, make sure:

GENIE.AI is deployed with HTTPS reachable at https://<NGINX_PUBLIC_DOMAIN>/. See Installation & Configuration Guide. The placeholder <your-domain> used throughout this guide is the value of NGINX_PUBLIC_DOMAIN in your .env.
Keycloak is reachable at https://<your-domain>/auth/admin (NGINX proxies /auth/* to Keycloak).
The genie realm exists (it is created automatically by the keycloak-config service during the standard install).
You have admin access to your Google Workspace / Microsoft Entra / generic OIDC / SAML IdP tenant, and the authority to register a new OAuth client or SAML relying party in it.
Outbound HTTPS from the Keycloak container to the IdP is allowed by your network/firewall. If your network uses an HTTP proxy, see §6 Network requirements below.

Key terms

Term	Meaning
OIDC (OpenID Connect)	The identity layer on top of OAuth 2.0 used by Google, Microsoft Entra, and most modern IdPs. Issues ID tokens (JWTs) that Keycloak can verify.
Broker (Keycloak)	The Keycloak feature that mediates between your app and an external IdP. The user signs in at the IdP, Keycloak translates the result, and issues its own token to GENIE.AI.
JWKS (JSON Web Key Set)	Public keys the IdP publishes; Keycloak uses them to verify the IdP’s ID token.
`{iss}#{sub}`	Composite key for a federated user. `iss` is the Keycloak realm’s issuer URL; `sub` is the user ID Keycloak assigned to the local account (not the IdP’s `sub`).
JIT (Just-In-Time) provisioning	The act of creating or updating the user record in ArangoDB on first authenticated request, using JWT claims as source of truth. See Keycloak Admin Guide → §5.
Identity Provider Mapper	A Keycloak transformation that runs during the broker flow to map an IdP claim (e.g., `groups`) to a Keycloak realm role. See Keycloak Admin Guide → §6.
Federated user	A user authenticated by an external IdP, as opposed to a user authenticated directly against Keycloak’s local database.

How it works

flowchart TD
 Browser["Browser (GENIE.AI Frontend - Vue)"]
 Login["Keycloak Login Page"]
 Local["Local Keycloak account"]
 ExtBtn["External IdP button (Google, Microsoft, …)"]
 AuthEP["External IdP authorization endpoint"]
 Auth["External IdP authentication + consent"]
 Broker["Keycloak broker endpoint<br/>(/auth/realms/<realm>/broker/<alias>/endpoint)"]
 Exchange["Keycloak exchanges code with IdP,<br/>validates token, applies Identity Provider Mappers (role assignment)"]
 Issue["Keycloak issues its own JWT to GENIE.AI"]
 Store["Frontend stores JWT and sends it on every API request"]

 Browser --> Login
 Login --> Local
 Login --> ExtBtn
 Local -. "Keycloak JWT" .-> Issue
 ExtBtn --> AuthEP --> Auth --> Broker --> Exchange --> Issue
 Issue --> Store

GENIE.AI always receives a standard Keycloak-issued OIDC token. The backend’s auth middleware (keycloak-auth-middleware.js) is completely unaware of which external IdP was used — the JWT signature, claims, and roles look identical regardless.

Local development with self-signed certificates

Mon, 01 Jan 0001 00:00:00 +0000

When you point a local GENIE.AI stack at a hostname other than localhost (El Salvador-style mobile-test topology, a private-IP GPU node, a colleague’s laptop over LAN), nginx serves a self-signed TLS certificate. Browsers, curl, Node.js and Python all reject the connection on certificate-validation grounds. This page lists every variable GENIE.AI exposes to either bypass or trust that certificate in dev, names the service each variable reaches, and spells out the security cost of bypassing.

Branding Customization

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to rebrand a GENIE.AI deployment for a partner institution: swap the logo, favicon, application title, and brand color in the web UI; replace the logo on the Keycloak login, account, admin, and email templates; and verify that everything renders correctly after a reload.

The brand surface is small (one JSON config, four logo files, two CSS files) and every file is committed to the repository, so rebranding can be a normal code change: open one MR, get one review. Because those same files are also seeded onto every deployed node, you can equally rebrand a running deployment by editing them on the node — no image rebuild, no redeploy. Pick whichever fits; Where the brand files live at runtime covers the difference, including the one trade-off that surprises people.

CORS, CSP & Public Domain

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Configure the three variables that govern what the browser is allowed to do against GENIE.AI, and what GENIE.AI announces as its public origin — the trust boundary between the SPA and the API gateway.

Prerequisites

A deployed GENIE.AI stack (Docker Compose or Swarm) with HTTPS terminated at nginx.
A reachable NGINX_PUBLIC_DOMAIN (the FQDN clients use to reach nginx) and a valid TLS certificate for it.
Access to .env at the deploy root and to the host running the stack.
For the OIDC verification step: the Keycloak realm name (default genie).

At a glance

Variable	Set in	Where it is consumed	Purpose
`NGINX_PUBLIC_DOMAIN`	`.env`	nginx redirects + frontend `Host` header (`default.conf.template:278, 301`), Keycloak `redirect_uri` / `KC_HOSTNAME`, Grafana `GF_SERVER_ROOT_URL`, backend `KEYCLOAK_URL`	Hostname every redirect + OIDC issuer URL is derived from
`CORS_ALLOWED_ORIGINS`	`.env`	Backend `cors` middleware (`components/gov-chat-backend/index.js:404`)	Comma-separated allow-list enforced by the backend `cors` middleware (with `/regex/` syntax — see CORS_ALLOWED_ORIGINS)
`CSP_CONNECT_SRC`	`.env`	nginx `location /` (`default.conf.template:268`), nginx named location `@frontend_spa` (`default.conf.template:292`), backend Helmet `contentSecurityPolicy` (`components/gov-chat-backend/index.js:382`)	CSP `connect-src` directive emitted by nginx for the frontend HTML responses and by the backend Helmet middleware. Must mirror `VUE_APP_CSP_CONNECT_SRC` (frontend dev-server CSP — `components/gov-chat-frontend/vue.config.js:5`)
`VUE_APP_CSP_CONNECT_SRC`	`.env`	Frontend dev-server CSP (`vue.config.js:5`) and `DefinePlugin` injection (`vue.config.js:63`)	Build-time `connect-src` for the local dev server and the runtime Vue bundle. Same value as `CSP_CONNECT_SRC` (different stage: build-time vs. runtime).

The other nginx locations each handle CSP independently of CSP_CONNECT_SRC — this is deliberate (the API has no need for cross-origin connect-src; Grafana needs its own because it embeds WebSocket traffic):

Admin dashboard customization

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The GENIE.AI admin dashboard is a single-file Vue 3 component, AdminDashboard.vue (4465 lines, Options API) that renders a left sidebar, four stat tiles, and a tabbed content area. The eight tabs cover everything an operator needs to run the platform: System Health, Knowledge Hierarchy, Document Management, Database, Logs, Query Inspector, User Management, and Security.

This page is the how-to for customizing the dashboard. It walks through the wiring model — sidebar nav-links, the adminTabs computed property, the DsTabs component, and the activeTab === '<tab-name>' content gates — then gives step-by-step recipes for adding a tab, removing a tab, and adding a new action card (the Backup / Optimize style). It also covers per-institution access control (which goes through Keycloak, not the dashboard) and the local-dev rebuild loop.

Restrict active locales on a deployment

Mon, 01 Jan 0001 00:00:00 +0000

GENIE.AI ships locale files for every supported language in the source tree. A deployment chooses which subset to expose at runtime via three configuration knobs — one per runtime surface:

Surface	Knob	Where it is read	Default (unset)
Web UI (language selector, vue-i18n runtime)	`VUE_APP_AVAILABLE_LOCALES`	Frontend `.env` (build-time, then injected into `window.APP_CONFIG`)	All 14 locales
Keycloak login pages	`KEYCLOAK_SUPPORTED_LOCALES`	Keycloak realm config (JSON array, read at realm import / restart)	Curated default set
Flutter mobile app	`KeycloakConfig.supportedLocaleCodes`	Per-flavor Dart config (e.g. `mobile/genie_ai_mobile/lib/config/flavors/template.dart`)	Curated default set

These three knobs are independent — a deployment can restrict the web UI to en,fr while keeping all login-page languages (e.g. for a deployment that federates to several identity providers each serving a different locale audience).

Deployment flavors

Mon, 01 Jan 0001 00:00:00 +0000

A flavor is the GENIE.AI term for everything that makes a deployment look like a particular institution rather than the upstream “GENIE.AI” build. On mobile, one flavor corresponds to one Dart file in mobile/genie_ai_mobile/lib/config/flavors/<name>.dart; every artifact that should differ between institutions — splash image, app title, Keycloak branding overrides, locale whitelist, mobile OIDC client — is read from that file (and the shared assets under assets/) at build time.

The production reference flavor is mobile/genie_ai_mobile/lib/config/flavors/itu.dart (the ITU El Salvador deployment). Every other flavor follows the same shape: copy template.dart to <institution>.dart, edit the values that should change, and add a case in getConfig() in keycloak_config.dart for the new flavor.