6.7 KiB
FedWiki Integration
This document describes how the member-console integrates with FedWiki for wiki site provisioning and management.
Architecture Overview
The member-console manages FedWiki sites through the FarmManager API, a plugin that runs on a designated admin wiki site within a FedWiki farm. The security layer uses a composable architecture that separates authentication from authorization.
Components
| Component | Package | Role |
|---|---|---|
| Security layer | wiki-security-composable |
Composable security plugin that separates authentication from authorization. Allows mixing auth providers with authorization enhancers. |
| Authentication | wiki-security-passportjs |
OAuth2/OIDC authentication via Keycloak. Configured per wiki domain in config.json under wikiDomains. |
| Authorization | wiki-plugin-useraccesstokens |
Adds API token (Bearer) authentication. Tokens are stored per-site in status/user-access-tokens.json. |
| Farm management | wiki-plugin-farmmanager |
REST API for programmatic farm management (create, list, delete sites). Requires admin authentication. |
How FarmManager Works
FarmManager is a site-level plugin with farm-level scope. It loads per-site (standard FedWiki plugin architecture), but manages all sites in the farm by resolving the parent farm directory from the current site's data path.
In practice, one site is designated as the admin site (e.g., admin.localtest.me). All farm management API calls go through this site. The plugin uses app.securityhandler.isAdmin(req) middleware to restrict access to farm admins.
FarmManager API
All endpoints are served from the admin site and require admin authentication via Bearer token.
Base URL: http://admin.localtest.me (local dev)
| Method | Endpoint | Description |
|---|---|---|
GET |
/plugin/farmmanager/sites |
List all wiki sites in the farm |
POST |
/plugin/farmmanager/sites |
Create a new wiki site |
GET |
/plugin/farmmanager/sites/:domain |
Get details for a single site |
PATCH |
/plugin/farmmanager/sites/:domain |
Partially update a site's properties |
DELETE |
/plugin/farmmanager/sites/:domain |
Soft-delete (deactivate) a site |
DELETE |
/plugin/farmmanager/sites/:domain?hard=true |
Permanently delete a site |
Authentication
The member-console authenticates to the FarmManager API using a User Access Token (prefix: fwuat-), sent as a Bearer token in the Authorization header.
Tokens are generated by wiki-plugin-useraccesstokens and stored as bcrypt hashes in the admin site's status/user-access-tokens.json. Each token has:
- A
name(unique per site) - A
user(the owner's OAuth2 identity) - A
tokenHash(bcrypt hash of the token) - A
displayHint(last 4 characters, for identification) - Optional
scopes(site:read,site:write)
Member-Console Configuration
Relevant settings in mc-config.yaml:
# URL of the admin wiki site (where FarmManager plugin is loaded)
fedwiki-farm-api-url: "http://admin.localtest.me"
# Domains where wiki sites can be created
fedwiki-allowed-domains:
- "localtest.me"
# URL scheme for generated site links
fedwiki-site-scheme: "http"
# User Access Token for FarmManager API authentication
fedwiki-admin-token: "fwuat-6R-p8TMlBBrwH7bV8l5oqsdoSbij5-SFHS5oVRJzGGM"
The FarmManagerClient in internal/workflows/fedwiki/farmmanager_client.go constructs API URLs as baseURL + path (e.g., http://admin.localtest.me/plugin/farmmanager/sites).
Local Development Setup
FedWiki Farm Structure
The FedWiki farm runs in Docker (see test/compose.yaml) on port 80 with these key directories:
test/data/fedwiki/ # Runtime data (mounted as /home/node/.wiki)
config.json # Farm configuration (OAuth2, wikiDomains, admin identity)
admin.localtest.me/ # Admin site (FarmManager API host)
status/
owner.json # Site owner identity (OAuth2 subject)
user-access-tokens.json # API tokens for Bearer auth
localtest.me/ # Root farm site
<subdomain>.localtest.me/ # User-created wiki sites
Seed Data
Seed data lives in test/seed/fedwiki/ and is copied to test/data/fedwiki/ on docker compose up via the fedwiki-init container (cp -rn, no-clobber).
The seed includes:
admin.localtest.me/status/owner.json— Admin site owner (alice, pinned ID:a0000001-0000-4000-a000-000000000001)admin.localtest.me/status/user-access-tokens.json— Pre-configured API token for member-console
config.json
The config.json is not seeded — it is runtime-generated by FedWiki on first boot, or must be manually created. It contains:
admin— Farm admin identity (OAuth2 subject). Must match a Keycloak user.farm: true— Enables farm mode.wikiDomains— Per-domain OAuth2 configuration (client ID/secret, Keycloak endpoints).security_type,auth_provider,authz_enhancers— Composable security stack.
If config.json is lost, FedWiki will generate a default one on startup, but you'll need to re-configure the OAuth2 wikiDomains and admin identity.
Keycloak User IDs
Test user IDs are pinned in test/seed/keycloak/seed-keycloak.sh so that FedWiki seed data (owner.json, config.json) can reference them deterministically:
| User | ID | Role |
|---|---|---|
| alice | a0000001-0000-4000-a000-000000000001 |
Operator, FedWiki farm admin |
| bob | b0000002-0000-4000-a000-000000000002 |
Member |
| carlos | c0000003-0000-4000-a000-000000000003 |
Member |
| diana | d0000004-0000-4000-a000-000000000004 |
Member |
The Keycloak bootstrap admin user ID is assigned by Keycloak and is not pinned.
Common Issues
"Requested Wiki Does Not Exist" from FarmManager API
- The admin site directory doesn't exist in
test/data/fedwiki/. Ensureadmin.localtest.me/exists with at leaststatus/owner.json. - Fix: Remove
test/data/fedwiki/and restart docker compose to re-seed.
EACCES permission denied
- The FedWiki container runs as
node. If the data directory is owned by root (e.g., after Docker recreates it), FedWiki can't write to it. - Fix:
chmod -R 777 test/data/fedwiki/or ensure your user UID matches the container'snodeuser.
Owner mismatch after Keycloak re-seed
- If Keycloak user IDs change, the OAuth2
idin FedWiki'sowner.jsonandconfig.jsonwon't match. User IDs are now pinned to prevent this.