Skip to content

Configuration

  • Choose a template

    Evaluation, recommended defaults or production.

  • Set your values

    Database, directory and credentials.

  • Verify

    Start Scribe and check the resolved behavior.

Start from a template and change only what your deployment needs.

You will know where to put a setting and which value takes precedence.

You decide: Choose a starter template before adding individual settings.

Next: Attribute modeling

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.

For schema decisions such as which values to sync as plain attributes and which relationship views to compute at query time, start with Attribute Modeling.

HIGHEST FIRSTCLI flags--readonlySystem properties-Dreadonly=trueSCRIBE_* variablesSCRIBE_LDAP_URLDeclared aliasesLDAP_SO_TIMEOUTConfiguration fileidentity-scribe.confLicense, databasefallback variablesDefaultsreference.confEffective valueif unsetif unsetif unsetif unsetif unsetif unsetif unsetfirst set wins
HIGHEST FIRSTCLI flags--readonlySystem properties-Dreadonly=trueSCRIBE_* variablesSCRIBE_LDAP_URLDeclared aliasesLDAP_SO_TIMEOUTConfiguration fileidentity-scribe.confLicense, databasefallback variablesDefaultsreference.confEffective valueif unsetif unsetif unsetif unsetif unsetif unsetif unsetfirst set wins
The highest-priority source that sets a value wins, except that the license and database fallback variables yield to the configuration file.
PrioritySourceExample
1CLI flags-r, --readonly, --config /path/to/config
2System properties-Dreadonly=true, -DSCRIBE_LDAP_URL=ldap://...
3SCRIBE_* env varsSCRIBE_LDAP_URL, SCRIBE_DATABASE_PASSWORD
4Declared aliasesOTEL_*, LDAP_*, MONITORING_*, and documented bare aliases
5Config fileValues in identity-scribe.conf
6DefaultsBuilt-in fallbacks in reference.conf

Every environment variable declared in the configuration reference overrides the file, in the alias order each setting documents: SCRIBE_LDAP_SO_TIMEOUT wins over LDAP_SO_TIMEOUT, which wins over SO_TIMEOUT. An empty or blank variable counts as unset. An environment value replaces the whole setting, including an object, a list, or a set of export headers.

List settings keep the string form documented for each setting, for example SCRIBE_AUTH_METHODS=bearer,ldap or a space-separated SCRIBE_LDAP_SINGLE_VALUE_ATTRIBUTES="cn uid ou". Object settings take a self-contained HOCON object, such as SCRIBE_LDAP_VIRTUAL_ATTRIBUTES='{}'; includes and external substitutions are not supported inside it. A value that is not such an object prevents startup with an error that names the setting but not the value. The contents of a valid object are checked as they are in the configuration file, and those errors can include the value, such as an invalid filter. All other environment values remain literal strings. Passwords are untouched, and numbers, booleans and durations keep their usual conversion. Each setting validates these values as it does for a value in the configuration file.

SCRIBE_LICENSE_FILE and the POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER and POSTGRES_PASSWORD fallbacks are exceptions: they apply only when the configuration file does not set license.file or the matching database setting.

Since v3.3.0, startup emits one config_env_override warning listing settings where an environment variable replaced a different explicit file value. The warning never includes values. Defaults and settings controlled by a higher-priority flag or system property do not trigger it. Values are compared as written, list items one by one, so an equivalent value written differently, such as cn sn for [cn, sn], may still be reported as an override. Before upgrading, review the variables in the service unit, container definition, and shell profile. Remove stale variables so they cannot override the intended configuration.

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

TemplateUse caseWhat it sets up
minimal.confEvaluation, getting startedDatabase, LDAP, one transcribe, REST channel
recommended.confStaging, internal deploymentsAll channels (LDAP, REST, GraphQL, MCP), Prometheus, health probes, indices
production.confProduction, real trafficEverything in recommended + TLS, auth, network isolation, locked-down APIs

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 for evaluation, including an Observe opt-out that should stay limited to trusted local environments.

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.

edirectory-idm.conf is an importable profile for eDirectory Identity Manager role, resource, and group membership queries. Include it after your base config when you have user, role, and group transcribes. See eDirectory Identity Manager Roles.

Every template needs a database and an LDAP source.

identity-scribe.conf
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
TypeExamples
Booleanstrue, false, yes, no, on, off
Durations500ms, 5s, 30m, 1h, 2d
Sizes1k, 2m, 3g (bytes)
NumbersPlain integers (no quotes)
StringsQuoted "value" or unquoted simple-value

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:

monitoring.log.rules += {
action = include,
where = "scribe.operation~=Audit.*" }
# Multiple items (use ${path} [...] pattern, not += [...])
monitoring.log.rules = ${monitoring.log.rules} [
{ action = include, where = "scribe.operation~=Debug.*" }
{ action = exclude, where = "scribe.operation~=Noisy.* 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, where = "scribe.operation~=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"
INHERITEDsslprotocols · ciphershttp.sslenabled = trueSocket secureinherited + customYour overridecert · keysuppliessuppliesreplaces two keys
INHERITEDsslprotocols · ciphershttp.sslenabled = trueSocket secureinherited + customYour overridecert · keysuppliessuppliesreplaces two keys
A child section inherits its parent's settings and changes only the keys it overrides.

These settings inherit from a parent section:

SettingInherits from
Socket SSLhttp.sockets.<name>.ssl ← http.ssl ← ssl
Socket CORShttp.sockets.<name>.cors ← http.cors
Auth cachesauth.bearer.cache, auth.ropc.cache, auth.ldap.cache ← auth.cache; local credentials are not cached
LDAP authauth.ldap ← ldap
Transcribe LDAPtranscribes.<name>.ldap ← ldap
Channel UIchannels.*.ui ← openapi.ui
Observe UImonitoring.observe.ui ← openapi.ui
Retry servicesretry.services ← retry

Override at any level:

http.sockets.secure.ssl = ${http.ssl} {
# only these keys change
cert = "/custom/server.crt"
key = "/custom/server.key"
}
dev.conf
include required("production.conf")
# Priority rules + relaxed thresholds
monitoring.log.rules = [
{ action = include, where = "scribe.operation~=*.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: Use the exact environment-variable spelling shown in the reference
Terminal window
# Print resolved config (sensitive values masked)
identity-scribe --printconfig
# Enable debug logging for config parsing
SCRIBE_LOG_CONFIG=debug identity-scribe
SymptomCauseSolution
Env var ignoredWrong prefixUse SCRIBE_ not IDENTITY_SCRIBE_
Value not parsedWrong formatUse HOCON format: 5s, true, 1024
Config file not foundWrong search pathUse --config or SCRIBE_CONFIG_FILE