Skip to main content

​
Overview

FOKS server configuration is written in Jsonnet, a superset of JSON with variables, functions, and imports. All services share a single config file: conf/foks.jsonnet. The file is structured as:
config.bash generates the local.*.libsonnet files from your deployment parameters. To see the fully-resolved configuration:

​
Core settings

These live in local.pre.libsonnet and are set by config.bash.

​
Networking

​
Ports

All external services share external_addr and differ only by port: Clients discover the exact ports from the probe service — no client-side port configuration is required.

​
Database

FOKS uses multiple databases (one per functional area). Each is named in the db block of foks.jsonnet:

​
Keys and certificates

​
Viewership mode

Controls whether users on the same host can see each other: Viewership is set when the host is initialized and can be changed later via the web admin panel.

​
Other flags

​
Applying config changes

After editing local.pre.libsonnet or local.post.libsonnet, restart the affected services:

​
SSO / OAuth2 configuration

SSO is configured at runtime via the web admin panel, not in the Jsonnet config. This means SSO can be enabled, changed, or disabled without restarting any services.
SSO is configured per virtual host (or per standalone server). It is set up through the web admin UI at foks admin web.

​
Setting up OAuth2 SSO

  1. In your identity provider (Okta, Entra ID, Auth0, etc.), create an OAuth2 application with:
    • Grant type: Authorization Code + PKCE
    • Redirect URI: https://<your-foks-host>/oauth2/callback
    • Scopes: openid, profile, email, offline_access
  2. Note the OpenID configuration URL. For Okta this looks like:
  3. Open the FOKS web admin panel:
  4. Navigate to your virtual host’s settings → SSO and enter:

​
How SSO authorization works

Once SSO is configured, every authenticated FOKS request checks with the IDP:
  1. On login, the user is redirected to the IDP and completes the OAuth2 flow. FOKS stores the resulting access and refresh tokens.
  2. On every subsequent authenticated connection, FOKS checks whether the stored access token is still valid.
  3. If the token is near expiry, FOKS proactively exchanges the refresh token with the IDP for a fresh access token.
  4. If the IDP rejects the refresh — because the user was deprovisioned, suspended, or removed from the application — FOKS immediately marks the session as invalid. The user loses access within the access token’s remaining TTL (usually minutes, depending on IDP settings).
This means removing a user from your IDP automatically revokes their FOKS access without any manual intervention.
For immediate revocation, set a short access token TTL in your IDP (e.g., 10 minutes). FOKS will attempt a refresh within that window and fail as soon as the IDP rejects the user.

​
SSO and usernames

When SSO is enabled, FOKS usernames are derived from the IDP’s preferred_username or email claim. This keeps FOKS identities in sync with your organization’s naming scheme — when you look up alice@your-foks-host, you know exactly which IDP account that maps to.

​
Disabling SSO

SSO can be disabled from the web admin panel at any time. Existing users will retain their accounts; they will no longer require IDP re-validation on each connection.