Security & Auth Configuration

Configuration for external authentication, Vertex AI, OAuth, auth profiles, tool policies, proactive memory, context engine, audit logging, health checks, plugins, prompt intelligence, and environment variables reference.

[external_auth]

Configures OAuth2/OIDC external authentication, allowing users to log in via identity providers like Google, GitHub, Okta, Auth0, or Keycloak.

[external_auth]
enabled = true
issuer_url = "https://accounts.google.com"
client_id = "your-client-id.apps.googleusercontent.com"
client_secret_env = "LIBREFANG_OAUTH_CLIENT_SECRET"
redirect_url = "http://127.0.0.1:4545/api/auth/callback"
scopes = ["openid", "profile", "email"]
allowed_domains = ["example.com"]
session_ttl_secs = 86400

# Where in the token the identity attributes both maps below are matched
# against are read from. Dotted paths; `<client>` is substituted with this
# provider's client_id. Defaults to ["roles", "groups"].
claim_paths = ["realm_access.roles", "resource_access.<client>.roles", "groups"]

# Which IdP groups may call the API, and at what privilege.
# Empty by default: without it an OIDC bearer authenticates nothing.
[external_auth.role_map]
"librefang-owners" = "owner"
"librefang-operators" = "admin"
"engineering" = "user"

# Which IdP groups confer membership in a local [[groups]] entry.
# Independent of role_map: membership carries no privilege.
[external_auth.group_map]
"platform-oncall" = "oncall"
"sox-reviewers" = "compliance"

role_map: turning an ID token into an API credential

Until an entry exists here, a validated OIDC bearer authorizes nothing — the daemon verifies the token against the provider's JWKS and the caller still gets the same 401 they would get with no token at all. Declaring a mapping is what grants privilege, so the grant is always something an operator wrote down rather than something the identity provider decided on its own.

The keys are values of whichever claims claim_paths resolves — the roles and groups claims by default — and the values are LibreFang roles in the same viewer < user < admin < owner ladder that [[users]] role and [channel_role_mapping] use. A caller holding several mapped groups gets the highest-privilege match, so claim ordering — which is the provider's business, not yours — cannot decide the effective role.

Three things deliberately grant nothing rather than falling back to a default:

• a claim value absent from the map,
• a claim value present but mapped to an unrecognised role string (a typo like "admn", which is reported as a WARN at boot and on config reload),
• a token from a provider with neither audience nor client_id configured, because JWT audience validation is disabled in that case and any token signed by the issuer's keys would otherwise validate.

require_email_verified applies here too: a token whose email the provider did not verify carries no role.

The mapping is read live from the config swap, so POST /api/config/reload applies an edit on the next request with no restart. It is deliberately not writable through POST /api/config/set — a caller who could edit it could grant themselves owner by naming a group they already hold — but GET /api/config reads it back so you can confirm which groups currently carry privilege.

group_map: putting an IdP group on a LibreFang team

[[groups]] (see the identity section) names a team — an on-call rota, a project group, a department — that permissions and ownership can refer to instead of enumerating individuals. group_map is how membership in one of those teams comes from your identity provider instead of being typed in by hand and then going stale when someone changes roles.

The keys are claim values, exactly as in role_map; the values are [[groups]] names. As with roles, membership is mapped and never name-matched: an IdP group called oncall does not join the local oncall group unless you wrote that entry. The reason is worth being explicit about — in a tenant where creating a group is self-service, name-matching would mean anyone who can create a group could pick a name and acquire whatever that team owns.

What membership does and does not do:

• It does confer the group's own name and every string in its roles list as binding-rule role strings, and it makes the caller a member of the group for ownership purposes.
• It does not confer any RBAC privilege. A group named owner is a team named owner. If you want one IdP claim to carry both membership and privilege, write it into role_map and group_map — two entries, deliberately.

Membership is recomputed from the presented token on every request and is never written into config.toml. That is what makes deprovisioning propagate: remove someone from the group in your identity provider and the membership disappears here when their current token expires, with nothing to clean up locally. It also means the reverse does not happen — an IdP that stops asserting a group does not remove that person from a [[groups]] members list you typed. A name in members is your own grant, and only you can withdraw it. When both sources name the same person, the result is simply the union.

A group_map value naming a group that does not exist in [[groups]] confers nothing and is reported as a WARN at boot and on config reload — including when the group was deleted or renamed without the map being touched, which is the usual way this happens.

GET /api/authz/whoami reports what the calling credential actually resolved to: role, principal, effective groups, which of those came from the token, and the group-conferred role strings. It is the first thing to check when an SSO login has less access than expected.

claim_paths: where the claim values come from

Both maps are matched against the same resolved set of claim values, and claim_paths decides which parts of the token that set is built from. Entries are dotted paths, so Keycloak's realm_access.roles and resource_access.<client>.roles are addressable; <client> is substituted with the provider's own client_id, so one entry works across providers and never picks up another client's roles from the same token. A path resolving to an array of strings contributes its elements; one resolving to a single string contributes its whitespace-separated words. A path that resolves to nothing is not an error — providers differ in what they emit.

