All versions since v2.1.0 (2024-07-05)
- Changes
Read the outcomes and fixes in this release.
- Upgrade
Check migration guidance before changing an existing deployment.
Find the relevant version below and check breaking changes before scheduling an upgrade.
Next: Upgrade guidance
v2.1.0 (2024-07-05)
Fixed
- Relative configuration references resolve consistently — File and path references now load from relative locations.
- Service TLS settings no longer leak into database configuration —
ssl.enabledapplies only to its intended service.
v2.1.1 (2025-02-17)
Fixed
- PostgreSQL TLS settings are applied correctly — Secure database connections now honor their configuration.
- Referenced configuration files load correctly — Split configurations no longer fail while resolving included files.
v2.1.2 (2025-02-18)
Fixed
- Attribute-set configuration rejects non-string values — Invalid elements fail validation with a configuration error.
v2.2.0 (2025-03-21)
Added
- Entry-size categories improve storage monitoring — Operators can distinguish entry data by size and see the distribution in monitoring views.
- Type-aware operations complete faster — Stored summaries reduce repeated work when IdentityScribe handles different entry types.
Fixed
- Service startup and database upgrades coordinate correctly — Service orchestration now follows the database upgrade lifecycle.
- The LDAP channel starts listening correctly — Clients can connect after channel startup.
- Memory and CPU metrics report accurate values — Resource dashboards no longer show misleading measurements.
- Health endpoints respond faster — Both health and healthy checks require less work.
v2.3.0 (2025-05-15)
Fixed
- Initial synchronization uses bounded memory — Large imports complete faster and no longer fail when memory pressure rises.
- Large LDAP responses no longer hit a message-size ceiling — Clients can receive entries that previously exceeded the limit.
- Database connections are acquired more reliably — Pool handling no longer causes avoidable acquisition failures.
- Memory and CPU metrics report more accurate values — Dashboards reflect resource use more closely.
- Health endpoints respond faster — Both health and healthy checks require less work.
- Routine logs are quieter and clearer — Normal activity uses appropriate levels and shorter messages.
Breaking
- BREAKING: Built-in PostgreSQL metrics were removed — dashboards that rely on them stop receiving data. Migration: collect database metrics with the dedicated Prometheus Exporter.
v2.4.0 (2025-06-25)
Added
- Directory lookups are faster on large datasets — Additional database coverage reduces work for common entry searches.
- Binary LDAP entry storage speeds synchronization and retrieval — Entries require less processing as they move between storage and channels.
- Selective searches use faster execution choices — IdentityScribe adapts database requests to searches that match only a small part of the directory.
- Initial synchronization avoids unnecessary lock contention — More work can proceed concurrently during the first sync.
- Synchronization state checks complete faster — Continuous synchronization spends less time determining each entry’s current state.
Fixed
- Startup counts as healthy while services initialize — Slow startup no longer causes a false health-check failure.
- Health responses show the correct service name — Operators can identify the affected service directly from the response.
- Routine monitoring disconnects no longer flood error logs — Client disconnects such as
Broken pipeandConnection reseton metrics and health endpoints now log at debug level. - Scribe disconnect failures are easier to diagnose — Error handling and logs now preserve the useful failure context.
- Restarts resume incremental synchronization — IdentityScribe no longer repeats the initial sync after every restart.
Breaking
- BREAKING: Attribute sets are no longer supported — attributes that exist only in
attributeSetsstop being observed. Migration: move every listed attribute into the mainattributesconfiguration before upgrading.
# Before (deprecated)attributeSets = [ "uid, mail, displayName"]attributes = "cn sn"
# After (supported)attributes = """ cn, sn uid, mail, displayName"""- BREAKING: Refresh-cache metrics were removed — dashboards and alerts that query them stop receiving data. Migration: remove these series from monitoring configuration:
scribe.entries.refresh.cache.countscribe.entries.refresh.cache.time
v2.5.0 (2025-06-26)
Added
- LDAP socket behavior is configurable — Environment variables and configuration properties can tune socket settings; the defaults suit production use.
- Metrics scraping uses a dynamically balanced worker pool — Scrapes complete with less contention under changing load.
Fixed
- LDAP presence searches no longer fail on an unsupported optimization — IdentityScribe now sends a valid search to the database.
- Scribe event metrics use consistent labels — Every
scribe_events_countseries carriesevent,op, andtarget. Add, move, and delete events use"none"whereoportargetdoes not apply, preventing meter registration errors.
v2.6.0 (2025-07-21)
Added
-
Scheduled reconciliation keeps stored entries aligned with LDAP — IdentityScribe periodically verifies entries against the source directory.
- Set either
intervalorcronto schedule the maintenance task. See the Configuration Reference for options and defaults. - One reconciliation runs after the initial sync and continuous search start, regardless of the schedule, to catch deletions that occurred during downtime.
- Enable scheduled reconciliation if:
- Your LDAP server has unreliable persistent-search delete notifications.
- You need periodic consistency checks for compliance.
- You experience frequent network partitions.
- New Prometheus metrics for reconciliation:
scribe_reconciliation_entries_verified_total(counter): Number of entries verified as present in LDAP during reconciliation.scribe_reconciliation_entries_deleted_total(counter): Number of entries deleted (synthetic deletes emitted) during reconciliation.scribe_reconciliation_duration_seconds(summary/timer): Total time taken for a full reconciliation run.scribe_reconciliation_last_run_timestamp_seconds(gauge): Unix timestamp of the last completed reconciliation run.
- Set either
-
Maintenance tasks can run on a schedule — See the Configuration Reference for options and defaults.
- These services support maintenance tasks:
- Database: perform routine storage upkeep after startup.
- New Prometheus metrics for database maintenance:
database_maintenance_duration_seconds(timer): Duration of each maintenance run.database_maintenance_failed_total(counter): Number of failed maintenance runs.database_maintenance_last_run_timestamp_seconds(gauge): Unix timestamp of the last attempted maintenance run.
- New Prometheus metrics for database maintenance:
- Scribe: reconcile stored entries with the LDAP server.
- The Scribe maintenance metrics are listed above.
- Database: perform routine storage upkeep after startup.
- These services support maintenance tasks:
-
Entry data compresses automatically — This reduces storage and network transfer size.
- IdentityScribe selects the compression algorithm from the data characteristics.
- Applications need no configuration changes.
- Typical LDAP entries can use up to 70% less storage.
- Prometheus metrics report compression effectiveness and cost.
-
LDAP entries keep their identity through restores and renames — Additional matching safeguards protect both initial and continuous synchronization, including rare directory restore and rename cases.
-
Prometheus scrapes return cached metrics — Metrics refresh on a regular interval so scrapes do not wait for collection work.
- Set
monitoring.prometheus.scrapeIntervalto control the refresh interval. The default is 15 seconds.
monitoring.prometheus.scrapeInterval = 15s - Set
Fixed
- License checks retry transient dependency failures — Connectivity failures involving LDAP or database services no longer crash the service immediately. IdentityScribe retries up to five times.
- Attribute changes keep their configured casing — Change logs and event descriptions no longer lowercase attribute names, so downstream systems receive the configured names.
- Reconciliation ignores unobserved operational attributes — It no longer reports false removals for attributes such as
createTimestamp,modifyTimestamp, orentryUUID; history contains only changes IdentityScribe actually observed.
Breaking
-
BREAKING: Monitoring uses about half as many time series — dashboards and alerts that depend on the former formats may stop matching. Migration: update them to the formats below before upgrading, test them in staging, and monitor memory use after deployment.
- Performance Impact
- ~50% fewer metrics: Reduced from ~1,600 to ~800 total metrics
- Memory: Rolling windows expire after 5 minutes, reducing memory use and keeping measurements current.
- Cardinality: Service-transition and LDAP-search labels use fewer combinations.
- Precision: Summary percentiles replace histogram approximations.
- Storage: Fewer time series require less monitoring storage.
- Monitoring Recommendations
- Update dashboards to use new metric formats before upgrading
- Test queries in a staging environment before using the new metrics in production.
- Verify alerts that depend on histogram buckets before upgrading.
- Monitor memory usage after upgrade (should decrease)
Detailed Changes
-
Service Transition Metrics
Before:
service_transition_seconds{service="X",from="new",to="starting",...}service_transition_seconds{service="X",from="starting",to="running",...}service_transition_seconds{service="X",from="running",to="failed",...}After:
service_transition_seconds{service="X",type="startup",...}service_transition_seconds{service="X",type="restart",...}service_transition_seconds{service="X",type="failure",...}Changes:
- Removed:
fromandtotags (high cardinality) - Added:
typetag with fixed categories (startup,restart,failure,shutdown) - Filtered: Startup noise transitions (
new → starting) - Percentiles: Reduced from 5 to 2 percentiles (
0.5, 0.95)
Migration:
- Update dashboards to use
typeinstead offrom/totags - Categories:
startup,restart,failure,shutdown
Terminal window # Old queryservice_transition_seconds{from="starting",to="running"}# New queryservice_transition_seconds{type="startup"} - Removed:
-
LDAP Search Metrics
Before: Histogram with 50+ buckets
channel_ldap_search_time_seconds_bucket{...,le="0.001"} 0channel_ldap_search_time_seconds_bucket{...,le="0.002"} 1[... 50+ buckets ...]After: Summary with selected percentiles
channel_ldap_search_time_seconds{...,quantile="0.5"} 0.043channel_ldap_search_time_seconds{...,quantile="0.95"} 0.051channel_ldap_search_time_seconds{...,quantile="0.99"} 0.052Changes:
- Format: Histogram → Summary
- Percentiles: Reduced to
0.5, 0.95, 0.99(high cardinality optimization) - Buckets: Removed all histogram buckets (50+ → 0)
Migration:
- Replace
histogram_quantile()with directquantilelabel access - Update SLI/SLO calculations to use summary percentiles
Terminal window # Old queryhistogram_quantile(0.95, rate(channel_ldap_search_time_seconds_bucket[5m]))# New querychannel_ldap_search_time_seconds{quantile="0.95"} -
Processing Time Metrics
Before: Histogram with SLO buckets
scribe_processing_time_seconds_bucket{entryType="user",phase="diffing",le="0.001"} 5scribe_processing_time_seconds_bucket{entryType="user",phase="diffing",le="0.002"} 25[... many buckets ...]After: Summary with full percentiles
scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.5"} 0.004scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.75"} 0.007scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.9"} 0.015scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.95"} 0.050scribe_processing_time_seconds{entryType="user",phase="diffing",quantile="0.99"} 0.487Changes:
- Format: Histogram → Summary
- Percentiles: Added
0.5, 0.75, 0.9, 0.95, 0.99(standard set) - Buckets: Removed all histogram buckets
Migration:
- Update queries to use
quantilelabels instead ofhistogram_quantile() - SLIs can now use direct percentile values
Terminal window # Old queryhistogram_quantile(0.90, rate(scribe_processing_time_seconds_bucket[5m]))# New queryscribe_processing_time_seconds{quantile="0.9"} -
New Entry Codec Metrics
Added new compression and entropy metrics:
scribe_entry_encode_bytes{codec="lz4|zstd|none",kind="raw|compressed",quantile="0.5"} 1440scribe_entry_decode_bytes{codec="lz4|zstd|none",kind="raw|compressed",quantile="0.5"} 1440scribe_entry_encode_compression{codec="lz4|zstd",le="5.0"} 4scribe_entry_encode_entropy{le="25.0"} 137598Reports:
- Encoded and decoded sizes by codec.
- Compression thresholds at 85% and 95%.
- Entropy distribution used for compression choices.
- Percentiles
0.5, 0.75, 0.9, 0.95, 0.99.
- Performance Impact
v2.7.0 (2025-11-14)
Added
-
Virtual attributes are computed when requested — Large multi-valued attributes, including sets with more than 100,000 values, no longer need to be stored with every entry.
- Define them with LDAP filter expressions and variable substitution.
- Two patterns are available:
- Cross-reference: Compute relationships to other entries, such as every group a user belongs to through
groupMembership. - Self-reference: Filter with the current entry’s attributes, such as a
userLevelderived fromdepartmentNumber.
- Cross-reference: Compute relationships to other entries, such as every group a user belongs to through
- Values stay current without consuming entry storage.
- LDAP clients can request, filter, and sort virtual attributes like stored attributes.
- Existing database coverage accelerates virtual-attribute searches where applicable.
Configuration Example:
ldap {virtualAttributes {# Cross-reference: Find all groups where this user is a membergroupMembership {filter = "(member={{current.entryDN}})"value = "{{other.entryDN}}"}# Self-reference: Compute user level based on departmentuserLevel {filter = "(departmentNumber=Executive)"value = "senior"}}}transcribes = [{type = "user"ldap {attributes = """cn, sn, mail, groupMembership, userLevel"""# groupMembership and userLevel will be computed virtually}}]Common uses:
- Large multi-valued attributes such as
equivalentToMeon roles, without timeouts or database bloat. - Reverse lookups without redundant stored data, such as every group a user belongs to.
- Values derived from an entry’s own properties, such as access levels or flags.
See LDAP Configuration for configuration and more examples.
Fixed
- Checkpoints advance during continuous synchronization — They previously advanced only while the system was idle, delaying offline-delete detection and reconciliation under sustained traffic.
- Compression monitoring uses 40–50% fewer time series — Memory use and dashboard query time drop while actionable thresholds remain available. Existing dashboards need no changes.
- LDAP connection metrics no longer become negative — Prometheus now reports the active connection count accurately.
- Extended DN searches return accurate matches — LDAP filter processing now handles extended DN matching correctly.
- Forwarded LDAP operations carry more diagnostic context — Logs now identify the relevant entry types for configuration and troubleshooting.
- Common operational-attribute filters require less database work — LDAP searches avoid unnecessary processing for these attributes.
- Database helper functions run with less overhead — Their lower-cost implementation reduces work during searches.
- Searches use configured indexes more reliably — IdentityScribe now keeps the statistics needed to choose them.
- LDAP forwarding metrics register reliably — The reorganized metrics prevent registration errors. Existing dashboards must be updated for the new format.
v3.0.0-rc.3 (2026-05-15)
IdentityScribe v3 is a major platform release for operating and integrating identity data at scale. It adds REST, GraphQL, and MCP access; the built-in Operator UI; embedded documentation; OpenTelemetry-native operations; and large-directory query performance improvements for sorted, filtered, prefix, substring, and cursor-paginated searches.
This release includes breaking database, configuration, endpoint, health, and metrics changes. Plan an upgrade window and start with Upgrading IdentityScribe.
Highlights
- Multi-channel identity APIs — REST/OpenAPI, GraphQL/GraphiQL, MCP, API discovery, streaming export, and consistent identifiers across channels. See REST, GraphQL, and MCP.
- Operator UI and embedded docs — Portal, Entries, Changes, Observe,
/docs, and/ref/*deep links ship with the product. See Monitoring. - Authentication and authorization — OIDC bearer tokens, browser sessions, access rules, channel-specific auth, LDAP bind refinements, and safer ProxyAuth behavior. See Authentication.
- OpenTelemetry-native operations —
/observe/*, MicroProfile health, Prometheus/OTLP metrics, wide logs, pressure signals, Grafana dashboards, Docker Compose, and Helm assets. See Observability and Monitoring. - Large-directory performance — Faster equality, prefix, substring, range, OR, sorted, partial-match, long-text, and cursor-paginated searches, with automatic fallback when acceleration is not suitable. See Database Tuning.
- Change history and point-in-time access — REST and GraphQL access to entry history, temporal lookups, verification timestamps, and operational naming attributes. See Data Model.
- Upgrades catch unsafe configurations earlier and fail more clearly — PostgreSQL 17/18 support, storage hardening, startup validation, clearer error codes, support IDs, and cleaner shutdown and cancellation behavior make upgrades easier to diagnose. See Upgrading and Failures.
Breaking Changes
Database support
PostgreSQL 15 and 16 are no longer supported. Upgrade to PostgreSQL 17 or later before installing v3; PostgreSQL 18 is recommended. See Upgrading IdentityScribe.
HTTP, health, and endpoint model
HTTP channels now use one socket configuration model. Deployments that configure old monitoring listener keys such as monitoring.hostname or monitoring.port must move those bindings to http.host, http.port, or http.sockets.*. See the HTTP Server Guide.
Status, health, and legacy monitoring paths changed. Monitoring probes and dashboards using /status, /healthy, or /-/* must move to /observe/*, /readyz, /livez, /startedz, /healthz, or /metrics. JSON health responses now follow MicroProfile Health, so clients parsing the old /healthy body must update their response handling. See Upgrading: endpoints.
Configuration and environment
Environment variable prefixes are standardized on SCRIBE_*. Replace IDENTITY_SCRIBE_* and SCRIBE_TELEMETRY_*. See Upgrading: environment variables.
Connection hints now use a typed session-flags {} object. String-based flag lists and flat work-mem configuration fail startup. See Database Configuration.
Logger configuration is consolidated to the canonical loggers. Old logger keys are removed. See Upgrading: logging.
ldap.authentication-required is removed. Use channels.ldap.auth.enabled. See Authentication.
Observability and client contracts
Metrics now use the scribe.* namespace. Update Prometheus queries, alerts, and dashboards. See Observability.
Error codes are standardized to SCREAMING_SNAKE_CASE. Clients matching on error codes must update their mappings. See Failures.
Broad queries that can span multiple entry types must include an explicit type constraint. Ambiguous requests fail early instead of running against an unintended scope. See Upgrading: query scoping.
Virtual attribute placeholders use {{self.*}}. Legacy {{current.*}} placeholders fail startup with migration guidance. See Upgrading: virtual attributes.
The bundled Grafana datasource now uses OAuth passthrough on the monitoring socket. Existing anonymous Grafana setups must configure OAuth or explicitly opt into temporary anonymous access during migration. See Monitoring.
Added
APIs and integrations
- REST API and OpenAPI UI — Query entries, look up individual identities, stream CSV/JSON/NDJSON/LDIF/JSON-LD exports, read change history, use conditional requests, choose strict or lenient attribute validation, and work with JSON, FleX, SCIM, or LDAP filters from HTTP clients. See REST Channel.
- GraphQL API and GraphiQL UI — Query entries, history, point-in-time state, connection counts, persisted queries, and schema-generated types with Relay-compatible identifiers. See GraphQL Channel.
- MCP channel — AI assistants can query identity data, reference docs, schemas, health, and diagnostics through
/mcpand/observe/mcp. See MCP Channel. - API discovery —
/.well-known/api-catalog, REST specs, and GraphQL schema endpoints make the enabled API surface discoverable. See Channels. - FleX query language — A forgiving filter syntax is available for runtime queries and configuration filters. See Filters Reference.
Operator UI and documentation
- Operator UI — Portal, Entries, Changes, and Observe views provide browser access to system status, identity data, history, pressure, health, JVM metrics, and remediation guidance. See Monitoring.
- Embedded documentation site —
/docsships with guides, reference docs, and/ref/*deep links so operators can jump from config, telemetry, and error references into the matching documentation.
Authentication and access control
- Bearer token authentication — Validate OIDC JWTs offline, support multiple providers, and use the same identity model across REST, GraphQL, MCP, and LDAP. See Authentication.
- Access rules — Define first-match policies using identity, service, request, time, and environment context. See Access Rules.
- Browser sessions — Built-in UI sessions, secure cookies, OIDC redirect handling, and per-UI auto enablement. See Authentication.
- LDAP auth refinements — DN/username bind handling, channel-specific auth settings, unified failure delay, operation-specific gating, strict base enforcement, bind-filter checks, and backend delegation when channel auth is disabled. See LDAP Channel.
Observability and operations
- OpenTelemetry-native observability — Prometheus metrics, OTLP traces/metrics, authenticated metrics export, exemplars, pressure metrics, and structured wide event logs. See Observability.
- Observe endpoints and API UI — Status, health, doctor, pressure, services, indexes, channels, config, license, hints, recommendation history, attribute coverage, query recommendations, and operational statistics are available under
/observe/*. See Monitoring. - Monitoring bundle — Grafana dashboards, Docker Compose, and Helm assets ship with the distribution. See Monitoring.
- Rule-based log filtering and error classification — Include or suppress wide-log events with glob patterns and LDAP-style filters, and separate noisy client errors from server-health signals. See Logging and Observability.
- Support workflow — Failure responses expose IDs and headers that operators can send to support. See Failures.
Data access and history
- Change history API — REST and GraphQL access to global and per-entry changes, patches, merged views, metadata, and time filters. See REST Channel and GraphQL Channel.
- Point-in-time lookup — Retrieve entry state at a timestamp, relative time, or change cursor. See GraphQL Channel.
- Operational identity attributes —
entryID,entryName,entryRDN, andverifiedTimestampare available across channels. See Data Model. - Virtual attributes can delegate upstream and vary by entry type — REST and GraphQL also validate them more strictly. See LDAP Configuration.
Performance and scale
- Large-directory query acceleration — Common equality, prefix, substring, range, OR, sorted, partial-match, long-text, and cursor-paginated searches now use faster paths where safe. Broad or unsupported requests fall back automatically. See Database Tuning.
- Cursor pagination at scale — Sortable single-valued and multi-valued attributes now page more predictably at deep cursors, avoiding several previously pathological large-directory plans. See Database Configuration.
- Large-directory searches adapt safely to observed traffic — IdentityScribe uses query traffic and maintenance statistics to keep performance predictable across data distributions. It uses safe exact choices while evidence is still warming. See Database Tuning.
- Search and sort controls — Operators can tune advanced search, sort, and preparation behavior when needed. See Database Configuration.
- Backpressure under load — HTTP APIs fail fast with
503andRetry-After; LDAP honors configured time limits. See Database Configuration. - Transcription throughput controls — Bounded workers and queue capacity reduce memory pressure during high ingest. See Transcribes Configuration.
Upgrade and data safety
- Startup detects ambiguous storage before writing — It catches naming collisions and repairs legacy database layout issues. See Upgrading.
- Startup and schema validation — REST/OpenAPI and GraphQL naming collisions fail early with actionable errors. See REST Channel and GraphQL Channel.
- Startup handles orphaned transcribe types explicitly — It can warn, fail, or ignore transcribe types found in the database but absent from configuration. See Database Configuration.
- Ignored LDAP contexts — Selected LDAP base DNs can bypass local storage and delegate directly to the upstream LDAP backend. See LDAP Channel.
- Faster startup and safer maintenance — Service startup, index builds, readiness reporting, and request cancellation have been tightened for large deployments. See Deployment and Monitoring.
Changed
- Unified HTTP configuration — REST, GraphQL, Observe, docs, and browser UIs share one socket model with named sockets, CORS, compression, request limits, and graceful shutdown. See HTTP Server Guide.
- REST cache semantics — Lookup responses support ETag and Last-Modified validators; search/export responses default to no-store. See REST Channel.
- REST strict/lenient validation — Clients can request strict unknown-attribute handling through
Prefer: handling=strict. See REST Channel. - GraphQL and REST naming — Type, field, and component names are sanitized deterministically with collision guardrails. See REST Channel and GraphQL Channel.
- Transcribes object syntax — Object syntax is preferred and deterministic. Legacy array syntax still works but logs a deprecation warning. See Transcribes Configuration.
- Logging and operator output — Startup summaries, pretty logs, exception logging, third-party logger controls, and routine log noise filtering are cleaner. See Configuration and Observability.
- Observe entry point and layout —
/ui/observelands on Inbox so open recommendations are visible first. System status renders as a collapsible header with per-operator collapsed-state, and previously closed recommendations that re-appear surface above Open in their own Regressed section. See Monitoring.
Fixed
-
Faster sorted substring search — Sorted substring (contains) searches now pick the faster path more reliably at small and medium directory sizes. See Database Tuning.
-
Authentication fails closed — Empty bearer tokens and unsupported ProxyAuth forms return authorization failures instead of inconsistent behavior.
-
Bearer DN claims enforce scope — Bearer
dnclaims now honor the configured LDAP base, matching DN and username ProxyAuth paths. -
UI auth gating respects
auth.enabled=false—/uiand deep links no longer redirect to login when auth is disabled. -
Beta upgrade startup — Migration checksum handling no longer blocks affected beta-based upgrade paths.
-
Timeouts cancel database work and timestamps stay consistent across time zones — Shutdown is quieter, and failed or timed-out requests promptly cancel their remaining work.
-
Backward paging reports and streams cursor metadata correctly — Clients receive complete pagination state in both directions.
-
Delegated virtual attributes forward without false self-reference warnings — Forwarding and validation now agree on self-references.
-
Authentication paths fail closed more consistently — OpenID Connect, token introspection, trusted client IP handling, and HTTPS certificate-chain limits now reject uncertain states.
-
Reconciliation and history preserve the right entry state — Distinguished-name changes, temporal lookups, history rewind, and change-history streams now return correct results and surface invalid requests as structured errors instead of silent success.
-
Large searches avoid result-boundary errors — Negated filters, large value ranges, cursor pagination, and sorted result boundaries no longer hit edge cases that could return incorrect rows.
-
REST, GraphQL, LDAP, and MCP honor their documented contracts — Exports enforce row-limit and pagination rules before committing responses, GraphQL returns standard error fields and per-entry changes reliably, LDAP Virtual List View jumps work for common single-sort requests, and MCP tools honor standard arguments and numeric limits.
-
Operational signals report their state reliably — Collector endpoint configuration, telemetry lifecycle handling, Prometheus compression negotiation, and index-build status tracking now agree with the running system.
-
The Operator UI preserves navigation state and sanitizes external links — Login redirects preserve query state, entry and history views avoid stale navigation data, and Observe deep links and sidebar states render consistently.
-
Documentation links and examples match the shipped product — Generated and reference material no longer points to unavailable fields or stale commands.
Deprecated
- Legacy config key spellings — camelCase and underscore_case keys still work but log warnings. Use kebab-case keys. See Configuration Reference.
- Legacy transcribes array syntax — Array syntax still works but logs a deprecation warning. Use object syntax keyed by transcribe type. See Transcribes Configuration.
- Legacy channel auth fallback — Use
channels.<name>.auth.enabledinstead ofchannels.<name>.authentication-required. See Authentication.
v3.0.0-rc.4 (2026-05-28)
Fixed
- Approximate (
~=) searches return more useful matches and run faster — LDAP~=filters and the equivalent REST/GraphQL approximate match now find compound names such as “Michael Schmidt” more reliably, while single-field searches on large directories complete faster. Very short search terms still return no matches to protect large directories from expensive broad scans. - Approximate searches across multiple fields avoid unnecessary full-directory work — Searches that combine approximate conditions across fields configured for substring search now use the faster available lookup with the same result set as before. Fields that are not configured for substring search continue to use the safe compatibility path.
- Combined prefix searches across configured search fields are faster — Searches that combine several prefix-searchable attributes with entry name or distinguished name filters now avoid unnecessary full-directory work when only a few entries match. This improves broad search-box queries in large directories while preserving result order and cursor pagination.
- Custom attributes missing from equality and prefix indexes —
indices.value-matchandindices.partial-matchsettings (and theSCRIBE_INDICES_VALUE_MATCH/SCRIBE_INDICES_PARTIAL_MATCHenvironment variables) were silently ignored when set. Only the built-in baseline attributes received equality and prefix indexes. Custom equality and prefix indexes are now created as configured. - Abandoned REST count/HEAD and GraphQL requests stop sooner — REST
?include=count, RESTHEAD, and GraphQL directory queries no longer keep database work running indefinitely after the client stops waiting. REST count/HEAD requests followchannels.rest.connection-hints.statement-timeout(SCRIBE_REST_STATEMENT_TIMEOUT) when configured and use a 30-second default otherwise; GraphQL requests use a 30-second execution deadline. - Searches preserve requested filters and result shapes more consistently — Directory searches with repeated attribute predicates, sorted filters, multi-type results, continuation pages, and point-in-time lookups now preserve the caller’s filters, connection hints, selected fields, and result column names more reliably.
- Cancelled searches release resources more safely — Count-only searches, point-in-time lookups, and streams cancelled while opening a database connection now use the same cancellation, timeout, and connection policy as normal searches, avoiding leaked connections or permits after callers stop waiting.
- GraphQL connection responses are more predictable — Connection queries now return requested
pageInfoand counts together, support larger configured pagination limits correctly, and handle malformed POST bodies without surprising parsing behavior. - REST/OpenAPI export contracts are documented more accurately — Change events now expose their runtime entry identifiers in the API schema, and search export responses document the supported media types and download headers.
- Query diagnostic reports are safer to share and easier to act on — Redacted support exports avoid raw search values, preserve the context Kenoxa support needs, explain when timing evidence is unavailable, and avoid recommending coverage changes that are already satisfied.
- Prefix searches recommend the right index setting — Queries that filter by a “starts with” attribute now point operators to
indices.value-matchinstead ofindices.partial-match. Attributes that are only ever searched by prefix can be removed fromindices.partial-match; combined prefix-and-substring workloads keep both recommendations. - Observe recommendations resolve more consistently — Inbox and query recommendation links now open the matching detail views more reliably, recommendations that point to expired query evidence are hidden, and storage coverage views use the available screen width more effectively.
- Ingestion and maintenance edge cases are handled more safely — Interrupted throttling no longer drops a live LDAP entry, reconciliation startup failures clean up active sync work, transient LDAP search interruptions reconnect with bounded warnings, and maintenance scheduling now recognizes threshold-only soft schedules.
- Monitoring and deployment bundles start more reliably — Helm health probes, Grafana OAuth passthrough, production replica defaults, monitoring-only datasources, full-stack Compose startup, and shutdown error reporting now match the runnable deployment shapes.
Changed
- Single-attribute approximate searches on short common names may return fewer matches — Approximate matching is more selective for short terms against attributes that usually hold a single word, such as
givenname. A search likegivenname ~= "mic"may return a smaller set than in prior releases. Multi-field approximate searches and approximate searches against attributes that commonly hold multiple words, such ascnordescription, are unaffected. Contact support if a specific attribute needs different matching behavior. - Index attributes are fetched automatically — Attributes listed in a transcribe’s
indices.value-match,indices.partial-match, orindices.sortableare now fetched and stored automatically. They no longer need to be duplicated inldap.attributes. - Kubernetes readiness now tracks traffic safety —
/readyzand JSON readiness report when the pod can safely receive requests. Scripts that need to wait for initial ingest and required index work to finish should use/observe/convergence. See Endpoints. - Observe recommendations are retained across restarts by default — Recommendation history and query diagnostic reports now remain available after restart. Set
monitoring.hints.persistence.enabled = falseto keep recommendations memory-only, ormonitoring.hints.persistence.clear-on-startup = trueto start each run with an empty recommendation history. - Query diagnostics are easier to share — Slow-query rows, coverage evidence, and recommendation links now open a report page that starts with operator actions and can export a Redacted or Full support bundle when Kenoxa support requests it.
- Diagnostics and operator signals are easier to interpret — Reports preserve troubleshooting context and count repeated observations consistently, ingest lag severity matches the documented thresholds, and Observe recommendation pruning avoids deleting concurrent lifecycle updates.
v3.0.0-rc.5 (2026-05-31)
Added
- The Queries tabs now explain how to turn on query statistics — When query statistics are unavailable, the Slow Log and Stats tabs show the missing setup step, copy-paste commands, and a link to the docs. The hint distinguishes a missing extension from a database library that still needs to be loaded.
- Optional auto-enable of query statistics for development and staging — Set
database.auto-create-query-stats-extension = trueto let IdentityScribe create the query statistics extension at startup after PostgreSQL has loaded the required library. The default isauto(on in development, off everywhere else), so production is unchanged unless you opt in. See Enabling query statistics.
Changed
- Query diagnostic reports explain multi-field substring searches more clearly — Support reports now show whether each searched field used the faster path or a safe fallback, with the reason when fallback was required. These rows previously reported that estimation was not captured, which made shared reports harder to act on.
Fixed
- Licensed deployments start without configuring an audience — License verification no longer fails when
license.audienceis left unset. The licensee your license was issued to is read from the signed license itself, so a valid license works out of the box. Setlicense.audience(or theSCRIBE_LICENSE_AUDIENCEenvironment variable) only when you want a deployment to match a specific licensee name. Previously, a deployment that did not setlicense.audiencecould fail to start with anInvalid audienceerror. - Prefix searches across substring-search fields are faster — Searches that combine several “starts with” conditions across configured search fields no longer fall back to full-directory work when a faster bounded lookup is safe. Large-directory searches return sooner with the same matches, ordering, and cursor pagination as before. Broad searches keep the safer path automatically, and no configuration change is required.
- Query statistics appear as soon as the extension is enabled — Turning on query statistics after IdentityScribe was first deployed no longer needs a redeploy or a follow-up migration; the Queries tabs and
/observe/stats/queriespick it up on the next refresh. Creating the extension before loading the database library no longer makes the endpoint fail; it reports the missing setup step and points to the fix. - Long prefix searches no longer admit neighboring values — Prefix searches with very long values now check the full requested value after using accelerated narrowing, so entries that only share the stored leading segment are no longer included. Normal short prefix searches keep the same fast path.
- GraphQL field-name docs match the served schema for mixed-case hyphenated attributes — The GraphQL guide now shows the exact field name exposed for attributes such as
DirXML-EntitlementRef, so generated examples, schema exploration, and documentation agree.
v3.0.0-rc.6 (2026-06-03)
Added
- LDAP setup checks now appear at startup and in Observe diagnostics — Startup now checks whether the configured LDAP bind mode and account can read the attributes needed for reliable transcription. Fatal problems stop startup with remediation, while non-fatal warnings appear in startup output and Observe diagnostics without changing Kubernetes readiness. This helps operators distinguish empty data from authentication or directory permission problems.
- Download a redacted setup report for support — The Operator UI dashboard can prepare a setup report to attach to a support ticket for first-run problems such as a missing REST API, a UI that shows no entries, documentation that does not load, or directory data that never appears. The report captures which APIs are enabled and where they are served, sockets and runtime ports, sign-in state, documentation availability, and whether the service can read your directory, with each check labeled passed, failed, skipped, or unavailable. Passwords, tokens, URL credentials, and other secrets are removed before download. See Reporting to support.
Changed
- Exported traces no longer carry raw directory identity by default — With trace export enabled (
monitoring.traces.enabled = true), exported spans previously included raw distinguished names, usernames, subject identifiers, entry UOID and UUID, and request URLs, which reached whichever collector or APM you export to. These identity values are now removed by default; enumerations, counts, durations, request outcome, and query shape are still sent unchanged, and internal wide logs keep full detail. To send specific identifiers to a collector you trust, set per-key strategies undermonitoring.traces.redaction— for example"scribe.entry_uoid" = identityto correlate spans by entry, or"auth.effective_dn" = hashto group by subject without the name. Distinguished names, usernames, and URLs accepthashbut are never sent raw.
Fixed
- Wide logs apply the configured per-key redaction rules — Wide logs now redact attribute values according to
monitoring.log.redaction, including the built-in defaults that hash distinguished names (*dn*) and truncate email addresses (*email*). Previously, glob patterns and dotted attribute keys in this setting were silently skipped, so distinguished names and email addresses could appear in wide logs in full despite the configuration. The always-on secret redaction (passwords, tokens, credentials, cookies) and trace export redaction were unaffected. - The Inbox groups repeated recommendations into one card per fix — When the same coverage recommendation (for example, missing sortable, value-match, or partial-match coverage on an attribute) is observed across many searches, the Inbox now shows a single card for each distinct fix instead of one card per observation. Each card shows how many observations support it and when it was last seen, and snooze, apply, and dismiss act on the whole group at once. The full evidence behind a card stays available from its detail view. Previously, a handful of real fixes could appear as hundreds of duplicate cards, and acting on one card did not affect the others.
- The Operator UI works when public API documentation is private — With production defaults, the REST data API remains available while the public API reference is off. The Entries view now loads its type information without depending on the public
/apipage, and dashboards and startup output no longer present documentation links that would return 404. Previously, a secure first-run setup could make the UI look empty or point operators to/api. - LDAP search responses preserve requested attribute-name casing — When an LDAP client requests
objectClass,ENTRYUUID, or another explicit spelling, IdentityScribe returns the attribute using that requested spelling while matching stays case-insensitive. Previously, local LDAP responses could return the configured spelling instead, which surprised clients that compare response attribute names. - Observe API documentation matches the channel status response — The OpenAPI document now describes the REST, GraphQL, MCP, and authentication availability fields returned by
/observe/channels, so clients that validate Observe responses against the spec no longer reject the channel status response. Previously, the response was valid at runtime but missing from the generated API contract. - Observe API documentation matches doctor status responses — The OpenAPI document now includes the
noisystatus returned by/observe/doctorfor informational checks, so clients that validate Observe responses against the spec no longer reject a valid doctor response. Health and readiness behavior are unchanged. - The API catalog lists only documentation links that are served —
/.well-known/api-catalogno longer advertises REST or GraphQL reference, schema, or playground URLs that return 404 when public API documentation is turned off (the production default). Each enabled channel’s base URL stays listed so the data API stays discoverable, and the documentation, schema, and UI links reappear once you enable them. Previously, the catalog could send API discovery clients to/api.json, the/apireference page, or the GraphQL schema even when those endpoints were disabled. - Searches on attributes from older databases are repaired automatically on upgrade — On databases first created by earlier versions, searches filtering on certain attributes (for example
objectClass) could fail at runtime. Upgrading now reconciles the affected databases automatically, so those searches succeed with no change to your attribute configuration — keepobjectClassspelled asobjectClass. No manual steps are required.
v3.0.0-rc.7 (2026-06-12)
Breaking Changes
- Observe endpoints require authentication by default — Anonymous requests to
/observe/doctor,/observe/channels, and other Observe JSON endpoints now return401unless an operator session or accepted credential is present. Migration: For trusted local evaluation, setmonitoring.observe.auth.enabled=falseorSCRIBE_OBSERVE_AUTH_ENABLED=false. For shared environments, sign in or send an approved credential. - Browser sign-in sessions require production keys — Production deployments that enable browser sign-in now fail startup until session-cookie keys are explicitly configured. Migration: Configure session-cookie keys before enabling browser sign-in in production; development setups keep local convenience behavior.
- GraphQL schema and introspection require authentication when anonymous access is disabled — Requests for schema SDL, introspection JSON, and helper routes (
/graphql.json,/graphql.sdl,/graphql/schema.*) now match query execution access rules. Migration: Send an approved credential to schema endpoints, or enable anonymous access. - Explicit distinguished-name binds are confirmed by the directory — LDAP binds with an explicit
dn:value are now accepted only when the directory confirms that distinguished name. Other authentication methods can no longer authorize a caller-supplied DN they cannot prove. Migration: Use username binds or an authentication method that can prove the DN. - Insecure authentication-provider TLS is development-only — Production deployments that set
auth.http.ssl.insecure=truenow fail startup. Migration: Configureauth.http.ssl.trust-storewith the provider CA, remove the insecure setting, or keepauth.http.ssl.insecure=trueonly for local development. - Credentialed CORS cannot reflect every origin — HTTP configurations that combine
allow-credentials=truewith reflected origins now fail startup because they would grant credentialed browser access to any requesting origin. Migration: List trusted origins explicitly, or turn credentials off for reflected-origin development setups.
Added
- Query diagnostic reports include corpus context — Reports now show directory scale, field coverage, statistics freshness, and replay guidance. When context is unavailable, the report and export call out the missing data directly.
- Change history gains hot-entry ranking across UI and APIs — The Operator UI, REST (
/api/changes/hot), GraphQL (hotChanges), and MCP (hotChanges) now rank the most frequently changed entries in a time window, with the same filters and cursor paging as the change feed. - GraphQL and MCP lookups can compare entry states over time — Integrations can now request one entry at two points in time through GraphQL or MCP. GraphQL returns the before and after entry states, while MCP lookup responses include before and after details plus a JSON Patch summary for the selected attributes.
- Observe highlights slow operator workloads — Observe Inbox and Queries now surface when entry searches, lookups, change history, hot-entry rankings, and entry comparisons are slow or recurring, with grouped cards, timing summaries, and next steps for each pattern. Admin operators see a timing chip on entry search, lookup, change, and comparison views that links to the matching Observe workload detail. Support can download a redacted workload report without exposing request identities or filter values.
- MCP change-history tools match REST and GraphQL — The MCP
changestool acceptssince/untiltime bounds,range=allfor unbounded history, andbeforefor backward pagination. See MCP Channel. - Startup warns when legacy configuration keys are ignored — v2 configuration paths that are present but no longer read are now reported at startup so upgrades do not silently keep obsolete settings.
- Directory servers with legacy RSA cipher suites can be reached with an explicit opt-in — TLS_RSA cipher suites are disabled by default because they lack forward secrecy. Listing the required suite in the LDAP connection’s
ssl.cipher-suitessetting re-enables it at startup (must be literal values, not environment-variable substitution). IdentityScribe logs a warning while the opt-in is active; prefer enabling modern (ECDHE) cipher suites on the directory server.
Changed
- API reference pages use newer embedded explorers — REST, Observe, and GraphQL documentation pages ship with refreshed bundled assets for better schema browsing, search, and local request trials. Same-origin Try Request calls keep browser sign-in credentials, while offline deployments continue to use bundled assets.
- Change history opens with a broader recent window — The Operator UI and generated API examples now start with the last 24 hours instead of one hour, making recent activity easier to discover in low-change directories. API clients can still request one hour,
range=allwith paging, or any supported time range explicitly. - Entry comparison is clearer and shareable — In the Operator UI, compare mode keeps time range and event filters with the event timeline they affect, while the comparison keeps its before and after controls in the diff. When a selected range does not include the compared points, the timeline dims the outside-range area. Operators can choose before and after points from a change timeline, a compact change-density view, or explicit timestamps. The selected comparison stays in the URL so the view can be shared.
- Observe UI is easier to scan and act on — The Services view focuses on status and action items first, with LDAP forwarding details on their own tab including forwarding rates, reason breakdowns, and guidance for strict-isolation setups. Recommendation detail pages now summarize linked evidence and show next steps, related views, and verification guidance. The configuration reference explains default protection on Observe endpoints and which settings control write actions.
- Observe evidence pages are easier to compare and share — Workload evidence, storage coverage, Inbox recommendation detail, and Query Diagnostic Report pages now follow a consistent evidence-first layout with action summaries, related links, and support export controls where available. Diagnostic reports keep timing and captured request samples together, while lower-level request details stay in a collapsed appendix. Dates, durations, counts, byte sizes, percentages, and rates use the same display rules across rows, detail panels, reports, and exports.
- Relationship modeling and deployment guidance cover common production choices — Attribute modeling guidance explains when to store relationship data as regular attributes versus virtual attributes, with group, role, manager, and owner examples. The deployment guide now covers single-writer topology (one non-readonly instance for transcription and maintenance, with optional read-only replicas for query channels). See Attribute Modeling and Deployment.
- Wide operational logs omit raw URL query strings by default — HTTP error diagnostics no longer write full query strings into wide logs unless an operator configures log redaction otherwise. Trace export already omitted this field; wide logs now match that default.
- REST searches have a default server-side deadline — REST searches now use a 30-second server-side deadline when no request-specific search limit is configured, matching GraphQL behavior and preventing slow searches from running indefinitely.
- Single-entry lookups are faster in large directories — REST, GraphQL, and LDAP requests that ask for one exact identity now avoid unnecessary broader search work. Exact LDAP base-DN lookups were about 40× faster in benchmarks; typed REST/GraphQL lookups by DN, UUID, numeric ID, or not-found result were about 10–25× faster. Selected attributes, access checks, errors, and broader searches keep their existing behavior.
- Change history and entry comparison requests are faster in large directories — Change history responses that do not request event details now avoid extra work, and entry comparisons return faster when comparing two points in time.
- High-entropy values are stored without wasted compression effort — Attribute values that are already random or compressed (certificates, encrypted or binary blobs) now skip the compression step, lowering write-time work on incompressible data. Values read back are unchanged; existing stored entries are unaffected.
- Large sorted pages have a higher safety ceiling — The default continuation safety limit now leaves more headroom for very large directories, so eligible sorted pages can finish without falling back too early. If you override
database.continuation.window.absolute-scan-cap, review that value against the new default before upgrading.
Fixed
-
Paginated searches no longer omit, duplicate, or misorder edge-case results — The fixes cover:
- Sorted searches that filter on one attribute and sort on another, as well as unfiltered sorted searches, now include entries that match the filter but have no value for the sort attribute. Entries with no sort value are placed after all valued entries for ascending sort and before them for descending sort, matching RFC 2891. Paging through no-value entries stays fast on large directories.
- OR-filter searches now deduplicate overlapping matches and keep entries without a sort value in page cursors.
- Searches sorted by entry name now use consistent continuation values, so moving through pages does not skip or duplicate rows when full DNs and short entry names sort differently.
- Virtual-attribute searches (such as group membership) now avoid unnecessary directory-wide work while preserving matches, ordering, and pagination.
- Large sorted searches that combine filters, prefix matching, cursor paging, or virtual attributes now avoid unnecessary broad work more often while preserving matches, ordering, and pagination on large directories.
- Searches that combine an exact match with additional conditions now apply all of them instead of returning broader results.
- Requests that include an empty alternative inside a larger filter now preserve the client’s intended match behavior.
- Filters on mixed-case attribute names (uppercase letters) now match and sort correctly.
- Query diagnostic reports now explain when sorted searches with OR alternatives cannot use the faster optimization.
- During startup, upgrade, or maintenance windows, sorted searches over multi-valued attributes wait for prepared acceleration data before using it, preserving correctness.
-
The Operator UI keeps state and formats values consistently —
- Opening
/uinow loads the Operator UI reliably in packaged deployments instead of showing a missing-page fallback. - Sign-in recovery works for expired and missing sessions: navigation and background refreshes show a sign-in prompt that returns operators to the same page after login; opening a protected page without a session redirects directly to sign-in.
- The browser sign-in screen now follows the selected Auto, Dark, or Light color mode instead of always rendering in dark mode.
- Recommendation times stay stable when browser clocks differ: future-dated observations from the server are treated as current local observations, so negative “ago” labels no longer appear.
- Observe refreshes show partial data honestly: if one panel fails, the UI marks data as partial, clears stale health details, and points operators at the affected area.
- Entry history and change views keep a recent time range selected, preserve that range while moving through timeline entries, and open entry links through the app router instead of briefly changing and reverting the page.
- Modals and panels close with Esc or an outside click. The attribute change sparkline keeps its most recent point. Database Health and Coverage panels ignore superseded background refreshes. The Observe view no longer persists raw diagnostic text. Free-text
~=searches load back into the query builder. Entry comparisons stay distinct when two points share a timestamp. Observe scope filtering matches regardless of letter case. - Light mode no longer looks disabled: cards, tables, status chips, and recommendation rows use clearer contrast.
- Multi-value diffs read consistently: an attribute side with no removed or added values no longer shows a contradictory “(no changes)” label, and before and after value lists now page together.
- Comparison markers on the change-density timeline keep their position while events load and when the time range changes. The timeline axis matches the selected range.
- Dense bursts in entry history and attribute change indicators now expand across their local time span instead of appearing as a single bar.
- Header copy buttons now report success or failure and use a fallback when direct clipboard access is unavailable.
- The UI recovers after a new deployment: when a browser has an outdated app open, the view surfaces an error with a reload option instead of showing a blank view. Entry list links encode the entry type so types with reserved URL characters open correctly.
- Observe Inbox badges now count grouped recommendations that still need review, so dashboard and sidebar totals match the Inbox list.
- Point-in-time links restored from change cursors now open the intended historical entry view. Change-history toolbar controls keep a stable layout on narrower screens.
- Opening
-
Change history fixes —
- Previous-page navigation works correctly: moving back requests entries before the current cursor instead of showing the next page again.
- Affected-attribute filters handle punctuation safely: quotes, semicolons, and other punctuation are treated as ordinary text.
- REST change-history filters accept the same singular and plural entry-type names as other directory requests.
- Search cursors keep working when clients rely on the default page size.
- Copied entry links keep special characters intact.
- URL-restored Operator UI filters no longer rewrite active searches.
- Per-type change URLs such as
/ui/entries/users/changesnow redirect to the global Changes view with the entry-type filter applied. - Hot-entry ranking requests now honor deadlines and disconnects like other change-history requests.
-
Startup and operations —
- Startup after an interrupted initial sync no longer skips entries: IdentityScribe detects the incomplete state and performs a full re-enumeration. Affected entries are reprocessed and brought up to date. This also resolves a startup hang where a restarted sync worker could wait indefinitely for a startup gate already released in a previous run.
- Directory synchronization repairs stale ownership conflicts automatically: when an entry moves in the directory while IdentityScribe is down or retrying, synchronization re-checks the directory, releases stale local ownership, and retries the affected entry without advancing past unresolved work. Readiness stays unavailable while repair is pending and resumes after the database has converged. Monitoring now reports repair-pending and repair-completed states separately, and only unresolved repair failures are logged as errors.
- Transient directory errors during startup are retried automatically (up to twice) before startup is treated as failed.
- Threshold-gated maintenance jobs no longer run when every configured threshold signal is missing. IdentityScribe warns about the missing signal so operators can fix the setting instead of unknowingly bypassing the gate.
- Startup and monitoring logs are quieter during healthy operation: successful LDAP startup checks and database statistics refreshes no longer emit routine informational lines. Failures and warnings still appear.
- Intentional shutdown during startup is treated as a clean cancellation instead of a spurious failed start.
- Startup fails fast when a service fails during parallel startup: the failure surfaces promptly instead of waiting on the still-starting service and appearing to hang.
- Invalid HTTP socket protocol settings fail startup clearly instead of silently falling back to an unintended listener shape.
- Stalled initial synchronization is visible in monitoring: when a transcribe’s baseline has been restored but its initial scan is incomplete and the sync worker is stuck in a restart loop, the
scribe_ingest_sync_stalledgauge increments and theingest.sync_stalleddoctor check turns degraded. The readiness snapshot reason changes fromcoherent-restored-baselinetorestored-baseline-sync-incomplete. Setmonitoring.ingest.fail-readyz-on-failed-state=trueto also take the transcribe out of the readiness gate when its sync worker enters a terminal-failed state. - Ingest health now reports initial completion separately from current lag, so complete-but-lagging transcribes are not mistaken for incomplete startup work.
- Successful write batches still commit when statement cleanup reports an error after execution, preventing completed persistence work from being rolled back by cleanup failures.
- Fatal maintenance errors now surface to service failure handling instead of being lost during scheduled cleanup.
- Native-image deployments keep embedded documentation and UI assets available across repeated requests.
-
Security and redaction —
- Authentication logs are safe and useful for access debugging: wide logs show bounded details such as failure reason, method, issuer, and key id. Subject identifiers, usernames, and client addresses use marked short hashes. Passwords, bearer tokens, cookies, and Authorization headers remain always replaced. Wide logs also note when a single-valued attribute was truncated on read.
- JWT and token-introspection authentication accept configured public issuer URLs while still using the configured provider endpoint for discovery, so deployments with separate internal and public issuer addresses validate tokens consistently.
- Browser session cookies choose the secure-cookie variant from the trusted request security state instead of raw forwarded-protocol headers.
- Exported traces apply redaction consistently: linked trace metadata and unlisted numeric/boolean attributes are now covered, so configured identity and credential protections are applied before data leaves IdentityScribe.
- MCP directory tool responses render returned values safely: text is wrapped in a safe plain-text form before presenting as Markdown, so directory values cannot appear as commands, headings, or links.
- MCP lookup errors escape invalid identifiers before rendering Markdown, so rejected input cannot appear as headings, links, or code.
- Invalid API requests now name the rejected parameter and why. The Operator UI shows that detail in search and change views and clears stale search cursors.
- Unauthenticated browser asset access is limited to known static asset prefixes; application routes that contain
/-/now require authentication as configured. - LDAP proxy-authorization controls are rejected by local LDAP handling instead of trusting a caller-supplied delegated identity.
- Hyphenated API-key attributes are now covered by default telemetry redaction.
-
Channel APIs return consistent errors, metadata, and paging behavior —
- REST requests with blank optional parameters (
fields,range,since,until) now use the documented defaults. - Single-entry REST lookups report service failures correctly: if IdentityScribe cannot load an entry after the request has been validated, the response reports a service failure with clearer text instead of a conflict response.
- Point-in-time entry lookups accept the same identifiers (DN, UUID, numeric ID) as current lookups. Numeric-ID lookups can also return deleted historical entries, including response validators, instead of missing the reconstructed entry.
- GraphQL type names no longer collide with built-in scalars.
- GraphQL typed lookups return
nullfor malformed identifiers instead of surfacing resolver failures. - GraphQL schema helper requests follow the configured schema access rules, and hot-entry fields avoid naming collisions with configured entry types.
- Generated REST API descriptions remain valid for punctuation-heavy type names.
- Generated REST API descriptions now document lookup comparison responses accurately.
- REST and GraphQL searches honor cancellation, deadlines, and disconnects: they stop promptly and report cancellation or timeout instead of returning late results or a 500 error.
- Typed entry lookups accept short distinguished names: single-RDN identifiers such as
uid=jdoeresolve under the requested entry type’s configured base. Genericnode(id:)lookups and plain names keep existing behavior. - LDAP search controls meant for the backend directory are now forwarded instead of dropped.
- LDAP Virtual List View requests with extreme before or after counts are bounded safely instead of overflowing.
- LDAP type-detection searches preserve the attribute spelling clients depend on:
objectClassand similar filters keep that spelling in local responses when clients use default attributes or*selection. Explicitly requested spellings still take precedence; matching remains case-insensitive. - LDAP responses preserve canonical attribute names for synchronization metadata while keeping client-requested casing for explicitly requested attributes.
- LDAP product fingerprints are more stable: detection no longer changes its fingerprint only because a directory serves the same UUID attribute in a different value form.
- Forwarded LDAP searches no longer look like setup failures: they are recorded with bounded informational details instead of repeated warnings, keeping logs focused on real failures.
- Stored entries are checked for truncation and malformed content on read: incomplete records are rejected instead of returning partial data.
- MCP change-history responses escape missing identifiers safely, and MCP reference lookups remain available when the embedded reference index is unavailable.
- Time-range inputs that are too large to represent now return bounded validation errors instead of unexpected server failures.
- REST requests with blank optional parameters (
-
Directory and reconciliation —
- Reconciliation reports missing-entry deletes more reliably: it waits only for the deletes it just scheduled, and repeated delete batches that exceed the completion timeout are visible in telemetry.
- Reconciliation telemetry distinguishes entry types so operators can tell which transcribe a stuck or slow pass affects.
- Reconciliation verifies fallback matches before scheduling missing-entry deletes, avoiding deletes based on an unrelated distinguished name.
- Health checks report unhealthy during automatic restart backoff so load balancers stop sending traffic until recovery.
- MCP directory tools honor client cancellation: search, lookup, and change-history tools stop running when the client cancels.
- Range-filter searches keep their lower and upper bound behavior in large sorted result sets. Explicit entry-type filters keep the requested type scope for current and point-in-time lookups.
-
Recommendations and Observe —
- Recommendation configuration examples are copy-paste safe: entry-type comments now appear after the quoted attribute value instead of inside it.
- Slow-query recommendations open the right diagnostic report: Observe matches slow-query rows to the recorded directory query even when the database truncates or normalizes the displayed text. The match is retained across restarts after a query shape has been observed once.
- Inbox cards focus on slow directory searches that operators can act on and ignore routine maintenance noise.
- Observe Inbox and recommendation detail views stay responsive when many observations support the same fix.
- Pending recommendation evidence is saved during shutdown, so recent observations remain available after restart.
- Shutdown waits for in-flight directory ownership repairs before closing, keeping repair state consistent across restarts.
v3.0.0-rc.8 (2026-06-22)
Breaking Changes
- Subtree searches that don’t name an entry type are answered locally — A directory search across a base that spans more than one configured context, without naming an entry type (for example a virtual-list-view browse from a directory client), is now answered from IdentityScribe’s own data instead of being forwarded to the upstream directory. Searches that already name a type, or target a single configured context, keep their current behavior. Migration: To keep forwarding these searches to the upstream directory, set
channels.ldap.untyped-search = delegate(orSCRIBE_LDAP_UNTYPED_SEARCH=delegate). Mark any subtree that must be served by the upstream directory as anignore-contextsentry. - Search diagnostics use one consistent model — Observe, traces, and support reports now describe search outcomes consistently, and every search strategy contributes timing evidence. Migration: Replace dashboards or alerts that depend on older internal series or labels with the supported query-latency signals in the Telemetry Reference and use Observe reports for per-search diagnostic detail.
- The Observe MCP endpoint requires authentication by default — Requests to the Observe MCP endpoint (
/observe/mcp) now require an operator session or accepted credential; anonymous requests are denied. This endpoint previously inherited the global monitoring auth setting, which left it open whenever global authentication was off. Migration: For trusted local evaluation, setmonitoring.mcp.auth.enabled=falseorSCRIBE_MONITORING_MCP_AUTH_ENABLED=false. For shared environments, sign in or send an approved credential.
Added
- Observe surfaces search-preparation cost — The Observe Inbox and query diagnostic report now show how much preparation work ran before a search and whether database connections still need per-request setup. Values read “evidence pending” until the first sample arrives, and trace export includes the same preparation timing. See Signals.
- Clearer LDAP sign-in diagnostics — When an LDAP sign-in succeeds but the directory service account cannot read the account back — an access-rights or filter configuration issue rather than a wrong password — operators now get a distinct signal that separates the two, and sign-in failures appear on the request timeline. The response sent to the client is unchanged.
- Every search records which strategy ran, and how fast each strategy is — Each query’s trace now carries the search strategy it took, so one trace shows which kind of search ran. Per-strategy latency is now recorded for every routed search, including merge and range searches that previously went unmeasured, and the Observe evidence-health panel shows per-strategy p95 latency and a recent (5-minute) mix beside the cumulative totals — so a slowdown or shift in one kind of search shows up without waiting for process-lifetime aggregates. A query’s diagnostic report now names its search strategy too, and Observe workload cards group by strategy — so two slow searches of different kinds no longer collapse into one card.
- Failure detail in logs can be redacted for shared log backends — Failure messages, failure details, and exception stack traces written to the structured and application logs can now be redacted before they leave the process, so query filter text, distinguished names, and attribute values that appear in error detail need not reach a shared SIEM. Redaction is opt-in and off by default — local incident logs keep full detail — and is set per field under
monitoring.log.redaction(exception.message,exception.stacktrace,failure.details,exception.cause.*,warning.details), using the same hash and omit options as trace export. With no redaction rule configured, log output is unchanged.
Changed
- Sorted searches that narrow to a small set of entries return quickly over large directories — A sorted or virtual-list-view browse that narrows to a small set — by entry distinguished names (a single one or a long list), by a unique identifier (
uuidoruoid), or by a selective attribute value such as a rare surname — now returns in a fraction of a second across very large directories, where the same search could previously take many seconds. This applies when the search names the entry types it spans (or its base maps to specific types) and sorts on an attribute the directory keeps sorted, on the first page and when paging forward by cursor or page offset. Results and ordering are unchanged. - Broad sorted browses served locally return quickly over large directories — A sorted or virtual-list-view browse over a base that spans several entry types, with no narrowing filter, now returns in a fraction of a second across very large directories — on its first page, when paging forward by cursor, and at a deep page offset — where the same browse could previously take tens of seconds. This applies when IdentityScribe answers the browse from its own data rather than forwarding it (see the subtree-search entry above) and the spanned types keep the sort attribute indexed. Results and ordering are unchanged.
- Observe presents evidence consistently across its views — The Observe Inbox, Workloads, recurring-workload groups, query diagnostic report, and storage-coverage views now share one evidence model, so a given signal reads the same way in every view. Expandable rows respond to the keyboard like native controls, and the views render correctly on small and mobile screens. The signals shown are unchanged.
Fixed
- Operator views label searches by strategy — The Observe planner evidence-health panel now labels each search by an outcome-framed search strategy (Filtered search, Sorted listing, Combined-condition search, Membership search, Range search), matching the per-query diagnostic report. The information shown is otherwise unchanged.
- Failed sign-ins return at a constant time — A failed credential check now returns at the same fixed time whether the username does not exist, the password is wrong, or the password was correct but the account could not be read back. Response timing no longer reveals which of these happened, so it cannot be used to confirm a valid password or probe which accounts exist. This covers credential validation at the LDAP bind, the HTTP
401response, and the browser login form; the response a client sees is otherwise unchanged. The fixed time isauth.failure-delay(SCRIBE_AUTH_FAILURE_DELAY), default 2 seconds — set it comfortably above your slowest failed sign-in for the guarantee to hold (the 2s default covers a healthy directory). Setting it to0disables both the delay and the constant-time response. - Sorted prefix searches keep accented matches — Sorted and virtual-list-view searches that filter the sorted attribute with “starts with” now keep entries whose names contain accents or other non-ASCII characters. These searches no longer omit valid matches while paging, and result ordering is unchanged.
- Sorted and paged directory searches no longer fail with an error — An LDAP search that has to be forwarded to the upstream directory (for example a sorted or virtual-list-view browse from a directory client) could return an “invalid request” error instead of the intended “this search cannot be served here” response. These searches now return the correct response.
- Directory searches that select entries by distinguished name no longer need an entry type — A subtree search that filters on one or more entry DNs (for example an Identity Hub lookup that names users and roles by their distinguished names) across a base that spans more than one configured context previously returned an error asking for an entry type. IdentityScribe now recognizes the entry type from each distinguished name and returns the matching entries. Searches whose DNs fall outside the configured contexts keep their existing behavior.
- REST error responses no longer expose internal diagnostic details — Error responses from the REST API previously included a
detailsobject that could carry internal directory layout (the configured base DNs for each entry type) and internal attribute names. REST error responses now omit that object, returning only the safe code, message, and HTTP status — matching the GraphQL and MCP channels. The code, message, and status are unchanged.
v3.0.0-rc.9 (2026-06-22)
Fixed
- LDAP discovery stays license-compatible across harmless directory metadata differences — Startup license checks no longer fail only because the connected directory exposes an equivalent identity dataset with a discovery-only distinguished-name metadata difference. Directory-specific UUID value forms still affect the fingerprint when they change how entries are identified.
- LDAP paged-search counts no longer understate complete result sets — Simple paged LDAP responses now report an exact size only when IdentityScribe knows the complete result count. Clients that page through a result set, including Identity Hub, no longer see a final response that suggests fewer available entries than were actually returned.
- Documentation pages render wider content and tables correctly — The published documentation now gives desktop pages more reading space and renders tables reliably.
- Redacted Observe support exports work for signed-in operators — Operators can now prepare redacted Query Diagnostic and Workload support exports without extra Observe write access. Full exports remain limited to operators with write access, and the Operator UI no longer shows the Full option to operators who cannot use it.
- Entry count toggle explains exact-count fallbacks — When an exact entry count takes too long, the Operator UI now keeps the exact-count toggle selected, shows that the displayed number is still an estimate, and labels the timeout instead of appearing to ignore the toggle.
- Forwarded LDAP searches can use entry distinguished-name filters — LDAP searches forwarded to the connected directory can now use
entryDN(or Active Directory’sdistinguishedName) when filtering, sorting, requesting attributes, or evaluating assertions. Identity Hub lookups by entry DN no longer fail with “Request cannot be delegated to backend server” when IdentityScribe forwards the search. - LDAP bind failures stay attached to the bind log — Failed LDAP binds that already run inside an LDAP bind operation no longer also emit a separate “Untraced error” line. Operators still get the same bind events and client response; the failure is now recorded with the operation log.
v3.0.0-rc.10 (2026-06-25)
Added
- eDirectory Identity Manager role and group setups have a ready-to-import profile — Deployments that track role and group membership on user entries can now include
edirectory-idm.confafter their base config. The profile adds the IDM role, resource, and group attributes IdentityHub commonly queries, keeps high-fanout reverse membership views virtual, and documents the expected user, role, and group mappings in eDirectory Identity Manager Roles. - Query defaults can be set once and overridden per channel —
query.default-count,query.default-limit,query.default-include,query.default-fields, andquery.default-sortnow provide shared defaults for integrations that do not set their own values. Named channel overrides such aschannels.ldap.default-count,channels.rest.default-fields,channels.graphql.default-sort, andchannels.mcp.default-limitstill let each integration choose its own behavior. - Recent forwarded LDAP searches are visible in Observe, with a value-free request shape on every trace — When IdentityScribe forwards a directory search to the connected directory, its trace and wide log now describe the request without exposing directory data: the search scope, a structural filter pattern with the values stripped (for example
objectclass?,uid=), stable digests of the base DN and filter, the requested controls, and a correlation id — underldap.request.*andldap.delegation.sample_id. This makes it possible to identify which forwarded search returned a “service unavailable” (or any other result) and trace it back to the responsible client call. The Operator UI’s LDAP Forwarding view adds an expandable list of recent forwarded searches for each forwarding reason, and the same samples are available at/observe/ldap/delegationwith a downloadable export. The literal base DN and filter are held in a bounded in-memory window and shown only to operators with Observe write access; capture is on by default and can be turned off withmonitoring.observe.capture-request-values = false. The window keeps the most recentmonitoring.observe.max-samplessearches (default 200) formonitoring.observe.ttl(default 15 minutes) and is never written to the database. Traces, metrics, and the redacted export never carry the literal base DN or filter. - MCP endpoints record tool usage, expose per-tool metrics, and limit concurrent tool calls — The data (
/mcp) and Observe (/observe/mcp) MCP endpoints now record one audit log line per tool invocation (endpoint, tool name, result, duration, and request id — never the tool arguments), and export per-tool request-count and latency metrics underscribe.mcp.tool.*. Both endpoints bound how many tool calls may run at once: the cap auto-derives from the configuredconcurrencysetting (the same knob that sizes the database pool and HTTP limits) when unset, and can be set explicitly viachannels.mcp.max-concurrent-tools/monitoring.mcp.max-concurrent-tools(0disables the limit). When the limit is reached, an incoming call waits for a free slot before being rejected with a clear error; the wait defaults to 1 second and is tunable viachannels.mcp.tool-acquire-timeout/monitoring.mcp.tool-acquire-timeout. - Operators are alerted when the directory sends incomplete change notifications — The health checks (
/observe/doctor) and the Observe Inbox now raise a signal when the connected directory sends change notifications that omitobjectClass. A critical alert appears when such an update could not be completed and was held back — the stored entry keeps its previous values until the directory is fixed; a warning appears when IdentityScribe re-read the full entry from the directory to recover. Each card shows how many occurred in the last 5 minutes and points to the directory-side fix (check the directory’sobjectClassattribute mapping and re-sync the affected entries); the exact attributes the directory dropped are recorded in the ingest logs. The same signals are available for dashboards underscribe.ingest.incomplete_notification.total(reason=repaired/reason=skipped).
Fixed
- Stored entries keep their attributes when the directory sends an incomplete change notification — When IdentityScribe syncs a change from the connected directory, a change notification that arrives missing
objectClass(a mandatory attribute every live entry has) is no longer treated as if the attribute had been removed. Such an update could previously dropobjectClass— and potentially other attributes — from the stored entry, leaving an entry that clients relying onobjectClassmay reject or that attribute searches may miss. IdentityScribe now recognizes the notification as incomplete and re-reads the full entry from the directory; if a complete copy still cannot be obtained, it leaves the stored entry unchanged rather than corrupting it. Incomplete notifications are recorded under the newscribe.ingest.incomplete_notification.totalmetric (reason=repairedwhen the full entry was re-read,reason=skippedwhen the update was held back), so operators can spot a directory that is sending incomplete change notifications. - Pattern-based LDAP bind attributes accept quoted OID keys — Pattern entries under
auth.ldap.bind-attributekeyed by a quoted object identifier (for example"1.2.840.113556.1.4.221") are now read with the correct attribute name. The surrounding quotes were previously kept as part of the name, so any bind that relied on that attribute was rejected. Unquoted dotted keys and ordinary attribute names are unchanged. - LDAP paged-search counts keep useful estimates — Simple paged LDAP responses now keep a server-side estimate when it is available, and the reported size is never lower than the returned page proves. The final page still reports the completed result size when IdentityScribe can determine it.
- Bundled monitoring dashboards use the current planner metrics — The packaged Grafana and Helm dashboards now read the planner metrics introduced in the latest release, so planner-health panels continue to show data after upgrading.
- Forwarded LDAP searches recover from a dropped backend connection — When IdentityScribe forwards a directory search to the connected directory and the backend connection has gone stale — for example after the directory restarted, or an idle connection was dropped by the network — the search now reconnects and retries once instead of returning a “service unavailable” error. First-page and non-paged searches recover automatically; a search already paging through results with a server-side cursor surfaces the interruption so the client can restart the sequence.
- Operator UI API errors keep their request id — An error returned from an Operator UI action now retains the server-assigned request id, so a failure seen in the console can be correlated with its server-side trace and logs.
Changed
- LDAP paging counts now default to exact totals unless a client opts out — LDAP Simple Paged Results and virtual-list-view responses use exact totals by default, so clients that display role or group member counts do not see a low estimate as the total. Clients that only need navigation can still opt out of counts, and operators can choose estimated or no-count behavior through the new count defaults.
- MCP search and lookup default to data attributes — When an MCP client omits
fields, search and lookup now request data attributes (*) by default, matching REST and the shared query default. Clients that need operational attributes can still passfields="+"orfields="*,+", and operators can restore the previous default withchannels.mcp.default-fields = "*,+". - Forwarded directory searches record why a “service unavailable” was returned — Traces and wide logs for a forwarded directory search now carry two diagnostic attributes.
ldap.delegation.pageshows whether the search started a result set (first) or resumed a server-side cursor (continuation);ldap.delegation.retryshows whether an automatic reconnect was not needed (none), recovered the search (recovered), or was exhausted because the directory stayed unreachable (exhausted). Together they separate a transient stale-connection blip that self-healed from a directory that is genuinely down, and flag the one case that cannot be retried automatically — a search resuming a cursor — so it is clear the client must restart that paging sequence.
v3.0.0-rc.11 (2026-07-01)
Added
-
Early warning for memory leaks, with a downloadable diagnostic report — A new always-on sensor watches whether the memory that survives each garbage collection is trending upward without bound. When it is, IdentityScribe logs a warning, raises the
scribe.memory.leak.suspectedmetric (alongsidescribe.memory.live_set.bytesandscribe.memory.growth.per_hour) so unbounded growth shows up in Grafana, and raises a card in the Observe Inbox. From the card’s System → JVM view you can download a memory diagnostic report — a redacted version safe to attach to a support ticket and a full version for local investigation — capturing the JVM’s heap, memory pools, garbage-collector counters, and the sensor’s growth assessment, in the same way as the existing slow-query and workload exports. For deep analysis, an operator with Observe write access can trigger an on-demand heap dump (POST /observe/memory/heap-dump) for tools such as Eclipse MAT; only one runs at a time. Because a heap dump is a full copy of the heap — including credentials and personal data — capture is disabled by default, and enabling it requires settingmonitoring.memory.heap-dump.directoryto a private path (there is no default): the directory and every dump are created readable only by the account IdentityScribe runs as. The redacted report is safe to attach to a support ticket, and the report view’s email action opens a pre-addressed draft for you to attach the downloaded Markdown to. Tune the sensor undermonitoring.memory— thresholds, observation window, and poll interval; it runs by default, independently of whether telemetry export is configured. -
Searches that identify entries by object class resolve without forwarding — A directory search that selects entries by
objectClassorstructuralObjectClass— for example(structuralObjectClass=inetOrgPerson)against a base that several transcribes share — now resolves to the right entry type and is served by IdentityScribe instead of being forwarded to the connected directory.structuralObjectClassfilters are matched the same way asobjectClassfilters. When the directory publishes its schema, IdentityScribe recognizes the structural subclasses of each transcribe’s configured object class automatically, so a transcribe filtered by(objectClass=person)also answersinetOrgPersonandorganizationalPersonsearches with no extra setup; when the schema is unavailable it falls back to the configured classes and logs why. The newtranscribes.<type>.ldap.object-class-aliasesoption lists additional object class values that identify a transcribe for cases automatic detection cannot cover. All of this affects inbound query routing only — it never changes what is synced, stored, or forwarded upstream.
Fixed
-
Memory no longer grows without bound under sustained search load — Continuous LDAP, REST, or GraphQL search traffic caused heap use to climb for the life of the process until garbage collection thrashed and the LDAP channel stopped responding, typically after several hours of uptime. Memory now stays flat under the same load.
-
Substring-search row-count learning stays bounded when persistence is disabled — With
database.gate-learning.enabled = false, the record of which substring-search row counts are exact was never trimmed, so memory could climb slowly under varied substring searches. It is now bounded regardless of that setting. -
Full re-sync startup no longer fails on large stored datasets — When a subscription fingerprint change triggers a full re-sync, IdentityScribe now clears the old stored entries in a way that does not exhaust PostgreSQL lock memory. Large directories no longer fail startup with an
out of shared memorymessage during that reset. -
Searches return each matching entry only once — Free-text and fuzzy searches over several attributes no longer return duplicate rows when the same entry matches through more than one attribute or through several values of a multi-valued attribute. Sorting and cursor pagination keep their existing order.
-
Malformed LDAP paged-search cookies are recorded as client errors — An LDAP Simple Paged Results request with a corrupted continuation cookie already received the correct
protocolErrorresponse; its trace, wide log, and error-rate signals now also classify it as a client error rather than a server-side failure, so a client sending a bad cookie no longer counts against server-error monitoring. -
The eDirectory Identity Manager profile ships in the release archive —
edirectory-idm.conf, documented since v3.0.0-rc.10 as an additive profile to layer on top of your base config, was missing from the downloadable release archive. The archive now includes it under the name used in eDirectory Identity Manager Roles. -
Shutdown waits for sort-index backfill work to stop — When IdentityScribe is backfilling a sort index in the background (for example after adding a multi-valued attribute to
indices.sortable), shutdown now waits for in-progress backfill workers to exit instead of signaling them and returning immediately. A shutdown that must wait past a bounded timeout logs a warning naming the workers still running. -
Cancelled single-entry lookups no longer run their query — A request that resolves to a single entry uses a fast single-row lookup path; if the caller cancelled or timed out while that lookup’s parameters were still being bound, the query could still run against PostgreSQL. It is now skipped as soon as the cancellation is detected, so a request nobody is waiting on no longer does database work.
-
Reference deep links resolve Prometheus metric names, not just OpenTelemetry names —
/ref/*links and the embedded reference index now also recognize a metric’s Prometheus-exposition name (the underscored form scraped from/metrics, for examplescribe_ingest_lag_seconds), alongside its dotted name (scribe.ingest.lag.seconds). Both forms resolve to the same reference page. -
The Getting Started Dockerfile example fails clearly on a bad download — The custom-image
Dockerfileshown in Getting Started now installsca-certificatesand downloads the release archive withcurl -fSL --show-error, so an unauthorized or failed download (for example an expired token) stops the build with a visible error instead of continuing with an invalid archive. -
Observe’s index-build detail list stays within its configured limit during large bursts — When many background index builds complete or fail within the same short window, the detail list behind Observe’s index-build status view could briefly hold more entries than its configured cap. The list is now trimmed to the cap after every burst.
-
Long sortable attribute names no longer report a false index-build failure — A sortable attribute whose combined type-and-attribute name is long (for example the
srvprvlocalizednamesattribute on therequestdefentry type) could show a permanent failed index build in Observe → Storage and log anindex_create_failedwarning on every startup, even though the index and its background maintenance were working correctly. These healthy builds are no longer reported as failed.
v3.0.0 (2026-07-31)
Breaking
-
BREAKING: Negative pagination limits now fail consistently across REST, GraphQL, and MCP — GraphQL directory searches that previously used the configured default now fail, GraphQL change-history errors now use
ARGUMENT_INVALID_VALUEinstead ofINVALID_ARGUMENT, and MCP search and change requests now fail instead of requesting one result. Migration: send a positivelimit, or omit it to use the configured default. -
Monitoring log-rule operation shortcuts are no longer accepted through
monitoring.log.rules[].name— startup fails if the shortcut remains in a rule. Migration: move exact operation filters towhere = "scribe.operation=Exact.Operation"and pattern filters towhere = "scribe.operation~=Prefix.*"; keep any duration or result predicates in the samewhereexpression.monitoring.log.rules = [{ action = exclude, name = "Transcription.WorkItem", where = "duration.seconds<=500ms" }{ action = exclude, where = "scribe.operation=Transcription.WorkItem duration.seconds<=500ms" }] -
Hint persistence operation shortcuts are no longer accepted through
monitoring.hints.persistence.rules[].name— startup fails if the shortcut remains in a rule. Migration: move rule matching towherefilters such ashint-type=CONFIGorseverity=ERROR.monitoring.hints.persistence.rules = [{ action = exclude, name = "CONFIG" }{ action = exclude, where = "hint-type=CONFIG" }]
Added
-
Observe shows where query time goes, and how it trends — Queries gains an Insights tab that separates planning, query-capacity wait, database-connection time, and time to the first result, and charts short-term history for the signals behind a slowdown: query concurrency and rejections, which kind of search is getting slower, ingest lag, throughput and queue pressure, service restarts, and memory growth. The ingest and system views gain matching history panels, and the golden-signal strips become sparklines. A Query Diagnostic Report shows the same breakdown for one captured request, and redacted support exports keep these value-free timings, so performance problems can be investigated without exposing query values. History covers roughly the last two hours at three zoom levels — recent minutes in detail, older data coarser — and lives only in memory: after a restart the charts show an explicit gap and start fresh instead of reporting zeros, as do captures taken before this release. It is on by default and costs well under a megabyte; disable or bound it under
monitoring.stats-history. -
Performance insight report for support — When you report a performance problem, one download now carries the evidence: the performance insight report (Observe → Queries → Insights) packages recent metrics history, query stage timings, the slowest search patterns, ingest health, and database pressure indicators into a single redacted JSON file safe to attach to a support ticket. You need no Prometheus or Grafana of your own. Search identifiers stay stable and usable after redaction, each disclosure tier enforces its documented size limit, and large downloads use gzip when the client accepts it. A full variant for local investigation is available at
/observe/performance-insight/export/full. As with the other reports, the email action opens a pre-addressed draft for you to attach the download to; the report itself is never embedded in the email. -
Repeated searches can use a faster database planning choice — IdentityScribe measures alternatives against live traffic and applies a faster choice to search patterns whose evidence is current, keeping the standard choice active by default. Once the evidence is stable it promotes the choice without an operator enabling it per pattern, and it keeps rechecking, so a choice returns to the standard one when its evidence weakens or changes. Decisions are never stored or keyed by the values you searched for. Observe shows the effective choice, the evidence behind it, and whether a decision is still learning, settled, or being reconsidered; the global learning control remains available for emergency rollback.
-
Observe shows which index build failed and why — When a background index build fails, the Observe → Storage → Build Queue view now lists each failed build by name with the reason it failed, instead of only a failure count. When there are more failures than the list can show, or the details have not loaded yet, the view says so alongside the count. If the same build returns to pending after a completed or failed attempt, the new lifecycle stays visible. Operators can see what needs attention without reading the server logs.
-
Incomplete-notification Inbox cards name the attributes dropped on repair — When the directory sends change notifications without objectClass, the Inbox card for repaired notifications now lists the attribute names recently dropped (for example
objectClass,mail) instead of pointing operators only to ingest logs. It keeps a bounded set of the newest samples per entry type, so one noisy type cannot crowd out the others, and a recording failure never blocks the repaired entry. Samples contain attribute names only, never entry values. -
Browser responses carry baseline security protections — IdentityScribe’s HTTP channels and published documentation now send headers that prevent framing, MIME-type guessing, and referrer disclosure.
Changed
-
The embedded REST API reference is updated — The
/apiand/observereference pages now use the current stable release, including fixes for schema display and keeping request examples in sync. -
Telemetry labels now use bounded, documented values — MCP tool counters and timings use fixed endpoint, tool, and result values; ingest failures use the stable reasons
process,persist, andexecutor; and request-provided attribute names outside the configured catalog no longer create new metric label values. Operator dashboards can group these signals without labels growing from unexpected traffic values.
Fixed
-
Sorted searches with missing sort values are faster and remain complete during concurrent updates — IdentityScribe now chooses the fastest verified complete execution for common first-page searches automatically. Fast searches no longer spend milliseconds on planning work that can exceed the search itself, and entries without the requested sort value cannot be omitted because the data changed between planning and execution. Results, ordering, and cursors are unchanged; no configuration is required.
-
Operator UI presets survive immediate reload or tab close — Saving, updating, or removing a preset previously waited briefly before writing to browser storage, so reloading or closing the page right afterwards could silently discard a change that already appeared saved. Preset changes are now stored immediately.
-
Telemetry shutdown problems are now visible — A failed or timed-out flush of buffered telemetry during shutdown previously looked identical to a clean close. IdentityScribe now logs a warning naming the affected provider and step, so operators can detect telemetry loss at shutdown, and always continues closing the remaining providers.
-
Sizes below one byte no longer render an undefined unit — Fractional byte values in the operator UI displayed output such as
512 undefined; they now always render with a valid unit. -
Large sorted pages no longer fall back too early after finding matching entries — In very large directories, a cursor-paged sorted search with a long list of possible attribute values could switch to slower behavior even while it was still returning matches. A search that is producing results now keeps going for longer before falling back, so the same page returns much faster, with results and ordering unchanged. To restore the previous behavior, set
database.continuation.budget-extension-enabled=false;database.continuation.window.absolute-scan-capremains the hard ceiling. -
Synchronization stops safely after a transcription worker fails — A worker failure could leave accepted entries waiting forever during drain or allow queued work to begin after the failure. IdentityScribe now wakes drain and shutdown waiters, accounts for accepted work that cannot run, refuses later processor admissions, and keeps checkpoint advancement disabled so a restart cannot skip abandoned work.
-
Cursor-paged searches keep requested virtual attributes — A later page that selected a virtual attribute could omit it from the results. Such requests now preserve every requested virtual field on every page.
-
Range filters keep the exact bounds you send — Multiple range conditions on the same attribute could be narrowed through case-insensitive value comparisons before execution, changing the intended result for mixed-case or locale-sensitive values. IdentityScribe now preserves the original bounds and lets the configured directory comparison rules decide the match.
-
Range filters match entries whose bounds are met by different values — Lower and upper bounds on a multi-valued attribute are now evaluated independently, as required by LDAP filter semantics. Entries are no longer omitted when one value satisfies the lower bound and another value satisfies the upper bound.
-
Interrupted database write confirmation is no longer replayed blindly — If the database connection failed while confirming a completed entry update or delete, IdentityScribe could retry work whose outcome was unknown, risking duplicate history or a repeated delete. It now stops the affected worker and keeps its checkpoint pinned until the outcome can be resolved. Failed write preparation also releases partially opened resources.
-
Browser session cookies reject unexpected encryption choices — Session-cookie decryption now accepts only the key-wrapping and authenticated-encryption algorithms IdentityScribe itself uses. Existing valid sessions keep working; cookies that advertise a different algorithm fail authentication before their contents are processed.
-
Cancelled MCP change-history requests stay cancelled — A client cancellation during history streaming was wrapped as a generic server failure. MCP clients now receive the cancellation result, while real history failures keep their existing error handling.
-
Disabled database time limits remain disabled after temporary request settings — A connection that began with no query or lock time limit could retain a temporary limit after a request-specific override. The original disabled state is now restored, preventing unrelated later requests from failing early.
-
Machine-readable tokens stay stable under non-English host locales — Configuration values, HTTP preference handling, GraphQL change types, telemetry labels, export labels, and MCP reference lookups now use locale-independent casing. Hosts using Turkish or another locale with special casing rules produce the same protocol values and accept the same documented inputs as other hosts.
-
Observe’s API reference covers every shipped diagnostic endpoint — The generated Observe OpenAPI document now includes memory snapshots and exports, heap-dump capture outcomes, query diagnostic reports, the setup support report, and the history and performance insight downloads, with their real access levels, disclosure tiers, status codes, and response schemas.
-
Startup fails with a clear error instead of hanging when a service never finishes starting — Services that start in parallel during process startup now share the same five-minute ceiling that sequential startup already enforced. A service stuck in its startup phase previously left the whole process waiting forever without becoming ready or exiting; startup now stops the other services and fails with an error naming the stuck service, so process managers can restart or alert instead of waiting on a process that will never come up.
-
Shutdown during startup no longer briefly starts further services — When a shutdown request arrives in the short window while startup is still bringing service groups up, a group could slip past the cancellation broadcast, start its services after shutdown had already completed, and only then be torn down. Startup now re-checks for a pending shutdown at the moment each group is registered, so no service starts once shutdown has begun.
-
A failed checkpoint read no longer looks like a first-time sync — When reading the stored sync checkpoint failed after retries (for example the database was briefly unreachable during startup), IdentityScribe treated the result as “no checkpoint exists” and started a fresh full synchronization, discarding the saved position. A failed read now surfaces as an error and stops startup of the affected sync worker instead, so the durable checkpoint is preserved and the worker resumes from it once the database is reachable again.
-
The Getting Started curl download examples fail clearly on a bad download — The
curlinstall snippets in Getting Started now use the same fail-fast, redirect-following flags as the Dockerfile example (curl -fSL --show-error). An unauthorized or failed download — for example an expired token — stops with a visible error at download time instead of saving an error response that only fails later atunzip. -
Exported trace names can no longer carry directory or request data — Trace redaction covered the attributes attached to a trace but not the trace’s own name. A request whose URL matched no known endpoint previously used its raw request path — which can contain entry names — as the trace name; such requests are now named by their HTTP method alone. Any trace name outside the expected naming scheme leaves IdentityScribe as
span.redactedinstead of its literal text. Attributes remain governed by the existing redaction policy; no configuration change is needed. -
Two transcribe types can no longer silently share the same storage — Transcribe type names that differ only in non-alphanumeric characters (for example
user-domainanduser.domain) resolve to the same storage, which would mix both types’ entries. Startup now rejects such a configuration with an error naming both colliding types, so the conflict is caught before any data is written. Existing configurations with distinct type names are unaffected. -
Root DSE discovery requesting operational attributes is answered by IdentityScribe — An LDAP Root DSE search (empty base DN, base scope) that requests the all-operational-attributes projection
+— the form many LDAP clients and browsers use for capability discovery — was forwarded to the connected directory, so clients saw the upstream directory’s capabilities instead of IdentityScribe’s. It is now answered locally like every other Root DSE search. Tree-browsing requests on real entries keep their existing forwarding behavior. -
GraphiQL enforces the configured script integrity value — The
channels.graphql.ui.asset.js-srivalue was accepted but never reached the browser, so a tampered script from a custom CDN would still load. The GraphiQL page now carries that integrity value where the browser verifies it before executing the script. Browsers that do not support this check keep the previous behavior; the stylesheet integrity check is unchanged. -
Opening GraphiQL while signed out redirects to the login page — With login enabled and anonymous API access disabled, opening
/graphqlin a browser returned a raw JSON authentication error instead of redirecting to the login page. The browser now lands on the login page and returns to GraphiQL after signing in. Schema and API requests keep the JSON authentication error. -
/readyzreports not-ready when core services are unhealthy — The readiness probe only reflected synchronization readiness, so an instance whose core services (for example the database connection or a channel listener) turned unhealthy after startup kept answering/readyzwithokand stayed in load-balancer rotation./readyznow also requires the services to be healthy, matching its documented “can safely receive traffic” contract./livez,/startedz, and/healthzare unchanged, and sync or index backlogs still do not pull an instance out of rotation. -
Searches naming several entry types with an OR filter are answered — A search over a base that spans several entry types and a filter listing the wanted types as alternatives — for example
(|(type=person)(type=group)), alone or combined with further conditions — was rejected as if no type had been named at all. Such filters now narrow the search to exactly the listed types, the same waytype=personalready did. Filters that mix a type alternative with conditions on other attributes keep the previous behavior, because narrowing those could drop matching entries. -
Breadcrumb links work for entries with long names — In the Operator UI, the breadcrumb trail on an entry page cut the entry identifier at 100 characters when building its link, so clicking a breadcrumb for an entry with a long distinguished name led to a page that does not exist. The link now always carries the full identifier; only the displayed text stays shortened.
-
Observe history panels preserve the evidence that still works — A malformed metric series no longer drops healthy series from the same collection. Query, ingest, JVM, service, and database views distinguish loading, first-load errors, stale data, and unavailable in-memory history; a later refresh or tier-switch failure keeps the last good charts visible with a retry action and stale-data notice.
-
Observe Inbox counts, lists, and details stay in sync — The sidebar count, Inbox list, and recommendation detail now share one bounded-freshness snapshot. Concurrent refreshes share one generation, and applying, dismissing, snoozing, or reopening a recommendation invalidates that snapshot before the next read, preventing a badge count from describing different evidence than the page.
-
Observe history and report downloads use the documented access checks — The in-memory history API now applies the same Observe read access as the other Observe JSON APIs, and the redacted and full report variants each require their documented access level.
-
Performance insight reports include incomplete-notification totals — The support report now includes recent skipped and repaired incomplete-notification counts when history is available. The Inbox card for skipped notifications also stays focused on the held-back updates, rather than listing dropped attributes, which apply only to repaired ones.
-
Heap dump capture no longer reveals server filenames — When on-demand heap dumps are enabled, the capture response now returns an opaque capture ID and size rather than the server location. Repeated capture attempts are also rate-limited with a retry time, so operators get a clear response instead of starting expensive captures back to back.
-
Monitoring configuration mistakes fail validation clearly — Telemetry log filters now reject conflicting operation-name constraints at startup, and one-sided saturation-pressure overrides are checked against the effective default for the other side. Invalid configurations fail with the normal monitoring configuration error instead of surfacing a lower-level startup exception.
-
Exact telemetry log filters stay exact — Monitoring log filters that name one operation exactly no longer also match near-named operations. Wildcard and regular-expression operation filters keep their existing pattern behavior.
-
Observe keeps configured attribute names in index-build labels — Storage build status now preserves the original configured attribute descriptor when reporting planned index work, so mixed-case attributes remain recognizable in the Operator UI instead of being shown through a normalized fallback.
-
Support downloads use safe filenames — Browser-triggered report downloads now sanitize unusual suggested names before setting the saved filename, preventing directory separators or control characters from appearing in download names.
v3.1.0 (2026-08-31)
Added
- Query diagnostics expose each stage — The Query Diagnostic Report now breaks a captured operation’s time into Normalize, Plan, Prepare, and Execute stages and shows how much time preparation used. The share covers one executed search or count operation; Execute includes admission wait, database work, and result delivery.
Breaking
-
Memory pressure metric matches documentation — BREAKING: Prometheus now exports JVM memory pressure as
jvm_memory_pressureinstead ofjvm_memory_pressure_ratio— custom dashboards and alerts that queryjvm_memory_pressure_ratiostop receiving samples. Migration: replacejvm_memory_pressure_ratiowithjvm_memory_pressure; the bundled dashboards are already updated. -
Workload evidence separates retained examples — BREAKING: Observe workload responses and support exports now separate aggregate observations from bounded retained examples — clients that read
seenCount, card recurrence fields, orsamplescan no longer parse those removed fields, and workload support exports now use schema 2. Migration: readobservedCount,evidenceCoverage, andretainedExamples; useretainedBecauseto explain each example; update support-export consumers to schema 2. -
Affected entry histories repair automatically — BREAKING: On upgrade, histories affected by the former identity reset are repaired automatically when the stored evidence is unambiguous, restoring the original entry ID as the single identity, removing the false Created event, and reducing later changes to the attributes that actually changed — temporary entry IDs created during affected refreshes no longer resolve. Migration: re-resolve affected entries by UUID or distinguished name and refresh any cached entry IDs; ambiguous histories remain unchanged and available for support diagnostics.
Fixed
-
Entry history survives configuration changes — Existing entries retain their entry ID and complete history when synchronized attributes or other source settings are added, changed, or removed and a full refresh follows. Only real object changes create history events; newly configured attributes that are absent on an object and attributes removed from synchronization update the current view without inventing changes. An interrupted or incomplete refresh remains pending instead of deleting entries that were not safely checked.
-
Attribute Coverage lists every attribute — The Operator UI now lists every stored attribute, including attributes without index or sort coverage. Those rows use a neutral “Not applicable” state and do not report healthy coverage signals.
-
Slow shares use every operation — Observe calculates each slow share from the complete workload seen by the current process. Drill-downs keep a bounded typical comparison beside noteworthy examples, while the overview stays focused on actionable patterns. Slow or failed examples no longer act as the denominator for the aggregate.
v3.2.0 (2026-09-18)
Added
- Technical accounts can authenticate locally — Configure one or more local accounts with a DN, password, and optional short-name alias for LDAP, HTTP Basic, or browser login without a backend authentication round trip. Forwarded LDAP operations use the account’s explicit backend credentials or the root LDAP credentials as a complete pair, and disabled delegation fails before a backend connection is opened.
- Thread dumps from a running service — Sending the quit signal (
kill -3) now writes every thread’s state and code location to the service output and lets the process carry on serving. Operators can see what a stalled instance is waiting on without restarting it, and the dump holds no directory entries or credentials. Earlier versions shut down on that signal.
Changed
- Authentication settings keep their method scope — LDAP and ROPC cache lifetimes, disabled caching, and token-expiry revalidation now apply to the selected authentication method. Concurrent checks for the same backend credentials share bounded work; local passwords are never cached, and bearer validation remains unchanged.
Fixed
- LDAP sign-ins stop waiting indefinitely — Authentication and identity lookups now have a ten-second default timeout, with limited simultaneous upstream work. Configure
auth.ldap.request-timeoutfrom 1 millisecond to 1 minute. Brief bursts can wait up to two seconds at each capacity limit within the authentication deadline. The default pending limit is 256 callers, including those joining a check for the same credential. Sizeauth.ldap.max-pendingfor the client connections that may bind within one upstream authentication round-trip, such as a client pool reconnecting after a restart; adjust waiting withauth.ldap.capacity-wait. Capacity rejections return LDAP busy (51), and authentication timeouts return unavailable (52); HTTP Basic sign-ins return 503 for either. These temporary failures skip the credential-failure delay. Invalid credentials retain LDAP 49, HTTP 401, and their configured minimum response duration.
v3.2.1 (2026-09-21)
Security
- Compression libraries receive security updates. Updated both compression libraries to address known vulnerabilities. No configuration changes are required.
Fixed
- Searches no longer stall until restart — On a busy service, directory searches on every channel could stop returning results until the service was restarted, while synchronization and health checks still reported a healthy instance. This permanent stall can no longer occur. All 3.x releases up to and including 3.2.0 are affected, so rolling back to an earlier 3.x release does not avoid the problem.
- Searches recover after clients give up or time out — Searches on every channel could stop after clients repeatedly gave up on slow requests or searches ran into their time limit while waiting, leaving a restart as the only recovery. Abandoned requests no longer cause this permanent stall. This affects releases from 3.0.0-rc.3 through 3.2.0, including stable releases 3.0.0, 3.1.0, and 3.2.0.
- Browser login works for local and LDAP accounts together — With
auth.methods = [local, ldap], the login form now accepts both configured local accounts and LDAP users. In 3.2.0, adding a local technical account made browser login local-only and LDAP users were rejected with “Invalid credentials”. No configuration change is needed; if you setauth.session.method = ldapas a workaround, you can keep it to keep technical accounts out of the browser, or remove it to allow both. Whereverlocalis accepted, a local account signs in only with its configured password, and a wrong password for a local DN or alias is never tried against LDAP. Surrounding whitespace in a login name, including non-breaking and invisible spaces from copy and paste, is now ignored for local accounts on all channels (browser login, HTTP Basic, and LDAP bind), and a local account alias configured with surrounding whitespace matches its trimmed form.[local]and[ldap]on their own, OIDC, ROPC, HTTP Basic, and LDAP bind behave as before. - MCP tools name wrongly typed arguments — A Data MCP tool call whose arguments use the wrong JSON types, such as a string
limitor an arrayentryType, now returns an invalid-argument error that names the argument. Earlier releases reported this as a temporary failure. - Observe MCP rejects unknown scopes — An
observecall whosescopeis not one of the documented values now returns an invalid-argument error. The submitted value is truncated and is not copied into the public error text, so a very longscopecannot inflate the response. Earlier releases silently returned the summary. - MCP
reflookups now resolve — Askingreffor an error code, metric, configuration key, or attribute now returns the matching documentation URL. Earlier releases returned no match. When nothing matches, the suggested queries are names that do resolve.
v3.3.0 (2026-10-03)
Security
- Oversized HTTP requests are refused early — BREAKING: HTTP requests with a body larger than 1 MiB are now refused with
413or a closed connection, and sign-in form posts larger than 16 KiB get413— clients that send larger GraphQL or MCP requests now fail. Migration: raisehttp.request-limits.max-payload-size(SCRIBE_HTTP_MAX_PAYLOAD_SIZE) for the socket that needs it, or set it to-1to remove the limit. Earlier releases accepted HTTP request bodies of any size before sign-in, so a single client could make the server reserve large amounts of memory. See HTTP request limits. - Configuration view hides secrets reliably — BREAKING: the configuration view (
/observe/config) and hint details requested withredact=falsenow require Observe write access (by default theadminrole), so signed-in accounts without it now get403; the configuration view and--printconfignow print formatted JSON instead of HOCON. Migration: give operators who need these views the role named inmonitoring.observe.write.auth.rules, or adjust those rules; update scripts that parse--printconfigor/observe/configoutput as HOCON. Previously both showed comments from the configuration files, numeric and true/false values under secret settings, and custom header values such as exporter API keys, so such a secret could be read by any Observe user. They now show no comments and redact every value under a secret setting and every header value, and the view is no longer cached by browsers. The Observe MCP endpoint now followsmonitoring.observe.auth.rules; when it runs on its own socket,monitoring.mcp.auth.rulesreplace them if set. All 3.x releases up to and including 3.2.1 are affected. See Endpoints. - LDAP token errors protect private details. Bearer sign-in and proxy authorization now keep token, account lookup, and unexpected validation details out of LDAP responses. If the identity provider cannot supply signing keys, requests receive a temporary unavailable response. Operators can find the cause in service logs.
- Local account passwords stay local. Alternate directory name spellings now resolve to the configured local account, so an incorrect password cannot be sent to the directory.
- Sign-in redirects stay within allowed pages. Encoded parent-directory segments can no longer move a sign-in redirect outside its allowed page area.
- Signing out over HTTPS ends the session. Signing out over HTTPS left the session cookie in the browser, so the session stayed valid there until it expired. Sign-out now removes it. All 3.x releases up to and including 3.2.1 are affected. No configuration change is needed.
- Other websites cannot change your session — BREAKING: sign-in and sign-out POST requests without origin information are rejected, and plain-HTTP deployments and older browsers such as Safari before 16.4 need the reverse proxy to report the public address — scripts that post the sign-in form without an
Originheader, and those deployments and browsers behind a reverse proxy that does not, now get “Invalid request” instead of a session. Migration: switch scripts that post the sign-in form to HTTP Basic; for plain HTTP or older browsers behind a reverse proxy, enablehttp.requested-uri-discovery, list the connection peer as trusted, and have it sendForwardedwithprotoandhost, orX-Forwarded-For,X-Forwarded-Proto, andX-Forwarded-Host. Another website could submit the sign-in form with an account of its choosing and sign a visitor’s browser into that account without the visitor noticing. The sign-in page now accepts a form only from its own pages; a form posted from elsewhere shows “Invalid request” and creates no session. Over HTTPS, sign-in behind a reverse proxy keeps working in current browsers without configuration changes. Sign-out now rejects cross-site requests and requests without origin information, leaving the current session in place; the in-app sign-out still works, and says so when a sign-out is rejected instead of returning to the sign-in page. Scripts that post the sign-out form without anOriginheader now get “Invalid request”. HTTP Basic, OIDC sign-in, and LDAP bind are not affected. All 3.x releases up to and including 3.2.1 are affected. See Sign-in form protection. - Proxy authorization now takes effect — BREAKING: an LDAP request with a Proxy Authorization control is now checked, and when IdentityScribe forwards it to the directory it runs as the requested identity instead of the signed-in account — a client that names a DN or username without permission, or presents a bearer token that maps to no directory account, now gets
AUTHORIZATION_DENIED(123); a non-critical, repeated, or malformed control getsPROTOCOL_ERROR(2), and a bind with an otherwise valid control getsUNAVAILABLE_CRITICAL_EXTENSION(12); a local account without the permission gets 123 for the control on every operation except a bind, which gets 2 or 12 like any bind; and an abandon request carrying the control is ignored. Migration: list each account that may act for other users inchannels.ldap.proxy-authorization.allowed(for the Identity Hub listener,channels.identity-hub.proxy-authorization.allowed) and make sure IdentityScribe’s directory account may act for those users in the directory; setproxy-authorization.enabled = trueon a local account that should do the same; remove the control from clients that do not need it and from bind requests. Earlier releases ignored the control, so such requests ran with the signed-in account’s directory rights rather than the requested user’s. IdentityScribe now decides before it looks up the requested identity or contacts the directory: abearer:token proves its subject and needs no permission where the listener accepts bearer sign-in, while a DN or username needs the new permission, which no account has by default and which a SASL sign-in gets only when the directory reports the signed-in account. Searches, writes, and other operations forwarded to the directory then run as the requested identity, and Who-Am-I reports it; searches answered from IdentityScribe’s own data and channel access rules still use the signed-in account. A paged or virtual list view search continues only as the identity that started it. Local accounts keep rejecting the control unless they opt in. All 3.x releases up to and including 3.2.1 are affected. See Proxy Authorization. - SASL binds are off by default — BREAKING: the LDAP listeners now refuse every SASL bind with
AUTH_METHOD_NOT_SUPPORTED(7) unless its mechanism is listed, and with channel authentication on a listed mechanism counts as a directory sign-in: it needsldapin the listener’sauth.methods, the account the directory reports through Who-Am-I (RFC 4532) must lie underauth.ldap.baseand matchauth.ldap.filterand must not be a local account’s DN, its roles come fromauth.ldap.roles, SASL binds that cannot reach the directory count toward detecting an outage, and while directory sign-ins fail fast during an outage a new SASL bind fails fast too, unless it is the sign-in let through to check the directory, which IdentityScribe checks before forwarding the bind — a SASL bind whose account the directory does not report, or reports outside that base or filter or as a local account’s DN, fails withINVALID_CREDENTIALS(49). Migration: SASL binds through IdentityScribe are off by default; list the mechanisms you use inchannels.ldap.sasl.mechanisms(for the Identity Hub listener,channels.identity-hub.sasl.mechanisms), make sure the directory answers Who-Am-I for them, and move clients that useEXTERNAL, which can no longer be enabled, to another mechanism or a simple bind. Earlier releases forwarded every SASL bind and took the account from the name in the bind request, which SASL does not check, so a client could sign in with its own credentials and be treated as another account; anEXTERNALbind authenticated IdentityScribe’s own directory certificate. A paged or virtual list view search started while a multi-step SASL bind was in progress no longer continues after the bind completes. All 3.x releases up to and including 3.2.1 are affected. See SASL binds. - LDAP sign-ins need a directory account — BREAKING: an LDAP bind that names no directory account now fails with
INVALID_CREDENTIALS(49): adn:bind whose value is not a DN, and a bearer oru:bind whose token or username maps to no DN — such clients can no longer sign in. Migration: bind with the account’s full DN (dn:uid=alice,ou=people,dc=example,dc=com) or its username (u:aliceor the plain name), and configureauth.ldapso bearer and username binds find the account’s DN. Earlier releases signed such a client in without an account, and requests IdentityScribe forwarded to the directory for it ran with IdentityScribe’s own directory rights. All 3.x releases up to and including 3.2.1 are affected. See Authentication. - Refused LDAP binds leave nothing signed in — With
channels.ldap.auth.enabled = false, a bind the directory accepted but whose account IdentityScribe could not determine, such as an Active Directory user principal name, was refused, yet the client’s later requests on that connection still ran with that account’s directory rights. They now run as an anonymous client, as after any refused bind. All 3.x releases up to and including 3.2.1 are affected. - Oversized LDAP requests are refused — BREAKING: the LDAP listeners now disconnect a client that sends a request larger than 10 MiB — a client that writes larger entries or modifications through IdentityScribe now loses its connection. Migration: if your clients send larger requests and the directory accepts them, raise
channels.ldap.max-message-size-bytes(for the Identity Hub listener,channels.identity-hub.max-message-size-bytes), or set it to0to remove the limit. Earlier releases accepted requests of any size, from clients that had not signed in too. Passwords and SASL credentials larger than 64 KiB, bind DNs and usernames larger than 8 KiB, and bind request controls larger than 8 KiB in total now getINVALID_CREDENTIALS(49) before IdentityScribe contacts the directory, which would drop such a request; Kerberos tokens andbearer:tokens up to 64 KiB still fit. All 3.x releases up to and including 3.2.1 are affected. See LDAP Channel. - JSON parsing receives security fixes. Updated the bundled JSON library with fixes for denial-of-service and deserialization issues. No configuration change is needed.
- Web server receives security hardening. Updated the web server with security fixes for request handling. No configuration change is needed.
Added
- Sign-ins fail fast during directory outages — When the directory stops answering or repeatedly returns busy or unavailable, LDAP sign-ins that need it no longer wait for the ten-second timeout. After five failed sign-in checks in a row, IdentityScribe checks the directory itself; when that check fails too, sign-ins fail immediately with LDAP result 52, HTTP 503, or “Sign-in temporarily unavailable” on the login page, and every ten seconds the next sign-in first checks whether the directory answers again. Sign-ins that fail because of what a client sent, such as wrong passwords or credentials larger than the directory accepts, never make other sign-ins fail fast. Normal sign-ins resume without a restart. Sign-ins rejected this way are counted instead of logged one by one, so clients that retry during an outage do not flood the log. Local accounts, browser sessions, cached sign-ins, and searches are not affected. Adjust or turn this off with
auth.ldap.breaker.threshold,auth.ldap.breaker.open-duration, andauth.ldap.breaker.enabled; see Authentication. - Doctor reports directory sign-in outages — The new
auth.ldap.upstreamdoctor check and thescribe_ldap_upstream_stategauge show whether the directory answers sign-ins: degraded when sign-in checks fail more often than usual, critical while sign-ins fail fast. Readiness is intentionally unchanged, because the directory serves every instance and taking them all out of rotation would not help. See Monitoring. - Release archives include third-party attribution. The release archive now contains
THIRD_PARTY_LICENSES.mdwith the notices and license texts for its open-source components. - Readiness reports stalled searches —
/readyzand/healthznow return503while searches are stalled: every query permit is in use, a search has waited for a permit or was turned away since the last release, and no permit has been released for 60 seconds. A turned-away search still counts after it gave up. A stalled instance usually needs a restart, so an orchestrator can now take it out of rotation; if a search finishes after all, the stall ends and the probes return200without one. A busy instance whose searches keep finishing stays ready, and/livezis unchanged. The newquery.permit_stalldoctor check andscribe_query_permit_stall_secondsgauge report the stall, and the log records aquery_permit_stallwarning when it starts andquery_permit_stall_clearedwhen it ends. If you restart, collect a thread dump withkill -3first. Tune the wait withmonitoring.readiness.query-stall-after(SCRIBE_MONITORING_READINESS_QUERY_STALL_AFTER), or keep readiness independent of searches withmonitoring.readiness.fail-on-query-stall = false(SCRIBE_MONITORING_READINESS_FAIL_ON_QUERY_STALL=false).
Changed
- LDAP StartTLS setting now rejected — BREAKING: IdentityScribe refuses to start when
start-tlsorssl.insecureis set totruefor an LDAP connection — configurations with either setting in any LDAP block now fail at startup. Migration: switch toldaps://(usually port 636) and setldap.ssl.caif your directory uses a private CA. The production guide previously suggestedldap.start-tls = true, but this setting was never applied, so the directory connection stayed unencrypted. See Production guide. - Faster planning choices adopted more often. Repeated searches switch to a consistently faster planning choice more often when response times vary. A choice that is slower for typical searches is no longer adopted only because its slowest searches finish sooner.
- Environment variables override the configuration file — BREAKING: environment variables listed in the configuration reference now take precedence over values in the configuration file — a stale variable left in a service unit or container environment now wins over the file, for example pointing the service at an old database or directory, and a variable the service previously ignored or read leniently now stops startup when invalid, such as an OTLP exporter timeout, an on/off value like
1orTRUE, or an invalid duration or number; an invalid OTLP protocol stops startup when that exporter is enabled. Migration: before upgrading, list the environment variables the service receives from service units, container definitions, and shell profiles; remove any that should not apply; usetrue,false,yes,no,on, orofffor on/off settings and valid durations, numbers, and OTLP settings; after upgrading, check theconfig_env_overridestartup warning, which names the settings an environment variable changed without showing values. Empty variables count as unset, and list settings keep their comma- or space-separated form, such asSCRIBE_AUTH_METHODS=bearer,ldap. Object settings such asSCRIBE_LDAP_VIRTUAL_ATTRIBUTESnow accept a value like{}even without a file value.SCRIBE_LICENSE_FILEand thePOSTGRES_HOST,POSTGRES_PORT,POSTGRES_USER, andPOSTGRES_PASSWORDfallbacks are unchanged: a value in the configuration file still wins. The--licensecommand-line option and alicense.fileJava system property now take precedence overlicense.filein the configuration file; previously the file value won, so remove a stale--licensefrom service units before upgrading. See configuration precedence and upgrading to v3.3.0.
Fixed
- Startup failures consistently signal failure — IdentityScribe now always ends with exit code
1when it gives up starting, including when a required setting such asauth.session.cookie-keysis missing and every retry fails; this case used to end with0. Docker restart policies, systemd and Kubernetes now see such a start as failed and can restart or alert. An HTTP port that is already in use now also fails startup: IdentityScribe retries according toretry.servicesand ends with exit code1if those attempts are exhausted, instead of running without health checks, metrics, APIs or the admin UI. A requested stop is not affected. - Slower planning choices reverted sooner. Recent measurements help repeated searches return sooner to the standard planning choice when an adopted choice becomes slower.
- Rare search and shutdown hangs fixed — IdentityScribe is now built on Java 25.0.4 (GraalVM Community Edition 25i2). Earlier releases were built on Java 25.0.2, where a task waiting with a timeout could, rarely, miss the signal to continue and wait forever, so a search, sign-in, or shutdown could hang until restart. The release binary contains its Java runtime, so installing this release is all you need to do. If you build IdentityScribe from source, use GraalVM Community Edition 25i2 (Java 25.0.4) or later.
- Faster totals for broad either-or searches — The exact total of a search for one of several values or prefixes on different attributes, such as
(|(givenName=Mara)(cn=Mara)), could take about twice as long as needed when it matched many entries and IdentityScribe had not yet learned how many entries each part matches, and the estimated total stayed at 200 whatever the real count. These totals are now computed the standard way in that case. All 3.x releases up to and including 3.2.1 are affected. No configuration change is needed. - Sorted contains searches tune themselves. Contains searches sorted by the searched attribute now record their timings like other searches, so adaptive planning can pick a faster choice for them and Query Diagnostic Reports show them.
- Backward paging returns the previous page. Fixed a case where paging backward with a
beforecursor through a search sorted by a single-valued attribute returned entries far from the cursor instead of the previous page, and placed entries without the sort attribute on the wrong side of it. No configuration change is needed. - Sorted paging retains missing values. Fixed a case where cursor paging omitted entries without the sort attribute after a page ended on an entry with a value, when moving forward in ascending order or backward in descending order. No configuration change is needed.
- Grafana monitoring bundle starts reliably — The Docker full stack in the monitoring bundle now starts its PostgreSQL 18 database and serves the monitoring endpoints on port 9001 that the health check and Grafana dashboards use. The bundle reads the LDAP source, the entries to sync, your license file and a session key for the Operator UI from a
.envfile, and can publish its database on another port when one on your host already uses 5432; see Grafana monitoring bundle for the prerequisites. Building the full-stack image yourself currently needs an x86_64 host. A database volume that holds data from another PostgreSQL major version needspg_upgradeor a dump and restore. - Late deletes preserve replacement entries. A delayed deletion for a removed entry no longer removes a new entry created under the same name.
- Forwarded requests explain directory outages. If a forwarded LDAP request cannot open a directory connection, it now returns
UNAVAILABLE(52) with a plain message. New forwarded binds and writes previously returned 80; a first forwarded search could return a different connection code. Unexpected search failures also keep private details out of the response. - Dropped directory connections answer consistently. If the directory connection behind a forwarded LDAP request drops during a session and cannot be reopened, searches, binds, writes and other forwarded operations now return
UNAVAILABLE(52) with “The directory is temporarily unavailable.”, the same answer as when no connection can be opened. They previously returnedSERVER_DOWN(81) or another client-side code such as 85 or 91, with connection error text that could name the directory host. - Error reference shows actual messages. The error reference now lists the messages clients can receive for token, export, lookup, and GraphQL failures, plus a search that fails a consistency check, in place of generic text.
- Large legacy upgrades finish rebuilding — A startup rebuild when upgrading from 1.x could fail repeatedly on a large directory with the default database settings. These rebuilds now complete without increasing the database lock-memory allowance. Upgrades from 3.2 do not run this rebuild.
- Shared instances recheck sorted searches — Instances sharing a database now stop using affected sort indexes during startup rebuilding and verify them again afterwards. New installations and upgraded instances resume normal sorted-search performance after verification without false backfill alerts. The convergence view shows when the readiness check is paused instead of reporting progress that it cannot verify. Upgrades from 1.x still require a maintenance window. See Upgrading.
- Sorted searches with totals succeed and run faster — A sorted search that asked for the total number of matches could fail instead of returning results: LDAP paged searches returned result 19 (constraint violation) with “Can’t do that right now”, REST returned HTTP 409, and GraphQL and MCP returned an error. This affected first pages that request only the total or name a virtual attribute among the requested attributes, for two kinds of filter on the sort attribute: a lower bound such as
(sn>=M)sorted bysn, and a prefix such as(cn=Mei*)sorted bycnthat matches more than 10,000 entries of one type, from the second such search on. These searches now return their entries with the exact total, and their exact and estimated totals are computed the same way as for the search without sorting, so they take about as long and estimates are as close. All 3.x releases up to and including 3.2.1 are affected. Totals for other sorted searches are faster as well: in our benchmarks on a directory with 250,000 entries, they were typically about three times faster than in 3.2.1, and up to about 20 times faster for broad filters on an attribute other than the sort attribute, such as a “starts with” search on a common first-name prefix sorted by surname. Totals for sorted searches that match only a few entries were already fast and stay that way. No configuration change is needed. - Debug logging reaches every log category —
--debug,--trace, and a debug or tracelog.levelorSCRIBE_LOG_LEVELnow also apply to theSuperVisor,Ingest,Monitoring,License, andConfiglog categories, which stayed atinfobefore. A quieter global level, such as--quietorlog.level = warn, still keeps their operation logs atinfo. A level set for one category, such asSCRIBE_LOG_MONITORING=warn, still wins in both directions. See Logging. - Library log levels can be changed —
SCRIBE_LOG_KENOXA,SCRIBE_LOG_HIKARI,SCRIBE_LOG_FLYWAY,SCRIBE_LOG_JOSE4J, andSCRIBE_LOG_HELIDONhad no effect, and neither did a quoted key such aslog."com.zaxxer.hikari"in the configuration file, so these libraries always logged atwarn. The variables now apply. In the configuration file, write the setting without quotes, as inlog.com.zaxxer.hikari = debug; settings already written that way keep working. If one of these variables is set in your environment, the library now logs at that level. See Logging. - LDAP synchronization settings take effect —
ldap.checkpoint-offset,ldap.idle-period,ldap.ignore-checkpoint-timestamp, andldap.single-value-attributes, set in the configuration file or throughSCRIBE_LDAP_CHECKPOINT_OFFSET,SCRIBE_LDAP_IDLE_PERIOD,SCRIBE_LDAP_IGNORE_CHECKPOINT_TIMESTAMP, andSCRIBE_LDAP_SINGLE_VALUE_ATTRIBUTES, were ignored, so synchronization always used the built-in values and the directory schema alone. They now apply. If you setldap.ignore-checkpoint-timestamp = true, every start now runs a full synchronization; remove it unless that is intended. If you setldap.single-value-attributes, check that the listed attributes hold one value in the directory. See LDAP. - Maintenance and reconciliation thresholds take effect —
database.maintenance.soft-thresholds,database.maintenance.hard-thresholds,ldap.reconciliation.soft-thresholds, andldap.reconciliation.hard-thresholds, set in the configuration file or through their environment variables, were ignored, so maintenance and reconciliation always used the built-in thresholds. They now apply, and a configured set of thresholds replaces the built-in one. If you set them, check that the values still describe how idle the system must be before maintenance or reconciliation runs. See Database and LDAP. - Duplicate local account aliases rejected — Two local accounts whose
usernamealiases differed only by surrounding spaces or invisible characters, or an alias that was another account’s DN with such padding, passed configuration validation, and the alias then signed in as nobody. Such a configuration is now refused at startup with a clear message, as is an alias that consists only of padding. Configurations with distinct aliases are not affected. - Trusted proxy address ranges now work — BREAKING:
http.requested-uri-discovery.trusted-proxies.exactnow matches CIDR ranges and IPv6 address spellings by address, and rejects non-IP entries at startup — a host name that was previously ignored can now prevent startup. Migration: replace non-IP entries with IP addresses or CIDR ranges; move any intended pattern over the peer IP address tohttp.requested-uri-discovery.trusted-proxies.pattern. - Reverse proxies report the public address — BREAKING: with trusted
X-Forwarded-*headers, IdentityScribe now uses the public address for sign-in origin checks, CORS, OIDC redirect URIs, and OAuth metadata — OIDC sign-in fails at the identity provider when the redirect URI registered there uses the internal orhttp://address. Migration: register the public HTTPS redirect URI at the identity provider. See Sign-in form protection. - CORS accepts standard web origins. With
http.cors.allow-origins = [same-origin], requests to HTTPS port 443 or HTTP port 80 now match the browser’s origin. Thehostvalue ofhttp.cors.allow-originsreturns the same address without an unnecessary default port. - OIDC sign-in works over HTTPS — OIDC sign-in failed with “CSRF validation failed” whenever IdentityScribe received the sign-in over HTTPS, because browsers discarded its temporary verification cookie. The cookie is now accepted and removed after sign-in, and the new session cookie is kept. All 3.x releases up to and including 3.2.1 are affected. No configuration change is needed.
- MCP lookups reject bad input clearly. Reference searches now ignore surrounding spaces and keep long misses concise. Unknown help topics return a validation error that lists the accepted topics. The hint shown with invalid-argument errors now points to a help topic and a reference search that work.
- Sign-in and sign-out reach any page. Redirects after sign-in and sign-out now work when the destination page or its query contains non-ASCII characters, such as umlauts.
- Directory outages show temporary sign-in failure — When the directory cannot be reached or returns busy or unavailable, the sign-in page and every authentication channel now report a temporary failure instead of wrong credentials. LDAP bind returns 52 and HTTP requests return 503. Local account sign-ins remain available during a directory outage.
- Early stream closes respect concurrency limits — When a client closed a search result stream before reading it to the end, the service could let more searches reach the database at once than the configured maximum, adding load to an already busy instance. Early stream closes now stay within the limit on every channel. All 3.x releases up to and including 3.2.1 are affected, and no configuration change is needed.
- Numeric local account DNs recognised — A configured local account is now recognised when its login DN is presented with numeric attribute types, such as
2.5.4.3=proxy,o=globalforcn=proxy,o=global, on all channels (browser login, HTTP Basic, and LDAP bind). Earlier releases treated that spelling as an unknown name and forwarded it with the submitted password to the directory, so a directory entry at the same DN could sign in even though the DN belongs to a local account. Local accounts were introduced in 3.2.0, so 3.2.0 and 3.2.1 are affected. As with the named form, a local account signs in only with its configured password, and a wrong password is never tried against LDAP. No configuration change is needed. - Database environment variables no longer block startup — Setting nested and some other
database.*options by environment variable, such asSCRIBE_DATABASE_FILTER_SELECTIVITY_PLAN_MODE_ENABLED=false,SCRIBE_DATABASE_ORPHANED_TRANSCRIBES_BEHAVIOR=ignore, orSCRIBE_DATABASE_QUERY_HTTP_ACQUISITION_TIMEOUT=10s, now takes effect. Previously the service refused to start with anUnsupported property nameerror. No configuration change is needed. - Busy searches no longer disrupt synchronization — Under heavy search load while the database was slow to write, saving query diagnostic report details could occupy every connection that synchronization needs. Searches then waited up to 30 seconds, synchronization logged “Failed to persist entry/event” and re-read entries from its last checkpoint, and the log filled with “Failed to persist query diagnostic snapshot” warnings. Report details are now saved in the background, one query at a time, and only while a connection beyond those synchronization needs is free; otherwise they are skipped instead of waiting, and a save that takes longer than two seconds is abandoned. Synchronization needs one connection per transcribe, at least two. If
database.system-pool-sizeis set to exactly that, report details are not saved and a warning at startup says so; raise it by one to save them. While the database is busy, only the latest details of each query are kept, and if more queries wait to be saved thanmonitoring.hints.cache.sizeallows, the others are skipped. Skipped details are not retried automatically; they may still be saved when the current query completes or when the query runs again, if there is room. The log records one warning when skipping starts, and one with the skipped count and the time of the last skip on the first save at least a minute after that skip, or at shutdown if skipping had not ended by then. A database that stays near its limit logs at most one such pair per minute. All 3.x releases up to and including 3.2.1 are affected. No other configuration change is needed. - Sorted searches recover after first start — After the first start on a new database, sorted searches could keep using a slower plan until the next restart, and
/observe/convergencereported sort indexes as ready while none were being tracked. Sort indexes are now rebuilt during that start and become ready on their own, and the convergence report counts them as backfilling until they are. All 3.x releases up to and including 3.2.1 are affected. No configuration change is needed. See Deployment verification. - Adaptive planning stays active continuously. Searches no longer fall back to the standard planning choice at regular intervals while the database responds normally, including during quiet periods. Turning adaptive planning off takes effect promptly even after a clock correction, and still lets searches already running finish.
- License checks ignore system language — BREAKING: the directory product is now identified the same way under every system language — an installation that runs under a Turkish or Azerbaijani system language with an UnboundID or Ping Identity directory fails to start with
Invalid scopesuntil its license is reissued. Migration: on such an installation, send the license request the upgraded service shows, as described in Renewing a License. Under those system languages, such a directory was identified under a different product name, so a license requested under one system language failed withInvalid scopeswhen the service started under another. On such an installation, the first start after the upgrade also runs one full synchronization of every entry type. Other installations keep their license and synchronization state. - A stop during startup ends cleanly — A stop that arrived just as the service, the synchronization of a transcribe, or an LDAP listener was starting, or restarting after an error, could leave it marked as failed, and the shutdown then logged an error although nothing had started. Such a stop now ends cleanly. No configuration change is needed.
- Forwarded virtual list view searches work — Every virtual list view (VLV) search that IdentityScribe forwards to the directory, such as a search below
ldap.ignore-contexts, failed with “Paging or VLV continuation is invalid after authentication changed; restart the search.” and was logged as an unimplemented search, even when the client had not signed in again. Identity Hub with VLV paging hit this on every forwarded search. These searches are forwarded again, and like other first-page searches they now reconnect once when their directory connection has gone stale. Continuing a paged or VLV result after signing in as another account is still rejected. A VLV request with a malformed control, and any request with a control whose type is not a plain numeric object identifier such as2.16.840.1.113730.3.4.9, is now answered with a protocol error, and a search rejected this way tells the client why. 3.2.0 and 3.2.1 are affected. No configuration change is needed. - Multi-value lookups report correct totals — A search for any of several values of an attribute listed under
value-match, such as(|(workforceID=A)(workforceID=B)), returned the matching entries but reported a total of 0 in LDAP paged results and virtual list view responses. Exact and estimated totals for such searches on the REST, GraphQL, and MCP channels were wrong as well. Identity Hub 9.13 and earlier rely on that total in their default paged search and therefore returned no results; later Identity Hub releases returned the entries but could report a total of 0. Such searches now report the number of matching entries. All 3.x releases up to and including 3.2.1 are affected. No configuration change is needed.
v3.3.1 (2026-10-07)
Changed
- Documentation explains with figures. Concept, guide, channel, reference and operations pages now show how Scribe works in figures that state their point in the caption, and mark the setting or flag that matters in configuration and command examples. Start with Architecture and Change Detection.
Fixed
- Upgrade to 3.3 works without superuser — Starting 3.3.0 failed with
permission denied to set parameter "identity_scribe.rebuilding_entries"when the database account is not a PostgreSQL superuser, which is the usual case on managed PostgreSQL services. The database upgrade now needs only the rights of the database owner. Installations that already upgraded to 3.3.0 start normally; no action is needed. - Query statistics work without superuser — The Observe Queries tab failed to load when the database account is not a PostgreSQL superuser, which is the usual case on managed PostgreSQL services. It now loads and says which step is missing when query statistics are not enabled. On a server shared with other applications it lists the queries of Scribe’s own database account, which others’ queries no longer crowd out. With
database.auto-create-query-stats-extensionon, Scribe now installs thepg_stat_statementsextension when its account is allowed to; on most managed services a database administrator still has to install it. - Documentation matches the product. Corrected statements that did not match Scribe’s behaviour, among them: gRPC is listed as planned, not available; the license expiry warnings start 15 days ahead and an expired license stops a running instance at its next check; error responses never carry
details; configuration priority, log rules for client errors, task pressure and connection pool sizes are now described as they work.
v3.3.2 (2026-10-13)
Delegated writes recover after directory disconnects, and operation logs now record write durations and outcomes. The bundled compression library also receives a security fix. No configuration or database changes are required.
Security
- Compression library security update. Updated the compression library bundled with 3.3.1 to address
CVE-2026-106451. Existing data remains readable; no configuration changes are required.
Added
- LDAP writes show their timing. Add, Modify, Delete and rename requests that IdentityScribe forwards to the directory now appear in the operation log as
LDAP.Add,LDAP.ModifyandLDAP.Deletewith their duration and result, and inscribe_channel_request_duration_secondswithop="add",op="modify"orop="delete"; a rename counts as a modify. Each write shows how long the directory took to answer as anLDAP.Delegationevent, so a slow write tells whether the time went to IdentityScribe or to the directory, and whether the write first had to connect to the directory. As with searches, slow and failed writes now appear in the operation log by default, except fast ones refused because the entry is missing or the request is invalid; to log every write, see Time LDAP writes. Requests and their results are unchanged.
Fixed
- Delegated writes recover after disconnects. Creates and modifications in 3.3.0 and 3.3.1 could keep failing with
UNAVAILABLEafter a directory connection dropped; Scribe now restores the connection for subsequent requests without repeating an uncertain write, and no configuration change is needed. - Invalid continuations give clear guidance. Rejected paging or VLV continuations in 3.3.0 and 3.3.1 now say
Paging or VLV continuation is not valid on this connection; restart the search.instead of claiming that the authorization identity changed. - Malformed paging returns protocol errors. Malformed paged-results request controls in 3.3.0 and 3.3.1 now receive
PROTOCOL_ERROR(2) andThe paged results request control is malformed.instead of a misleading continuation rejection.
v3.3.3 (2026-10-18)
Bearer tokens and token claims no longer reach logs or traces, access rules match their values literally, and a stopped LDAP listener now restarts on its own; upgrades with renamed entries finish, very large groups load again while oversized entries are refused when written, and two quick changes to an entry keep the newer value. Four changes need action, listed under Breaking: heap dumps need a directory only the service account can read, Observe actions sent from other websites are refused, HTTPS sessions need the protected session cookie, and identity providers must report their configured issuer; bearer sign-in also uses the auth.http trust store now. Logs written by earlier releases may contain tokens and personal data, so delete or restrict them.
Breaking
- Heap dumps need a private directory. BREAKING:
POST /observe/memory/heap-dumpnow refuses with503unlessmonitoring.memory.heap-dump.directoryis owned by the service account and grants no access to anyone else, because a dump holds credentials and personal data; point the setting at such a directory or let Scribe create it. Filesystems without POSIX permissions or ACLs are refused as well. - Other websites cannot trigger Observe actions. BREAKING: Inbox actions, the plan-mode kill switch and heap dumps now answer
403and change nothing when a browser session sends them from another website, including another host of the same domain, or without origin information, so a page elsewhere can no longer act with a signed-in operator’s rights; Inbox actions and the kill switch also answer415unless the body is sent withContent-Type: application/json. The Observe pages keep working. All 3.x releases up to and including 3.3.2 are affected; see Sign-in form protection. Migration: switch scripts that call these actions with a session cookie to a bearer token or HTTP Basic credentials, which are not affected, and send JSON bodies withContent-Type: application/json. - HTTPS sessions need the protected session cookie. BREAKING: Over HTTPS, Scribe now reads only the session cookie it sets over HTTPS, which no other host and no plain-HTTP page can set; a session cookie left over from a plain-HTTP sign-in, or one hidden inside another cookie’s value, is ignored. Behind a reverse proxy that terminates TLS, a request counts as HTTPS when the proxy is listed in
http.requested-uri-discoveryand reportshttps; Scribe then sets the protected cookie withSecure, and access rules onrequest.securematch. Migration: sign in again after moving a deployment from HTTP to HTTPS; behind a TLS-terminating proxy, enablehttp.requested-uri-discoverywith the proxy as a trusted proxy so sessions get the protected cookie. - Identity providers must report their configured issuer — BREAKING: Scribe now rejects a provider whose discovery document names an issuer other than its
issuerorpublic-issuer— bearer tokens, password sign-in and token introspection through that provider fail. Migration: setpublic-issuerto the issuer your identity provider reports. See Authentication.
Security
- Access rules match values literally. Underscores, percent signs and backslashes in a starts-with, ends-with, contains or wildcard value acted as wildcards, so a rule could match request paths, hosts or accounts it did not name; they now match only themselves, and only
*in a wildcard value matches any text, as documented. All 3.x releases up to and including 3.3.2 are affected; see Access rules. - Bearer tokens kept out of logs. A rejected LDAP bearer bind could write the client’s complete bearer token into the operation log, where anyone with log access could reuse it; the log now records only the reason. Delete or restrict logs from earlier releases, and treat tokens that were still valid at the time as exposed.
- Token claims kept out of logs. A token rejected by a claim check, such as issuer, expiry or audience, wrote its decoded claims, including subject and e-mail address, into the operation log, and introspection failures logged audience values; the log now names the failed checks and claims, the token’s issuer and the expected value, and no claim values. With
SCRIBE_LOG_JOSE4J = debug, token headers no longer reach the library log. Delete or restrict logs from earlier releases according to your personal-data retention rules. - Rejected opaque tokens kept out of traces. With a UserInfo endpoint configured, an opaque token containing characters not allowed in an HTTP header was written in full into the trace and the operation log; both now record only the reason.
- Bearer sign-in honours identity provider settings. Bearer tokens are now checked with signing keys and provider details fetched through the
auth.httptrust store and timeouts, so identity providers with a private certificate authority work without changing the system trust store. While the identity provider is unreachable, Scribe retries it at most every few seconds, backing off to once a minute, instead of on every request, and keeps using the last signing keys it fetched. A provider’sCache-Control: max-agenow counts as at least one minute and at most one day, and provider answers larger than 512 KiB are refused. A failed token request now logs only the provider’s status, the kind of answer (such as JSON or HTML) and its size, no longer the start of its answer or its full content type, which could echo a password or authorization code.
Changed
- Token rejections report their actual reason. Rejection codes no longer depend on words inside the token: expired tokens report
AUTH_TOKEN_EXPIRED, tokens for another audienceAUTH_TOKEN_INVALID_AUDIENCE, and a token with an unknown signing algorithmAUTH_TOKEN_INVALID_SIGNATUREwith LDAP result 49 and HTTP 401 instead ofAUTH_JWKS_ERRORwith 52 and 503. All other rejections keep their LDAP result and HTTP status.
Fixed
- Upgrades with renamed entries finish. An upgrade that rebuilds stored entries failed on every start when an entry had been renamed, including entries deleted later; renamed entries now come back with their new name and last change time.
- Groups with very many members are stored and read again. An entry with more than 65,536 values in one attribute, such as a large group’s members, was stored but then failed to load, so later changes to it, directory reads of it and restores failed; such entries, including those stored by earlier releases, now load normally. An entry beyond the supported size (more than 4,096 attributes, more than about four million values, an attribute name over 1,024 bytes, a value over 16 MiB or 64 MiB of values in total) is now refused when it is written, with an error naming the exceeded limit, and the previously stored version and its history stay unchanged.
/observe/health/readyfails while searches are stalled. Like/readyz, it and the combined/observe/healthnow return503with aquery-stallcheck while every query permit stays in use, unlessmonitoring.readiness.fail-on-query-stallisfalse; see Kubernetes probes.- Stopped LDAP listeners restart. When an error such as running out of threads stopped an LDAP or IdentityHub listener, it stayed down until Scribe was restarted while the channel reported healthy; it now restarts as set by
retry.services, and the channel reports unhealthy until it accepts connections again. On Linux withuse-reuse-address = false, the restart retries while an old connection still holds the port and logsldap_listener_rebind_failedfor each attempt. - Shutdown no longer waits for stalled clients. Stopping Scribe or a listener no longer waits for a client that has stopped reading its responses.
- Reconciliation counts only recorded entries. When the database could not record that a page of entries was verified, reconciliation still counted the page and searched the same entries again; it now retries briefly and otherwise stops the run without counting that page.
- A slow directory no longer ties up database connections. When a change notification arrived without the entry’s object classes, Scribe re-read the entry from the directory while holding a database connection and the entry’s row lock; it now holds them only for the write.
- Two quick changes keep the newer value. When the directory changed the same entry twice in quick succession, Scribe could store the older values last and add a change back to them to the entry’s history, although the directory still held the newer values; the newer values now stay stored and the history shows no such change. Entries already affected are corrected by their next change or a resync.
- Later queries keep their settings. A session setting that failed to apply or restore could change plan choice or timeouts for unrelated later queries on the same pooled connection.
- Transient errors retry under every system locale. Database, LDAP and HTTP operations now also retry temporary I/O failures under Turkish or Azerbaijani system locales.
- A missing license file is named. When
license.filepoints at a file that does not exist or cannot be read, verification now fails withLicense file not found or not readable: <path>and where the setting came from. - The production template starts.
config/production.conffailed startup validation; it now serves the Operator UI and REST admin on the internal socket together with Observe, and all templates note that production needsSCRIBE_AUTH_SESSION_KEYS. See Network isolation. - Missing session keys stop startup at once. With
auth.enabled = falseand browser sessions on, the default when any UI is enabled, a production start withoutauth.session.cookie-keysnow fails validation withAUTH_SESSION_KEYS_REQUIREDinstead of retrying untilretry.services.max-attemptsruns out. - The Helm stack serves monitoring on port 9001. The chart exposed port
9001, but Scribe never opened it; the chart now configures health and/observeon9001, matching the Docker bundle, and its probes check that port. - The Helm stack’s Grafana reaches Prometheus and Tempo. The stack now serves Prometheus on
9090and points the Tempo datasource at its HTTP port, so dashboards and trace lookups work after install. - Health endpoints answer
HEAD./livez,/readyz,/startedzand/healthzansweredHEADwith404, so probes such aswget --spidersaw a running instance as failed; they now return the same status asGET, without a body. - Delegated searches keep the client’s attribute spelling. Since 3.0, searches forwarded to the directory, such as those under
ldap.ignore-contexts, sent unmapped attribute names in lowercase, so a client asking forworkforceIDcould receiveworkforceidand find no values; Scribe now forwards them as the client spells them. - Sorted searches by position return each entry once. A sorted search that starts at a numbered position, such as an LDAP virtual list view request by offset, could repeat and skip entries when some had no value for the sort attribute; each position now matches the complete sorted result. All 3.x releases up to and including 3.3.2 are affected.
- Paged sorted searches return long values once. With the default
database.query.sort.long-value-tiebreaker = deterministic, paging through values that share their first 256 characters could repeat some entries and skip others; each page now continues exactly where the previous one ended. - Case-only changes replace the old spelling. When the directory changed only the letter case of one value of a multi-valued attribute, Scribe kept both spellings in searchable data and recorded only an addition; it now keeps the new spelling and records the old one as removed. Values recorded before this release are not corrected.
- Per-transcribe task limit takes effect. The documented
max-task-concurrencysetting of a transcribe was ignored in favour of the database pool size; it now applies, capped atconcurrency. See Transcribes. - Browser sign-in works behind a proxied identity provider. When
public-issuerdiffered fromissuer, as is usual behind a reverse proxy, every browser sign-in was rejected; it now succeeds, and sign-ins from other identity providers are still refused. - Failed MCP tool calls count as failures. A tool call that returned an error, such as an invalid argument, was recorded as
okin the per-tool metrics and the audit log; it is now recorded asunknown, so error rates show. - Scheduled maintenance stops at shutdown. Scheduled and interval maintenance runs now stop at their next safe point when Scribe shuts down, as manual runs already did, instead of delaying shutdown until the sweep ends.
- Entry views show the current state. In the Operator UI, returning to an entry or to a relative time such as “1 hour ago” showed the state from your first visit, and a deleted entry reappeared; the view now checks for the latest state and says when that check failed, with a “Try again” button.
- Entry history shows the time you chose. In the Operator UI, choosing a time before the entry existed or older than the loaded history jumped to a later change; the view now shows the entry at that time, or says it did not exist then.
- Entry comparisons show loading and errors. In the Operator UI, comparing two states of an entry showed every value as added or removed while one side was loading or had failed; it now shows that it is loading, or an error with a “Try again” button.
- The Browse Hub says when its data is missing. When monitoring data failed to load or refresh, Browse Hub cards showed zeros, “None”, “All clear” or old values as if current, also after a reload; they now show “Loading” or “Unavailable”, with a “Try again” button when nothing loaded or a refresh failed.
- Observe views work with hints off. With
monitoring.hints.enabled = false, the Doctor, Services, Build Queue, Ingest, JVM, LDAP Forwarding and Pipeline views showed only an error; they now show their data and mark values that did not refresh as unavailable. - The Changes feed shows the right hourly rate. In the Operator UI, the Changes summary rate read 3,600 times too low; 3,600 changes in one hour now show as
3.6k/h.
v3.3.4 (2026-10-22)
This release fixes one startup failure in 3.3.3 and updates build and documentation tooling for known advisories. If you skipped a startup step to work around it, read the action under Fixed before you start 3.3.4.
Fixed
-
Startup no longer stops while cleaning up entry histories. When startup had to clean up entry histories that earlier resyncs had duplicated, Scribe could stop with
Unable to discover event-stream normalization candidates, caused byCannot change transaction read-only property in the middle of a transaction. We reproduced this failure: a new database connection reached Scribe with a transaction still open. New connections now start without one, which fixes the reproduced failure. Installations whose next start runs this cleanup, mostly the first start after an upgrade, may be affected. Action: if you skipped the cleanup by settingeventStreamNormalizationVersionin thesubscriptionstable, remove that marker right before the first start of 3.3.4, so the cleanup runs on that start:BEGIN;UPDATE subscriptionsSET state = state - 'eventStreamNormalizationVersion'WHERE id LIKE 'identity-scribe:state:%';SELECT id, state ? 'eventStreamNormalizationVersion' AS marker_presentFROM subscriptions WHERE id LIKE 'identity-scribe:state:%';COMMIT;Every row should show
marker_present = false. After that start, the log reports the cleanup for each entry type and the marker is set again. Without the marker workaround, no action is needed.
v3.3.5 (2026-10-26) Latest
Access and log rule conditions now match as written: conditions with dotted values, such as e-mail addresses or IP prefixes, and conditions in outer parentheses joined with and or or could match other requests than written, so deny rules could miss and allow rules could admit identities they were meant to exclude. Two changes may need action, both under Breaking: a parenthesised rule condition that reads both as one comparison and as several now stops startup with an error naming the rule, and REST, GraphQL and MCP search filters such as (cn=x or sn=y) are now read as two comparisons. Bearer sign-in keeps working while the identity provider’s key endpoint is unavailable, forwarded LDAP sign-ins keep their own directory account after a lost directory connection, and wrong-issuer errors stay readable. Set database passwords through database.password or POSTGRES_PASSWORD rather than inside a connection address, where they can reach debug logs; build and documentation tooling is also updated for known advisories.
Breaking
- Rule conditions in outer parentheses match as written. BREAKING: An access or log rule condition wrapped in outer parentheses and joined with
andoror, such as a deny rule(subject.principal.id=alice@example.com or subject.principal.id=bob@example.com), was read as a single comparison with the rest of the condition as its value. With=such a condition never matched, so deny rules did not apply and allow rules admitted no one; with>=,<=or~=it could match far more than written, so an allow rule such as(subject.principal.id>=alice and subject.principal.id<b)admitted identities likecarol.white@example.comthat it was meant to exclude. These conditions now work as written. Search filters sent over REST, GraphQL or MCP follow the same rule, so(cn=x or sn=y)now searches for either comparison; to search for a value that containsorfollowed by=, write the=as\3d. Filters sent by LDAP clients are unchanged. A rule condition that reads both as one comparison and as several comparisons joined byand,or,&&,||or a space, such as(subject.principal.id=alice or subject.principal.id eq bob)or(subject.principal.id>=a&&subject.principal.id<b), now stops startup with an error naming the rule. Migration: remove the outer parentheses, or, for a value that really contains such text, escape the characters that separate it, such as each space as\20. Values that cannot be read as several comparisons, such as(subject.principal.id=uid=alice,ou=Research and Development,dc=example,dc=com), keep matching as written.
Security
- Rule conditions preserve dotted values. Since 3.0.0, access and log rules with dotted or underscored values, such as e-mail addresses, IP prefixes and operation names, could compare against a rewritten value when using a word operator (
eq,startswith,contains, etc.) or spaces around the operator. Such conditions could match too few or too many requests: deny rules did not apply, allow rules did not match (including the shipped examplerequest.client.ip startswith 10.0.), and allow rules with a negated operator such asneornotinadmitted the identities they were meant to exclude. Values are now kept as written. Workaround before upgrading: use a symbol operator without spaces, such assubject.principal.id=alice.smith@example.comorrequest.client.ip^=10.0.; replacein/oneoflists with one rule per value; fornotin, join symbol inequalities withandin the same rule, such assubject.principal.id!=alice.smith@example.com and subject.principal.id!=bob.jones@example.com. Write these FleX conditions without outer parentheses; before this release a parenthesisedorcan silently never match. For a value that contains spaces, use the LDAP form and write each space as\20, such aswhere = "(subject.principal.id=alice\\20smith.jones)". - Wrong issuer errors stay readable. When a discovery document names a different issuer than configured, Scribe keeps the actual and expected values in the error while escaping control characters and shortening an unusually long actual value.
- Keep database passwords out of connection addresses. Database passwords given inside
database.url,database.hostorPOSTGRES_HOSTcan appear in debug logs of the connection pool; set them throughdatabase.passwordorPOSTGRES_PASSWORDinstead. 3.4 removes them from logs.
Fixed
- Forwarded LDAP sign-ins keep their own directory account. When a client signed in through a SASL bind, or through any bind with
channels.ldap.auth.enabled = false, and Scribe then lost its directory connection for that client, Scribe opened a new connection with its own backend account and ran the client’s later requests there. Later requests that need that directory connection now getUNAVAILABLEuntil the client binds again, and a write is still never sent twice. Sessions signed in by Scribe itself reconnect as before. See Proxy Authorization. - Bearer sign-in survives key-endpoint outages. Bearer tokens signed with the last good keys keep validating when the identity provider’s key endpoint is unavailable or its answer cannot be read, instead of failing after about 20 minutes with the default refresh interval. Entries Scribe cannot read are ignored when the answer also contains a usable signing key. Failed key fetches keep their retry delay. Valid answers retire withdrawn keys within four refresh intervals after the last answer containing them, plus any pending retry delay (up to 60 seconds), including removal of all signing keys and longer cache lifetimes.