FC Administration Guide

Scope — this page covers day-to-day operator tasks: realm and user bootstrap, role assignment, runtime health checks, log-level tuning, and the Helm-based production deployment. For configuration parameters see Installation & Configuration Guide. For the deployment view (Kubernetes topology, storage layout) see the arc42 document at github.com/eclipse-xfsc/docs/federated-catalogue/src/docs/architecture/.

1. Keycloak realm and roles

The Federated Catalogue authenticates against an external Keycloak realm (default name: gaia-x). The realm definition shipped with the docker-compose stack lives under /keycloak/realms — see its README for the import procedure.

Default admin credentials for the local Keycloak: admin / admin. Change these before any non-local deployment.

Admin console URL (local stack): http://key-server:8080/admin — requires the 127.0.0.1 key-server line in /etc/hosts.

Roles

The FC and the demo portal consume two role names from the gaia-x realm:

Role	Purpose
Ro-MU-CA	Catalogue user — can register, query, and manage assets through the API and demo portal.
ADMIN_ALL	Catalogue administrator — additionally has access to the admin dashboard endpoints (graph rebuild, backend switch, file-store inspection, trust-framework family/base-class/bundle-config toggles and overrides, schema-module toggles).

Onboarding a user

1. Log into the Keycloak admin console.
2. Select the gaia-x realm.
3. Users → Add user — fill username, email, first/last name. Save.
4. Credentials tab → set a password. Disable "Temporary" if you do not want a forced reset on first login.
5. Role mapping → assign Ro-MU-CA (standard user) and/or ADMIN_ALL (administrator).

Client and client secret

The FC server is registered as the OAuth2 client federated-catalogue in the gaia-x realm. The client secret must match what is supplied to the FC via the KEYCLOAK_CREDENTIALS_SECRET environment variable (or keycloak.credentials.secret in application.yml / Spring profile).

For local docker-compose runs, both sides read the secret from docker/.env (or docker/dev.env). Rotate the secret by regenerating it in Keycloak and updating the env file before restarting fc-server.

Keycloak Clients → federated-catalogue → Credentials tab

Per-environment realm files

The repository ships three pre-configured realm exports, one per target environment:

Directory	Target environment
keycloak/realms/dev/	Local development
keycloak/realms/staging/	Staging
keycloak/realms/prod/	Production

The KC_REALM_ENV environment variable selects which one Keycloak imports at startup. Use the dev/ realm only for local docker-compose runs; replace its placeholder secrets before promoting any realm export to a shared deployment.

Embedding the Keycloak Admin Console in the FC portal

The FC demo portal embeds the Keycloak Admin Console in an iframe for the user-management page. By default, modern browsers block this through the X-Frame-Options header and the Content-Security-Policy frame-ancestors directive. To allow the embedding, relax both headers in the master and gaia-x realms (Realm Settings → Security Defenses, or directly in the realm JSON):

Header	Required change
xFrameOptions	Remove (set to the empty string "").
contentSecurityPolicy	Add your portal origin to the frame-ancestors list.

The bundled realm files include preliminary values so the demo portal works out of the box; tighten these for production.

Admin Console URL override

The demo portal auto-derives the Keycloak Admin Console URL from the catalogue's configured Keycloak server and realm. When Keycloak is reachable on a different hostname from the FC (for example, the FC talks to Keycloak in-cluster but the browser hits an ingress), set the explicit override property documented in the Installation & Configuration Guide.

2. Runtime health and observability

The FC exposes the following Spring Actuator endpoints by default:

Endpoint	Purpose
/actuator/health	Liveness / readiness probe. Detail level is shown only when the caller is authorized (management.endpoint.health.show-details: when_authorized).
/actuator/info	Build info and version metadata.
/actuator/graph-rebuild	FC-specific — triggers a graph store rebuild from the metadata store. Requires the ADMIN_ALL role.

Additional actuator endpoints (/metrics, /prometheus, /loggers, …) can be enabled by extending management.endpoints.web.exposure.include — they are off by default.

Log-level tuning at runtime

Application loggers can be raised or lowered without a restart via environment variables, e.g.:

LOGGING_LEVEL_EU_XFSC_FC=TRACE
LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=INFO

Or via the actuator /loggers endpoint when it is exposed and the caller holds ADMIN_ALL.

3. Graph store administration

The FC supports two graph backends (Fuseki by default, Neo4j optionally), resolved at startup by RoutingGraphStore. The active backend can be switched at runtime via the admin dashboard's Switch Backend action — this performs an in-process driver swap and persists the choice as graphstore.preferred.backend so the next boot uses it.

A pre-flight probe verifies reachability of the target backend before the switch is committed. If a backend is empty after a switch, use the /actuator/graph-rebuild endpoint (or the dashboard's rebuild action) to repopulate it from the metadata store.

4. Production deployment (Helm)

The official Helm chart is at deployment/helm/fc-service. See its README.md for the values reference.

Minimum operator checklist before promoting to a shared environment:

• Override spring.datasource.password with a Kubernetes secret.
• Override graphstore.password (Neo4j) with a Kubernetes secret if Neo4j is selected.
• Override keycloak.credentials.secret via KEYCLOAK_CREDENTIALS_SECRET from a secret.
• Pin federated-catalogue.enabled-trust-frameworks (e.g. gaia-x) to the bundle(s) you intend to enforce.
• Decide which verification steps to enable (federated-catalogue.verification.*) — all signature checks are off by default.
• Configure federated-catalogue.query.partners if this instance participates in distributed query.
• Configure publisher.impl / subscriber.impl (ces, nats, or none) according to your event topology.

5. Troubleshooting

Symptom	First thing to check
/actuator/health returns DOWN	Check Postgres connectivity (spring.datasource.url) and the active graph store URI.
JWT auth fails with 401	issuer-uri matches your Keycloak realm exactly; client secret matches Keycloak; clock skew between FC and Keycloak under 60s.
SDs/assetsare accepted but not searchable	The graph store may be empty or out of sync — call /actuator/graph-rebuild.
Trust framework rejects a credential	Confirm federated-catalogue.enabled-trust-frameworks includes the framework family and that the bundle's trust-anchor URL is reachable from the pod.
Compliance call hits an unexpected endpoint	A runtime override may be active. Call GET /admin/trust-frameworks and inspect each bundle's effectiveConfig / overriddenFields; revert a single field via PATCH /admin/trust-frameworks/bundles/{bundleId} with the field set to JSON null, or wipe all overrides for the bundle via DELETE /admin/trust-frameworks/bundles/{bundleId}.