Configuration

IdentityScribe uses HOCON files, environment variables, and CLI flags. You only need to set what differs from the defaults — everything else comes from reference.conf.

Values are resolved highest-priority-first:

IdentityScribe ships three config templates. Copy one to identity-scribe.conf and edit it for your environment.

minimal.conf gets IdentityScribe running with the fewest settings. It connects to one LDAP source, syncs one entry type, and exposes a REST API. Use it to evaluate Scribe or build up a config from scratch.

recommended.conf turns on every channel and adds monitoring. It includes user and group transcribes with indices, Prometheus metrics, health probes, and observability endpoints. Auth is disabled so you can explore without tokens.

production.conf applies the full Production Checklist. It enables TLS on all endpoints, requires bearer token auth, isolates monitoring on a separate socket, and disables API schema endpoints. All secrets come from environment variables — no hardcoded defaults.

Every template needs a database and an LDAP source.

ldap {
  url = "ldap://your-ldap-server:389"
  bind-dn = "cn=admin,dc=example,dc=com"
  bind-password = ${LDAP_BIND_PASSWORD}
}

database {
  url = "postgresql://localhost:5432/identity_scribe"
  user = "scribe"
  password = ${DB_PASSWORD}
}

Secrets use ${ENV_VAR} substitution so they stay out of config files. See Secrets management for more.

Environment variables follow the config path with dots converted to underscores:

Config path: monitoring.hints.persistence.enabled
Env var:     SCRIBE_HINTS_PERSISTENCE_ENABLED

The configuration reference lists every environment variable alongside its config path and default value.

Customize defaults without copying them. These patterns keep configs short and pick up new defaults automatically on upgrade.

Use += to add items after defaults:

# Single item
monitoring.log.rules += { action = include, name = "Audit.*" }

# Multiple items (use ${path} [...] pattern, not += [...])
monitoring.log.rules = ${monitoring.log.rules} [
  { action = include, name = "Debug.*" }
  { action = exclude, name = "Noisy.*", where = "duration.seconds<=10ms" }
]

# Any array works
http.cors.allow-origins += "http://localhost:3000"
ssl.cipher-suites += "TLS_AES_256_GCM_SHA384"

Place items before defaults. For log rules, earlier items take priority:

# Your rule first, then defaults
monitoring.log.rules = [
  { action = include, name = "Critical.*" }
] ${monitoring.log.rules}

Objects merge automatically. Specify only what changes:

# Change port, inherit everything else
http.sockets.admin { port = 9001 }

# Override format, keep other log settings
monitoring.log.format = "json"

Many settings cascade automatically:

Override at any level:

# Start with http.ssl, change just the cert for this socket
http.sockets.secure.ssl = ${http.ssl} {
  cert = "/custom/server.crt"
  key = "/custom/server.key"
}

include required("production.conf")

# Priority rules + relaxed thresholds
monitoring.log.rules = [
  { action = include, name = "*.Dev*" }      # Always log dev ops
] ${monitoring.log.rules} [
  { action = exclude, where = "duration.seconds<=2s" }  # Relax timing
]

# Extra CORS origins
http.cors.allow-origins += "http://localhost:3000"
http.cors.allow-origins += "http://localhost:4321"

1. Check priority: A higher-priority source may be overriding your value
2. Verify naming: Ensure underscores match dots in the config path
3. Case sensitivity: Environment variables are case-insensitive for lookup

# Print resolved config (sensitive values masked)
identity-scribe --printconfig

# Enable debug logging for config parsing
SCRIBE_LOG_CONFIG=debug identity-scribe

• Configuration reference — Every setting, env var, and default value
• Deployment — Docker Compose and Kubernetes examples
• Upgrading — Migration from older config formats