AppSettings

Application parameters, environment configurations and runtime overrides.

This page documents the keys used by the framework in appsettings.json and appsettings.{Environment}.json.

General conventions

• Values under AppSettings are read as strings and then converted (bool/int) by the backend.
• For boolean flags use true|false.
• For numeric keys use positive integers (seconds/minutes/timeout).
• Keys are case-sensitive on the JSON side.

Logging

Top-level section Logging:LogLevel (standard .NET). Allowed values for each key: Trace | Debug | Information | Warning | Error | Critical | None. Hot-reload.

• Logging:LogLevel:Default

Meaning: default log level for all non-overridden categories.

Typical default: Warning.

• Logging:LogLevel:System

Meaning: level for the System category (.NET runtime).

• Logging:LogLevel:Microsoft

Meaning: level for the Microsoft category (ASP.NET Core, EF, hosting).

AppSettings - Core bootstrap

• firstRun

Meaning: enables the first-time configuration/provisioning flow.

Values: true | false.

Typical default: false.

• preScaffold

Meaning: enables pre-scaffolding of metadata/app objects.

Values: true | false.

Typical default: false.

• projectDataFolder

Meaning: application project root (e.g. CrmApp) used for files, assemblies and runtime resources.

Values: absolute filesystem path.

• projectAssemblyName

Meaning: application assembly loaded dynamically.

Values: absolute .dll path.

• defaultSiteRoute

Meaning: initial client route after bootstrap/login.