The default is ["roles", "groups"]. scope is deliberately not included: roles and groups are assertions your identity provider makes about the user, while scope describes what a client application asked for and was granted, which a token minted for a different OAuth client in the same tenant also carries. Add "scope" to the list if you want it, and only where you have set audience — without audience binding the daemon refuses to derive any grant at all.

Note that adding a path widens role_map as well as group_map, since both read the same set.

group_map and claim_paths are read-only through POST /api/config/set for the same reason as role_map, and readable through GET /api/config for the same reason too.

For multi-provider setups, use [[external_auth.providers]] with fields: id, display_name, issuer_url, auth_url, token_url, userinfo_url, jwks_uri, client_id, client_secret_env, redirect_url, scopes, allowed_domains, audience.

[terminal]

Configures access control for the interactive terminal WebSocket endpoint.

[terminal]
enabled = true
allow_remote = false
allowed_origins = ["https://dashboard.example.com"]
tmux_enabled = true
max_windows = 16
# tmux_binary_path = "/usr/local/bin/tmux"

Notes:

• Missing Origin is allowed for non-browser clients.
• allow_remote = true does not disable auth; if API keys or dashboard credentials are configured, remote clients still need valid auth.
• Prefer explicit HTTPS origins over "*" for browser access.
• The ws_terminal_messages_per_minute rate limit (default: 3600) in the [rate_limit] section controls per-connection WebSocket message throughput for interactive terminal sessions.

[vertex_ai]

Configures Google Cloud Vertex AI as an LLM provider.

[vertex_ai]
project_id = "my-gcp-project"
region = "us-central1"
credentials_path = "/path/to/service-account.json"

Credentials are resolved in this order:

1. credentials_path in config (JSON string or file path)
2. VERTEX_AI_SERVICE_ACCOUNT_JSON env var
3. GOOGLE_APPLICATION_CREDENTIALS env var (file path)
4. gcloud auth print-access-token CLI fallback

[oauth]

Configures OAuth client IDs for PKCE (Proof Key for Code Exchange) flows used by the dashboard.

[oauth]
google_client_id = "your-google-client-id.apps.googleusercontent.com"
github_client_id = "your-github-app-client-id"
microsoft_client_id = "your-azure-app-client-id"
slack_client_id = "your-slack-app-client-id"

[auth_profiles]

Configures multiple API key profiles per provider to enable key rotation when one key is rate-limited or exhausted.

[auth_profiles]
anthropic = [
  {name = "primary", api_key_env = "ANTHROPIC_API_KEY_1", priority = 0},
  {name = "secondary", api_key_env = "ANTHROPIC_API_KEY_2", priority = 1},
]
openai = [
  {name = "main", api_key_env = "OPENAI_API_KEY", priority = 0},
]

The value is a map from provider name to a list of AuthProfile objects:

[tool_policy]

Configures global tool access rules, groups, and recursion depth limits. References the ToolPolicy type.

[tool_policy]
subagent_max_depth = 10
subagent_max_concurrent = 5

[[tool_policy.global_rules]]
pattern = "shell_*"
effect = "deny"

[[tool_policy.groups]]
name = "web_tools"
tools = ["web_search", "web_fetch"]

ToolPolicyRule fields:

ToolGroup fields:

[proactive_memory]

Configures proactive memory extraction (mem0-style automatic memory management). References the ProactiveMemoryConfig type.

[proactive_memory]
enabled = true
auto_memorize = true
auto_retrieve = true
max_retrieve = 10
extraction_threshold = 0.7
# extraction_model = "gpt-4o-mini"             # uses default provider
# extraction_model = "anthropic/claude-haiku-4" # targets a specific provider
# extraction_model = "anthropic:claude-haiku-4" # colon form also works
extract_categories = ["user_preference", "important_fact", "task_context", "relationship"]
session_ttl_hours = 24
duplicate_threshold = 0.5
confidence_decay_rate = 0.01
max_memories_per_agent = 1000

[context_engine]

Configures the pluggable context assembly engine that controls how agent memory is recalled and assembled into prompts.

[context_engine]
engine = "default"
# plugin = "qdrant-recall"    # resolves to ~/.librefang/plugins/qdrant-recall/

[context_engine.hooks]
# ingest = "~/.librefang/scripts/my_recall.py"
# after_turn = "~/.librefang/scripts/my_indexer.py"
# runtime = "python"   # python (default) | v | node | deno | go | native

[[context_engine.plugin_registries]]
name = "Official"
github_repo = "librefang/librefang-registry"

[audit]

Configures audit log retention.

[audit]
retention_days = 90

[health_check]

Configures periodic health checks for LLM providers.

[health_check]
health_check_interval_secs = 60

[plugins]

Configures additional plugin registries to search for installable context engine plugins.

[plugins]
plugin_registries = ["acme-corp/librefang-plugins"]

[prompt_intelligence]

Configures prompt versioning and A/B experiment support. When enabled, LibreFang automatically tracks prompt version history and supports running A/B experiments to compare prompt variants. See the Prompt Intelligence guide for full documentation.

[prompt_intelligence]
enabled = false
hash_prompts = true
max_versions_per_agent = 50

Environment Variables

Complete table of all environment variables referenced by the configuration. None of these are read by the config file itself -- they are read at runtime by the kernel and channel adapters.

LLM Provider Keys

Web Search Keys

Channel Tokens