Start Here

IdentityScribe syncs your LDAP directories into PostgreSQL and exposes the data through REST, GraphQL, and LDAP channels. This page walks through installation, configuration, and your first queries. Takes about 5 minutes.

• PostgreSQL database (15+, recommended 18+)
• Access to an LDAP directory (Active Directory, OpenLDAP, etc.)
• curl or any HTTP client
• ldapsearch (optional, for testing the LDAP channel)

We need a config file that points at our database and LDAP source. Create identity-scribe.conf:

# Where to store synced data
database.url = "jdbc:postgresql://localhost:5432/scribe"
database.user = "scribe"
database.password = ${DB_PASSWORD}

# LDAP source to sync from
ldap.url = "ldap://your-ldap-server:389"
ldap.bind-dn = "cn=reader,dc=example,dc=com"
ldap.bind-password = ${LDAP_BIND_PASSWORD}

# What to sync -- one transcribe per entry type
# The key ("users" here) becomes the entry type we query against
transcribes {
  users {
    base = "ou=users,dc=example,dc=com"
    filter = "(objectClass=person)"
    scope = sub
    attributes = "cn, sn, givenName, mail, telephoneNumber"
  }
}

Secrets use ${ENV_VAR} substitution so they stay out of config files. Each transcribe defines an entry type to sync — its base DN, filter, scope, and which attributes to capture.

export DB_PASSWORD="your-db-password"
export LDAP_BIND_PASSWORD="your-ldap-password"

./identity-scribe-*

We should see a startup banner with the version and configured channels. Once it’s ready, we verify:

curl http://localhost:8080/readyz

Expected output: readyz check passed. If we see this, Scribe is running and has completed its initial sync. If the binary fails with Illegal instruction or similar on startup, see CPU Compatibility.

# List all users
curl http://localhost:8080/api/entries/users | jq

# Search by name (FleX filter syntax -- human-readable shorthand)
curl -G http://localhost:8080/api/entries/users --data-urlencode "filter=cn ^= John" | jq

# Get a specific entry (use an entryID from the list response above)
curl http://localhost:8080/api/entries/users/ENTRY-ID-HERE | jq

We should see a JSON response with an edges array. Each entry includes its entryID, cn, mail, and the other attributes we configured in the transcribe.

Scribe auto-detects the filter format, so we can also use LDAP syntax (cn=John*), JSON {"cn":{"sw":"John"}}, or SCIM cn sw "John". FleX is the human-readable shorthand format. See Choosing Filters for trade-offs between formats.

curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users(filter: \"cn ^= John\") { edges { node { cn mail } } } }"}' | jq

The response wraps results in data.users.edges. Each node contains the fields we asked for — cn and mail in this case.

The GraphQL schema is generated from our transcribe configuration. Open http://localhost:8080/graphql in a browser to explore it interactively with the built-in GraphiQL IDE.

# List all entries
ldapsearch -H ldap://localhost:10389 -x -b "o=data" "(objectClass=*)" cn

# Search users by name
ldapsearch -H ldap://localhost:10389 -x -b "ou=users,o=data" "(cn=John*)" cn mail

The LDAP channel prints entries in LDIF format — one attribute per line, entries separated by blank lines. We should see the same data we queried via REST and GraphQL.

Open http://localhost:8080/ui in a browser. The Operator UI shows synced entry counts, live ingest activity, and pressure indicators. We can search and filter entries, view point-in-time snapshots, compare versions, and browse the change timeline for any entry.

The Observe dashboard at /ui/observe shows golden signals, service health, and the Operator Copilot — which surfaces recommendations when it detects problems.