Values: hash-route (e.g. #/).

• license-email

Meaning: installation email/license.

Values: valid email.

AppSettings - Database and provider

• dbms

Meaning: main DB provider for data routes.

Enum-like values: mssql | mysql | postgresql | oracle | xml.

Typical default: mssql.

• meta-dbms

Meaning: metadata DB provider (system routes).

Enum-like values: mssql | mysql | postgresql | oracle | xml.

Typical default: same as dbms.

• allowMultipleDBMS

Meaning: enables coexistence of multiple providers at runtime.

Values: true | false.

Typical default: false.

• connection

Meaning: base connection string used by services/scaffolding.

Values: provider-specific connection string.

• DataDBName

Meaning: default data database name.

Values: DB name.

• connectionByUser

Meaning: uses a connection/context bound to the current user at specific runtime points.

Values: true | false.

Typical default: false.

AppSettings - CRUD, query, filters

• autoGeneratedQueryTimeout

Meaning: timeout (seconds) for auto-generated SQL queries.

Values: positive integer.

Typical default: 120.

• storedProcTimeout

Meaning: timeout (seconds) for stored procedure execution.

Values: positive integer.

• enableServerSideCrudChangeLog

Meaning: enables server-side logging of CRUD operations.

Values: true | false.

Typical default: true.

• optimisticCheckEnabled

Meaning: enables optimistic concurrency control on updates: the save is rejected if the record was modified by another user after it was read (comparison of the version field/data_modifica). Avoids silent overwrites in multi-user scenarios.

Values: true | false. Hot-reload.

• logicDeleteField

Meaning: global field for logical deletion (if not defined in the table metadata).

Values: column name.

• logicDeleteValue

Meaning: value that represents a "logically deleted record".

Values: string/number compatible with the field type.

Typical default: 1.

• cacheDataMinutes

Meaning: data cache duration in minutes (when route caching is active).

Values: positive integer.

• cacheDataIncludedRoutes

Meaning: whitelist of cacheable routes.

Values: comma-separated list of routes.

• cacheDataExcludedRoutes

Meaning: blacklist of routes to exclude from the cache.

Values: comma-separated list of routes.

• traceQuery

Meaning: enables SQL query tracing with execution times.

Values: true | false.

Typical default: false.

• sqlVerbose

Meaning: enables verbose SQL output in endpoints/tools that support it.

Values: true | false.

• logInvoke

Meaning: enables logging of dynamic function/callback invocations.

Values: true | false.

AppSettings - Security, login, session

• customAuthentication

Meaning: delegates authentication to custom application logic.

Values: true | false.

• enableCookieAuthentication

Meaning: controls who writes the k-user session cookie and with which policy. The backend exposes the same wire format in both modes (k-user=<urlencoded-json>); only the sender and the cookie attributes change.

Values: true | false. Default: false.

Concise comparison of the two modes:

### Single-session behavior (mode true)

Each login generates a new token that overwrites the previous one. Practical consequences:

- If the same user logs in from two different browsers (or two incognito windows), the last login wins: the first browser is disconnected with the message "Session terminated: the same user has logged in from another browser." — whether navigating a page or refreshing.

- The browser with the last login is not affected.

- Two tabs in the same browser do not have this problem: they share the same cookie, so the token is updated on both.

### Known pitfalls

- If you edit appsettings.json by hand while the backend is running, a restart is required (the web AppSettings editor performs the flush automatically).

- After flipping from false to true, pre-existing cookies do not have the token → users must log in again.

- The E2E tests (backend-api-client.mjs) detect the mode automatically and work in both cases.

• enableODATAAuthentication

Meaning: enables auth for OData endpoints.

Values: true | false.

• enableHttpsRedirection

Meaning: forces the HTTP→HTTPS redirect + HSTS. Default false (no redirect, no HSTS): the app responds over both HTTP and HTTPS. Set true ONLY on hosts with a valid HTTPS certificate (in Startup.cs it activates UseHttpsRedirection/UseHsts).

Values: true | false. Default: false. Restart.

Meaning: enables guest access.

Values: true | false.

• applyGrantByDefaultToGuest

Meaning: applies default grants to the guest user as well.

Values: true | false.

• grantDashSaveToGuest

Meaning: allows the guest to save dashboards.

Values: true | false.

• default-role-id

Meaning: role assigned as fallback/default.

Values: integer (role ID).

• sessionTimeoutMinutes

Meaning: user session timeout in minutes.

Values: positive integer.

Typical default: 60.

• notifySessionExpirationBefore

Meaning: lead time (minutes) for the session expiration notice.

Values: positive integer.

Typical default: 1 or 2 depending on the environment.

• enableUserLanguageSwitch

Meaning: enables the user language switch in the UI.

Values: true | false.

AppSettings - Password and credential policy

• IsPwdEncripted

Meaning: indicates whether the passwords in the store are hashed.

Values: true | false.

• encriptionMethod

Meaning: legacy hash algorithm used for password verification.

Enum-like values: SHA1 | MD5.

Typical default: SHA1.

• password_min_length and password_min_length

Meaning: minimum password length (note: in some files a variant with a trailing space in the key name exists).

Values: positive integer.

Typical default: 8.

AppSettings - Captcha, double token, application URLs

• captcha_public_key

Meaning: captcha public key.

Values: string.

• captcha_private_key

Meaning: captcha private key.

Values: string.

• enableDoubleTokenAuthentication

Meaning: enables an additional token verification step in the intended login/activation flow.

Values: true | false.

• site-url

Meaning: site base URL for absolute email/workflow links.

Values: absolute URL.

• content-url

Meaning: base URL for content/confirmation links (mailing, read-confirm, etc.).

Values: absolute URL.

AppSettings - Email and mail notifications

• email-host

Meaning: SMTP host.

Values: hostname/IP.

• email-port

Meaning: SMTP port.

Values: integer (25, 465, 587, ...).

• email-ssl

Meaning: enables SMTP TLS/SSL.

Values: true | false.

• email-user

Meaning: SMTP username.

Values: string.

• email-pwd

Meaning: SMTP password.

Values: string/secret.

• email-sender-address-mailing

Meaning: sender for mailing/notification emails.

Values: valid email.

• email-sender-name-mailing

Meaning: mailing sender display name.

Values: string.

• email-sender-address-registration

Meaning: sender for registration/activation emails.

Values: valid email.

• email-admin-registration

Meaning: administrative recipient for registration events.

Values: valid email.

• email_confirm_token_subject

Meaning: subject template for the token confirmation email.

Values: string.

• email_confirm_token_body

Meaning: body template for the token confirmation email.

Values: string (HTML allowed).

AppSettings - Upload and media

• uploadFolder

Meaning: root folder for file/image uploads.

Values: absolute path or virtual path resolved by the server.

• base64Image

Meaning: forces handling of images in base64 format where applicable.

Values: true | false.

AppSettings - Report and report viewer runtime

• ReportMode

Meaning: report rendering mode in the viewer.

Observed enum-like values: web (default fallback) and custom modes handled controller-side.

Note: if absent, the backend uses the web fallback.

• reportQueryTimeout

Meaning: timeout for report dataset queries (seconds).

Values: positive integer.

AppSettings - Record translations (legacy keys in AppSettings)

• recordTranslationsEnabled

Meaning: enables per-field record translation.

Values: true | false.

• recordTranslationsDefaultTableName

Meaning: default record translations table.

Values: table name.

• recordTranslationsTranslationJsonFieldName

Meaning: name of the translations JSON field.

Values: column name.

• recordTranslationsDefaultLanguage

Meaning: fallback language for record translations.

Values: culture code (e.g. it-IT, en-US).

• recordTranslationsFieldNames

Meaning: list of translatable fields.

Values: comma-separated list.

Related top-level sections (outside AppSettings)

• RecordTranslations:Enabled

Meaning: main runtime switch for record translations.

Values: true | false.

• RecordTranslations:DefaultTableName

Meaning: physical translations table.

Values: table name.

• RecordTranslations:TranslationJsonFieldName

Meaning: translations JSON field.

Values: column name.

• RecordTranslations:DefaultLanguage

Meaning: fallback language.

Values: culture code.

• RecordTranslations:FieldNames

Meaning: translatable fields.

Values: array of strings.

• Scheduler:Enabled

Meaning: enables the scheduling hosted service.

Values: true | false.

• Scheduler:PollSeconds

Meaning: scheduler polling in seconds.

Values: positive integer.

• Scheduler:MaxTasksPerCycle

Meaning: maximum tasks processed per cycle.

Values: positive integer.

• Scheduler:RetryDelaySeconds

Meaning: retry delay for failed tasks.

Values: positive integer.

• Scheduler:SqlCommandTimeoutSeconds

Meaning: scheduler SQL timeout.

Values: positive integer.

• Notifications:Enabled

Meaning: enables the realtime notifications subsystem.

Values: true | false.

• Notifications:Mode

Meaning: backend notifications watcher mode.

Enum-like values: SqlDependency | Polling.

• Notifications:PollSeconds

Meaning: notifications polling if Mode = Polling.

Values: positive integer.

• Authentication:OAuth:Enabled

Meaning: enables OAuth/OIDC login.

Values: true | false.

• Authentication:OAuth:Provider

Meaning: OAuth provider displayed/handled.

Enum-like value used in config: Google (extendable to OIDC-compatible custom providers).

• Authentication:OAuth:Authority

Meaning: OIDC authority/issuer.

Values: URL.

• Authentication:OAuth:ClientId

Meaning: OAuth application client id.

Values: string.

• Authentication:OAuth:ClientSecret

Meaning: OAuth client secret.

Values: string/secret.

• Authentication:OAuth:RequireHttpsMetadata

Meaning: requires OIDC metadata over HTTPS.

Values: true | false.

• Authentication:OAuth:CallbackPath

Meaning: signin callback path.

Values: absolute path.

• Authentication:OAuth:SignedOutCallbackPath

Meaning: signout callback path.

Values: absolute path.

• Authentication:OAuth:AllowedReturnOrigins

Meaning: whitelist of allowed return origins.

Values: array of URLs/origins.

• Authentication:OAuth:Scopes

Meaning: scopes requested from the provider.

Values: array of strings (openid, profile, email, ...).

ADFS via OpenID Connect

ADFS 4.0+ (Windows Server 2016+) speaks OIDC natively: integration with WUIC requires no new code, just the Authentication.OAuth section configured on the ADFS tenant. The pipeline is the same as Google/Auth0/Keycloak — Provider="OpenIdConnect" routes the flow to services.AddOpenIdConnect(...) in Startup.cs:264.

Prerequisites on the ADFS side:

1. Federation Service Name reachable over HTTPS from the WUIC backend (e.g. https://adfs.contoso.com/adfs).

2. OIDC endpoint enabled: verify that https://adfs.contoso.com/adfs/.well-known/openid-configuration returns 200 with the discovery document.

3. Application Group registered in the ADFS Management Console (adfs.msc → Application Groups → Add Application Group → "Server application accessing a web API"):

- Redirect URI: https://<host-wuic>/signin-oidc

- Note down the ClientId (auto-generated) and generate a ClientSecret.

4. Issuance Transform Rules on the Web API: emit at least email, name, upn as claims (needed by the frontend to populate the user profile).

Configuration on the KonvergenceCore side:

Known pitfalls:

• `RequireHttpsMetadata=true` mandatory in production: ADFS exposes the signed metadata over HTTPS; never disable it except in dev against an ADFS with a self-signed cert.
• `CallbackPath` must match the Redirect URI registered in ADFS literally (case-sensitive on the path). If you change one, change the other too.
• Scopes: ADFS supports openid, profile, email, and custom scopes defined in the Application Permissions. If you request a scope not granted to the client, ADFS responds with invalid_scope during consent.
• Single Logout (SLO): SignedOutCallbackPath is called only if ADFS is configured to emit the logout token. If it is missing, after the WUIC logout the browser stays logged in to ADFS and a new WUIC login is silent SSO.
• Coexistence with LDAP: the Authentication.OAuth section (browser-redirect federation) and Authentication.Ldap (direct bind from username/password) are independent. They can coexist — the front-end shows a "Login with ADFS" button in addition to the local form.
• Provider distinct from Google: the Provider==Google branch in Startup.cs:241 uses AddGoogle() with hard-wired scopes. For ADFS set `Provider=OpenIdConnect` (not Google), otherwise the pipeline points to accounts.google.com.
• ADFS 2.0 / 3.0 (Windows Server 2008R2-2012R2): they speak only WS-Federation or SAML 2.0, not OIDC. Those tenants would need an additional PackageReference (Microsoft.AspNetCore.Authentication.WsFederation or Sustainsys.Saml2) and a new branch in Startup.ConfigureServices — out of scope for this section.

Authentication:Ldap (LDAP / Active Directory)

WUIC supports LDAP/AD authentication as an optional provider before the traditional DB login (LDAP-first). When Authentication:Ldap:Enabled=true, the backend attempts a bind against the configured directory server; if the bind succeeds and the user does not yet exist in the local users table, they are auto-provisioned with Authentication:Ldap:DefaultRoleId (or, as a fallback, AppSettings:default-role-id). If LDAP is offline and FallbackToDbOnFailure=true, the login automatically falls back to the DB provider — useful to guarantee admin/admin access even during a directory server outage.

Minimal example:

Available keys:

• Authentication:Ldap:Enabled

Meaning: enables the LDAP provider in front of the DB. When false, the flow is identical to a deployment without the section.

Values: true | false.

• Authentication:Ldap:Host

Meaning: hostname of the directory server (AD DC, OpenLDAP, ApacheDS).

Values: string.

• Authentication:Ldap:Port

Meaning: port of the directory server.

Values: integer. Typically 389 (plain or StartTLS) or 636 (LDAPS).

• Authentication:Ldap:UseSsl

Meaning: opens the connection directly in LDAPS (TLS at-connect).

Values: true | false.

• Authentication:Ldap:UseStartTls

Meaning: opens in plain and then promotes to TLS via the StartTLS extended op (RFC 4511).

Values: true | false. Mutually exclusive with UseSsl.

• Authentication:Ldap:BaseDn

Meaning: base DN under which to search for users.

Values: DN string (e.g. DC=example,DC=com).

• Authentication:Ldap:UserSearchFilter

Meaning: LDAP filter to locate the user entry. The {username} placeholder is replaced with the username (RFC 4515 escaping applied on the C# side to prevent injection).

Values: filter string. Default: (&(objectClass=user)(sAMAccountName={username})) (Active Directory). For OpenLDAP typically use (&(objectClass=inetOrgPerson)(uid={username})).

• Authentication:Ldap:UsernameAttribute

Meaning: entry attribute from which to read the canonical username (used as username_column_name in the local users table).

Values: string. Default: sAMAccountName.

• Authentication:Ldap:DisplayNameAttribute

Meaning: attribute from which to read the display name (used as user_description_column_name).

Values: string. Default: displayName.

• Authentication:Ldap:EmailAttribute

Meaning: attribute from which to read the email (used as email_column_name).

Values: string. Default: mail.

• Authentication:Ldap:BindDn

Meaning: DN of the read-only service account used for the search. Empty = anonymous bind (some ADs allow it for limited searches, OpenLDAP usually does not).

Values: DN string.

• Authentication:Ldap:BindPassword

Meaning: service account password. Never commit it: use a secret manager/env var (Authentication__Ldap__BindPassword) or fill it in post-install from the AppSettings editor.

Values: string/secret.

• Authentication:Ldap:ConnectTimeoutSeconds

Meaning: connection timeout (in seconds) to the directory server. On expiry the login falls back to the DB if FallbackToDbOnFailure=true.

Values: positive integer. Default: 5.

• Authentication:Ldap:FallbackToDbOnFailure

Meaning: if LDAP is unreachable or returns an error not related to credentials, it falls back to the traditional DB login. Guarantees admin/admin access during a directory outage.

Values: true | false. Default: true.

• Authentication:Ldap:AutoProvision

Meaning: on the first successful LDAP login of a user unknown to the local DB, automatically creates the row in _metadati__tabelle.user_table_name (default utenti) with the default role.

Values: true | false. Default: true.

• Authentication:Ldap:DefaultRoleId

Meaning: role id assigned during auto-provisioning. Overrides AppSettings:default-role-id. If both are null, the default is 1.

Values: integer or null.

Known pitfalls

• Bind password never committed: the appsettings.linux.*.json template uses __SET_LDAP_BIND_PASSWORD__ as a placeholder; the deploy script substitutes it. For the "dev" templates (appsettings.json, appsettings.Development.json) the default value is the empty string — never a real secret.
• AD vs OpenLDAP filter: AD uses sAMAccountName, OpenLDAP uses uid. Change UserSearchFilter and UsernameAttribute accordingly.
• StartTLS on port 636: common mistake. 636 is LDAPS (UseSsl=true); StartTLS runs on 389.
• No change to the cookie path: LDAP and DB users receive the same k-user cookie. The difference is only in how the credentials are authenticated.
• Sentinel password: the provisioner inserts '__LDAP__' as the value of the local password column for auto-provisioned users. It is never used to authenticate (the LDAP bind has already validated), but the column must be NOT NULL-compatible.
• Runtime toggle: all Authentication:Ldap:* keys are RestartAndLogout: editing them from the AppSettings editor requires a clean restart.

AppSettings - License

WUIC license keys (RSA signature verified at bootstrap). Hot-reload.

• license-email

Meaning: email the license is issued to (see also Core bootstrap).

Values: valid email.

• license-payload

Meaning: license payload in Base64 (tier, enabled features, expiry, machine fingerprint). Read and verified against license-signature + license-public-key-pem.

Values: Base64 string.

• license-signature

Meaning: RSA signature of the license-payload. If invalid, the license is rejected and the gated features stay disabled.

Values: Base64 string.

• license-public-key-pem

Meaning: RSA public key (PEM) used to verify the signature. The private key never leaves the issuing machine.

Values: PEM.

SQL Retry (SqlMapperRetry)

Automatic retry with backoff on transient SQL operations (deadlock, timeout, lost connection). All keys require a restart.

• SqlMapperRetry:Enabled

Meaning: enables automatic retry on transient SQL errors.

Values: true | false.

• SqlMapperRetry:MaxAttempts

Meaning: maximum number of attempts before propagating the error.

Values: positive integer.

• SqlMapperRetry:BaseDelayMs

Meaning: base delay (ms) for the exponential backoff between attempts.

Values: positive integer.

• SqlMapperRetry:UseJitter

Meaning: adds random jitter to the delay to avoid thundering-herd.

Values: true | false.

• SqlMapperRetry:RetryReadOperationsOnly

Meaning: limits the retry to read operations only (non-idempotent writes are not retried).

Values: true | false.

• SqlMapperRetry:RetryOnTransaction

Meaning: allows the retry even when the operation is inside an explicit transaction.

Values: true | false.

Crash Reporting (CrashReporting)

Sends anonymized stacktraces to the WUIC crash-reporter server. Requires explicit GDPR consent before activation. All keys require a restart (middleware/hosted service registered at startup based on Enabled).

• CrashReporting:Enabled

Meaning: sends the anonymized error details to the private WUIC server. Requires explicit GDPR consent before activation.

Values: true | false.

• CrashReporting:UpstreamUrl

Meaning: receiver endpoint. Default https://errors.wuic-framework.com. To be overridden only for self-hosted on-prem deployments.

Values: URL.

• CrashReporting:ClientId

Meaning: client id override. If empty, the email from the license payload is used as the authoritative client_id.

Values: string.

• CrashReporting:DisclaimerAcceptedVersion

Meaning: read-only audit field set by the consent flow. Incremented when the disclaimer text changes (forces re-consent).

Values: string.

• CrashReporting:DisclaimerAcceptedAt

Meaning: read-only audit timestamp set by the consent flow.

Values: string (date/time).

• CrashReporting:MaxQueueSize

Meaning: capacity of the bounded channel; the oldest entries are dropped under sustained crash-storms.

Values: positive integer.

• CrashReporting:MaxBreadcrumbsLen

Meaning: breadcrumb limit per report (UTF-8 bytes). Truncated if exceeded.

Values: positive integer.

• CrashReporting:DedupTtlSeconds

Meaning: window within which identical stack hashes are counted as duplicates.

Values: positive integer.

• CrashReporting:DedupFlushEvery

Meaning: flush every N-th repeated occurrence (1 = no dedup, always send).

Values: positive integer.

RAG Chatbot (LLM)

Configuration of the <wuic-rag-chatbot> component and the .NET RAG engine (WuicRagEngine). The keys are read hot-reload by the .NET backend. Not hard-coded.

• rag-llm-provider

Meaning: provider of the conversational model. Must be set explicitly. anthropic uses the Anthropic format (Claude); openai/openrouter/ollama use an OpenAI-compatible endpoint. ollama points to a local Ollama via rag-llm-base-url (e.g. http://HOST:11434/v1). If empty or unset the chatbot stays in retrieval-only (no LLM invoked): there is no default provider.

Values: anthropic | openai | openrouter | ollama | empty (= retrieval-only, no LLM).

• rag-llm-api-key

Meaning: the ONLY source of the api key, independent of the provider chosen above. Special value agent-sdk = uses the Agent SDK (claude CLI) via subscription instead of the metered API, if installed. For ollama a dummy key (e.g. ollama) is sufficient. Empty = LLM disabled (retrieval only). Never commit it to the repo: use a secret manager / env var override.

Values: string (provider api key) | agent-sdk | ollama (dummy).

• rag-llm-base-url

Meaning: override of the provider endpoint. Mandatory for `ollama` (e.g. http://HOST:11434/v1). Empty = default per provider (https://api.anthropic.com, https://api.openai.com/v1, https://openrouter.ai/api/v1).

Values: URL.

• rag-llm-default-chat-model

Meaning: model used by the chatbot for each new turn (also determines the max context window).

Values: depends on the provider, e.g. claude-haiku-4-5-20251001 (anthropic) | qwen2.5-coder:32b (ollama).

• rag-auto-compact-threshold

Meaning: threshold in number of turns beyond which the backend automatically triggers a best-effort compact pre-Ask (summarizes the old turns into _rag_chat_sessions.context_summary). Set to 0 to disable auto-compact (the user can still trigger /compact manually via the UI).

Values: integer >=0. Recommended default: 30.

Operational notes

• In production always use a secret manager/environment variables for passwords/tokens (email-pwd, ClientSecret, captcha key, etc.).
• If you enable allowMultipleDBMS, validate that dbms and meta-dbms are both supported by the deployment.
• For realtime notifications, Notifications:Mode=SqlDependency requires a compatible SQL setup; alternatively use Polling.

Real appsettings.json (snapshot)