Overview
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
AppSettingsare 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:DefaultMeaning: default log level for all non-overridden categories. Typical default:Warning.Logging:LogLevel:SystemMeaning: level for theSystemcategory (.NET runtime).Logging:LogLevel:MicrosoftMeaning: level for theMicrosoftcategory (ASP.NET Core, EF, hosting).
AppSettings - Core bootstrap
firstRunMeaning: enables the first-time configuration/provisioning flow. Values:true | false. Typical default:false. Note: release packages ship withtrue(the wizard opens at first start and sets the key back tofalse). Withfalsethe wizard methods ([AsmxFirstRun]) answer only administrators.preScaffoldMeaning: enables pre-scaffolding of metadata/app objects. Values:true | false. Typical default:false.projectDataFolderMeaning: application project root (e.g. CrmApp) used for files, assemblies and runtime resources. Values: absolute filesystem path.projectAssemblyNameMeaning: application assembly loaded dynamically. Values: absolute.dllpath.defaultSiteRouteMeaning: initial client route after bootstrap/login. Values: hash-route (e.g.#/).license-emailMeaning: installation email/license. Values: valid email.
AppSettings - Database and provider
dbmsMeaning: main DB provider for data routes. Enum-like values:mssql | mysql | postgresql | oracle | xml. Typical default:mssql.meta-dbmsMeaning: metadata DB provider (system routes). Enum-like values:mssql | mysql | postgresql | oracle | xml. Typical default: same asdbms.allowMultipleDBMSMeaning: enables coexistence of multiple providers at runtime. Values:true | false. Typical default:false.connectionMeaning: base connection string used by services/scaffolding. Values: provider-specific connection string.DataDBNameMeaning: default data database name. Values: DB name.connectionByUserMeaning: uses a connection/context bound to the current user at specific runtime points. Values:true | false. Typical default:false.
AppSettings - CRUD, query, filters
autoGeneratedQueryTimeoutMeaning: timeout (seconds) for auto-generated SQL queries. Values: positive integer. Typical default:120.storedProcTimeoutMeaning: timeout (seconds) for stored procedure execution. Values: positive integer.enableServerSideCrudChangeLogMeaning: enables server-side logging of CRUD operations. Values:true | false. Typical default:true.optimisticCheckEnabledMeaning: 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.logicDeleteFieldMeaning: global field for logical deletion (if not defined in the table metadata). Values: column name.logicDeleteValueMeaning: value that represents a "logically deleted record". Values: string/number compatible with the field type. Typical default:1.cacheDataMinutesMeaning: in-memory cache of list results (one entry per route and query text, per tenant); a write on the route clears its entries. Values: missing or0= cache off (default, nothing is kept in memory); positive integer = minutes an entry stays valid;-1= no expiry. Limit: at most 500 queries per route; to make room, expired entries are removed first, then the oldest ones.cacheDataIncludedRoutesMeaning: whitelist of cacheable routes. Values: comma-separated list of routes.cacheDataExcludedRoutesMeaning: blacklist of routes to exclude from the cache. Values: comma-separated list of routes.traceQueryMeaning: enables SQL query tracing with execution times. Values:true | false. Typical default:false. Content: withtrueevery successful AsmxProxy call writes method, duration and request body to_error__logs. Since 1.7.28 the body of login and credential methods (login,resetPassword,changePassword,register,createApiToken...) is not logged, and in the other bodies fields with a secret-like name (password,newPassword,pwd,token,captchaToken,secret,api_key...) become***. Application and personal data remain, visible to whoever reads_error__logsor its backups: keep it off in production. Since round 2 of 1.7.28: in every traced value (connection strings ofupdateConnection,insertConnection,get_database_names,configure_wuic, scaffolding...) the text afterPassword=/pwd=becomes***; the route's password columns with any name (mc_ui_is_password) are masked in the body; in_log_querywrites (insert, update, clone) on a table with password columns do not log the SQL text ([omesso: scrittura su una tabella con colonne password]) and in the other queries connection passwords are masked.sqlVerboseMeaning: enables verbose SQL output in endpoints/tools that support it. Values:true | false. Default:false(since 1.7.28 also in the shippedappsettings.json). Who gets it:sqlQueryin the response goes only to the verified superadmin; for other users the response has no query even withtrue(since 1.7.28; before, any caller received it, with the row and tenant restriction predicates and the written values). On SQL Server the list read passes filter values and paging as parameters (@wq0,@wq1...,@wq_skip,@wq_take): the reported query (sqlQueryin the response and_log_querywithtraceQuery) starts with oneDECLAREper parameter with its value, followed by the query, and runs as is in SSMS, e.g.DECLARE @wq0 varchar(8000) = '%Tailspin%'; DECLARE @wq_skip int = 25; DECLARE @wq_take int = 25;. On MySQL, PostgreSQL and Oracle the values travel the same way (@wq0... on MySQL and PostgreSQL,:wq0... on Oracle) and the reported query has three parts: a comment listing the parameters and their values (-- WUIC parametri: @wq0 = '%Tailspin%', @wq_skip = 25, ...), the parametric query as it reaches the DBMS, commented line by line after-- WUIC query parametrica:(with@wq0/:wq0in place of the values), and after-- WUIC query eseguibile (valori al posto dei parametri):the same query with the values in place of the placeholders, the only uncommented part: it can be pasted and run as is in MySQL Workbench, psql/pgAdmin or SQL Developer. Queries without parameters keep the usual format.logInvokeMeaning: enables logging of dynamic function/callback invocations. Values:true | false.
maxConcurrentExportsMeaning: maximum number of XLS exports the process runs at the same time; the others wait in a queue and the progress dialog and the notification show their position ("Queued: position N"). Values: positive integer. Note: if absent or invalid, the backend uses half of the machine's cores (at least 1). The limit is per process: every node or application pool has its own. Sizing: every running export uses about 1.3 cores and keeps the uncompressed sheet in memory until the file is closed (measured on 25/09/2026 with 228k rows x 13 columns: ~300 MB per export). On a machine shared with other application pools a value lower than the default is advisable: on the public demo (8 cores, 8 application pools) it is2, because 4 exports together took the process to 60-75% of the machine. Example:"maxConcurrentExports": "2"inAppSettings(appsettings.json or the environment overlay, e.g.appsettings.Demo.json); the value is read at every export, but after editing the file recycle the application pool if the configuration does not reload by itself.maxQueuedExportsMeaning: maximum number of exports waiting; beyond it the request answers 503errors.metaservice.export.queue_full(every queued export keeps a request thread busy). Values: positive integer. Note: if absent or invalid, the backend uses10.
AppSettings - Security, login, session
customAuthenticationMeaning: delegates authentication to custom application logic. Values:true | false.enableCookieAuthenticationMeaning: controls who writes thek-usersession cookie, with which policy, and how the server checks it. Values:false | true | "signed"("signed"since 1.7.21). Missing or empty key:"signed"(since 1.7.28; before it meantfalse), reported at startup by the line[security] enableCookieAuthentication assente o vuota: uso "signed"...; the no-authentication mode is chosen only by writingfalse. Changing it requires a restart and a new login.
Concise comparison of the three modes:
| Aspect | false (client-managed) | true (server-managed, token) | "signed" (server-managed, signed) |
|---|---|---|---|
| Who writes the cookie | Frontend JavaScript after login | Backend via Set-Cookie | Backend via Set-Cookie |
| Format | k-user=<urlencoded-json> | k-user=<urlencoded-json> | k-user=s1.<expiry>.<signature>.<json> (HMAC-SHA256 signature, content not encrypted) |
HttpOnly | No (readable by JS) | Yes (XSS protection) | Yes |
SameSite | — | Lax (CSRF protection) | Lax |
Secure | — | Yes over HTTPS, off on http://localhost | Same as true |
| Expiry | — | sessionTimeoutMinutes (default 60), renewed at every request | Same as true; the expiry is also inside the signature, so the server enforces it |
| Server-side check at every request | Privileges and role declared in the cookie compared with the DB | Token + IP + timeout on DB | Signature and expiry; privileges and role compared with the DB |
| Sessions per user | Several concurrent sessions | Only one (last login wins) | Several concurrent sessions |
| Cookie editable by the client | Yes, including the user: the DB only blocks privileges higher than those of the given user, not the identity (see below) | No | No: any change invalidates the signature |
| IP binding | No | Yes (IP change forces re-login) | No |
| Required DB schema | Standard | Columns token, ip, LastActivityDate | Table _wuic_revoked_sessions (created automatically at startup) |
| Logout | MetaService.logout | MetaService.logoutSession (clears the DB token) | MetaService.logoutSession (revokes that browser's session) |
| When to use it | Development and CI only: it does not authenticate (see below) | Production exposed to the internet, one session per user | Production with several sessions per user (shared accounts, demos, multiple browsers) |
### 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.
### Mode "signed" (since 1.7.21)
- The cookie is signed with the cookie-signing-key key (see below). Missing or invalid signature, expired or edited cookie: it counts as no cookie, the request answers 401 errors.auth.unauthenticated and the frontend goes back to the login.
- As with false, several logins of the same user coexist: a new login does not disconnect the other browsers. Unlike false, the client cannot change anything in the cookie (user, role, company, language).
- Every login is a session of its own (sid inside the signed cookie, unchanged by renewals). Logout revokes it on the DB (_wuic_revoked_sessions): the cookie of that browser and every copy of it are rejected, the other sessions of the same user stay logged in. Details in the next section.
- The frontend never writes the cookie: language change (MetaService.setCurrentUserLanguage) and company change (MetaService.switchAzienda) re-issue it from the server.
- Scripts and tests that call the API must send back the cookie received from the login (cookie jar or Set-Cookie) as is, without building it: backend-api-client.mjs and the scaffold-*.ps1 scripts already do so.
### Login, logout and several sessions of the same user
A "session" is a k-user cookie. Tabs and windows of the same browser (same profile, not incognito) share a single cookie, so they are always one session, in all three modes: a login in one tab applies to all of them (even with a different user, who replaces the previous one), and a logout in one tab also disconnects the others at their next request. Independent sessions need different browsers, different profiles or an incognito window.
| Case | false | true | "signed" |
|---|---|---|---|
| Second login of the same user from another browser or device | Both stay logged in | The first browser is disconnected at its next request (session_replaced) | Both stay logged in |
| Logout from a browser | The frontend deletes the cookie; there is nothing to close on the server | Token cleared on the DB: the cookie is no longer valid | Revokes that browser's session; the other sessions of the same user stay logged in |
| Copy of the cookie used after logout | Valid. The cookie only holds the user_id: it can even be built without ever receiving it | Rejected (401) | Rejected (401): the session is revoked on the DB |
No request for more than sessionTimeoutMinutes | No server-side expiry | Session expired (session_expired): new login | Cookie expired: new login, on that browser only |
Logout of another user by an administrator (MetaService.logout) | No server-side effect | The user is disconnected immediately | All their sessions opened up to that moment are rejected; a new login works. With multi-tenant it applies only to the user of that company, not to users with the same id in other companies |
Password reset (MetaService.resetPassword) or new password saved on the users row | No effect on sessions | Every open session of the user is closed (token cleared as on logout), including the one saving it if it is theirs: log in again with the new password (since 1.7.28; before they stayed open) | Every open session of the user is rejected, including the one saving it if it is theirs: log in again with the new password (since 1.7.21) |
Session used without pauses for more than signedSessionMaxLifetimeHours (default 24 hours) | No limit | No limit: it expires only through inactivity | Rejected: new login, even while in use (since 1.7.21) |
| IP address change | No effect | New login required | No effect |
| User deleted or role changed | Rejected at the next request | Rejected at the next request | Rejected at the next request |
In practice:
- false does not authenticate: whoever knows or guesses a user_id gets in as that user. Use it only for development and CI, never on an installation reachable by others. As a reminder, at every start the backend writes the log line [security] enableCookieAuthentication=false: NESSUNA autenticazione... and the AppSettings editor asks for confirmation before saving false.
- true and "signed" close the session also for whoever holds a copy of it, both with your own logout and with an administrator's.
- The difference is in concurrent sessions: with true the last login kicks out the other browsers, with "signed" they coexist and logout closes only the browser that asks for it (an administrator's closes them all). To close the sessions of every user at once, change cookie-signing-key.
### 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.
- Since 1.7.13 the token and expiry check applies to every provider, PostgreSQL and Oracle included, and logout closes only the caller's session: see Authentication & Authorizations.
- After a mode change the cookies already issued are no longer valid (switching to "signed" the signature is missing; going back to true/false the signed cookie is not JSON) → users must log in again.
- In the AppSettings editor the key is a three-value list; in the file both the strings "true"/"false"/"signed" and JSON booleans are accepted.
cookie-signing-key(since 1.7.21) Meaning: HMAC-SHA256 key that signs thek-usercookie withenableCookieAuthentication = "signed"; ignored in the other modes. Values: base64 of at least 32 bytes, e.g. the output of[Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)). Default: empty. When empty, the backend generates it at the first login and saves it inappsettings.json; if the file is not writable (or the current value is not valid) it uses an in-memory key and a new login is needed after every restart. Note: it is a secret (whoever knows it can sign valid cookies): do not commit it or copy it between installations. With several instances behind a load balancer it must be set by hand, identical on all of them: left empty, each instance generates its own and the cookies issued by one are not valid on the others (random 401s). Changing it disconnects every user. Log: at startup, in"signed"mode, the backend writes the key fingerprint ([security] enableCookieAuthentication=signed: impronta della chiave di firma 1a2b3c4d5e6f7a8b ...: the first 8 bytes of the SHA-256, not the key). Different fingerprints across instances = different keys. A key generated on the fly is reported by the line[security] cookie-signing-key generata ora...: if it shows up at every start, the saved value is not being read (e.g. an environment variable or anappsettings.{Environment}.jsonthat sets it empty). Upgrading to 1.7.28 with several nodes: withoutenableCookieAuthenticationthe mode is"signed"(previouslyfalse) and, withoutcookie-signing-key, every node generates its own key: setcookie-signing-keyto the same value on all nodes (and writeenableCookieAuthenticationexplicitly) before upgrading. On the start where the key is generated with the mode taken from the default, the backend logs[security] ERROR: enableCookieAuthentication assente ...; startup is not blocked (a single node needs nothing else).signedSessionMaxLifetimeHours(since 1.7.21) Meaning: maximum lifetime of a"signed"session, in hours from login. The cookie is renewed at every request, but renewal does not move the login time: after these hours the session is rejected even while in use and a new login is needed. It limits how long a stolen copy of the cookie can be used. Ignored in the other modes. Values: integer;0= no limit (not recommended: a copy of the cookie used continuously never expires). Default:24(also when the value is empty, not numeric or negative). Read at every request. Note: revocations in_wuic_revoked_sessionsare kept until login + maximum lifetime +sessionTimeoutMinutes, so a revoked cookie does not become valid again when the row is deleted.enableODATAAuthenticationMeaning: enables auth for OData endpoints. Values:true | false. Note: since 1.7.13 the/odata/*data endpoints always require a valid session, regardless of this key. Since 1.7.21 so do/odata,/odata/$metadataand/odata/openapi.json(seeodataPublicMetadata).odataPublicMetadata(since 1.7.21) Meaning:true=/odata,/odata/$metadataand/odata/openapi.jsonanswer without a session, as up to 1.7.20: anyone can see which tables are exposed and with which columns (not the data). For clients that read the service shape before authenticating. Values:true | false. Default:false(a session is required, as for the data). Read on every request.apiTokensEnabled(since 1.7.21) Meaning: personal tokens for external clients. Each user creates them from the user menu ("API tokens"); they work with the owner's permissions and in the company where they were created: scopesodata.read/odata.writeon/odatafor Power BI, Excel and scripts (see OData, section "Personal tokens"); scopesnl-queryandapp-generatorfor "Ask your data" and the app generator from WUIC Assistant and Claude Code (see Ask your data, section "From WUIC Assistant and Claude Code"). Values:true | false. Default:false. Read on every request (no restart): when off, existing tokens are rejected (401errors.auth.api_tokens_disabled) and the menu item disappears.apiTokenMaxLifetimeDays(since 1.7.21) Meaning: maximum validity of a personal token, in days. Every token has an expiry: 90 days by default (or this value, if lower). Values: integer > 0. Default:365(also when empty, non-numeric or <= 0). Read on every request.apiTokenAllowedRoles(since 1.7.22) Meaning: ids of the roles (comma separated) that can create and use personal tokens. Removing a role also stops the tokens its users already created; superadmins always can. Values: list of role ids. Default: empty (every role). Read on every request.apiTokenWriteRoles(since 1.7.22) Meaning: ids of the roles (comma separated) that can create and use tokens with write access (odata.write). Removing a role makes the write tokens already created read-only. Values: list of role ids. Default: empty (every role that can create tokens). Read on every request.odataMaxTop(since 1.7.22) Meaning: maximum rows per response on/odata/<entity set>: a larger$topanswers 400, without$topthe response stops at this number (since 1.7.28; with$count=truethe wrapper carries@odata.nextLink). Values: integer > 0. Default:1000(also when empty, non-numeric or <= 0). Read on every request.odataMaxExpandDepth(since 1.7.22) Meaning: deepest$expandnesting (a($expand=b)= 2); deeper answers 400. Values: integer > 0. Default:2. Read on every request.odataMaxNodeCount(since 1.7.28) Meaning: maximum nodes of$filter,$orderbyand$expand(nested ones included) for non-superadmins; beyond it answers 400errors.input.invalid.$selectcolumns do not count. Values: integer > 0. Default:100(also when empty, non-numeric or <= 0). Read on every request.forwardedHeadersKnownProxies/forwardedHeadersKnownNetworks(since 1.7.22) Meaning: IP addresses (and CIDR networks, e.g.10.0.0.0/8) of the reverse proxies or load balancers in front of the backend whoseX-Forwarded-Foris trusted, in addition to localhost. Without them the client IP is the proxy's, and rate limits (login, API tokens) hit every client behind it together. Values: comma-separated lists. Default: empty (localhost only). Read at startup.enableHttpsRedirectionMeaning: forces the HTTP→HTTPS redirect + HSTS. Defaultfalse(no redirect, no HSTS): the app responds over both HTTP and HTTPS. SettrueONLY on hosts with a valid HTTPS certificate (activatesUseHttpsRedirection/UseHsts). Values:true | false. Default:false. Restart. Meaning: enables guest access. Values:true | false.applyGrantByDefaultToGuestMeaning: applies default grants to the guest user as well. Values:true | false.grantDashSaveToGuestMeaning: allows the guest to save dashboards. Values:true | false.default-role-idMeaning: role assigned as fallback/default. Values: integer (role ID). Note: for registration it must point to an existing role withoutadmin/superadminrights, otherwise registration is refused.registrationEnabledMeaning: enables self-service user registration. Without an explicittrueregistration is not available. Values:true | false. Default:false.loginRateLimitPerIpPerMinute(since 1.7.16) Meaning: maximum number of login attempts per minute (successful or not) from the same IP; once exceeded, the IP gets HTTP 429errors.auth.login_rate_limitedfor 1 minute. Protects against credential stuffing (many usernames tried from the same IP). Values: integer;0= per-IP limit off. Default:0(also when the value is not numeric or is negative). Note: on installations exposed to the internet it should be set, e.g.30. The per-user limit (5 wrong passwords in 5 minutes, 1-minute lockout) is always on and does not depend on this key. Loopback is never limited. Up to 1.7.15 the per-IP limit was fixed at 30 attempts per minute, with only loopback exempt. Details in Authentication & Authorizations. Example:"loginRateLimitPerIpPerMinute": "30"; the value is read at every login, but after editing the file recycle the application pool if the configuration does not reload by itself.loginRateLimitExemptIps(since 1.7.16) Meaning: IPs exempt from the login attempt limit, treated like loopback: they are never limited or counted. Meant for stress tests that log in hundreds of users from the same IP. Values: comma-separated IPs (spaces allowed). The match is exact; the IPv4-mapped form (::ffff:10.0.2.2) is equivalent to10.0.2.2. Example:"loginRateLimitExemptIps": "10.0.2.2, 192.168.1.50".sessionTimeoutMinutesMeaning: user session timeout in minutes. Values: positive integer. Typical default:60.notifySessionExpirationBeforeMeaning: lead time (minutes) for the session expiration notice. Values: positive integer. Typical default:1or2depending on the environment.enableUserLanguageSwitchMeaning: enables the user language switch in the UI. Values:true | false.
AppSettings - Password and credential policy
IsPwdEncriptedMeaning: indicates whether the passwords in the store are hashed. Values:true | false.encriptionMethodMeaning: legacy hash algorithm used for password verification. Enum-like values:SHA1 | MD5. Typical default:SHA1.password_min_lengthandpassword_min_lengthMeaning: 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_keyMeaning: captcha public key. Values: string.captcha_private_keyMeaning: captcha private key. Values: string.enableDoubleTokenAuthenticationMeaning: enables an additional token verification step in the intended login/activation flow. Values:true | false.site-urlMeaning: site base URL for absolute email/workflow links. Values: absolute URL.content-urlMeaning: base URL for content/confirmation links (mailing, read-confirm, etc.). Values: absolute URL.
AppSettings - Email and mail notifications
email-hostMeaning: SMTP host. Values: hostname/IP.email-portMeaning: SMTP port. Values: integer (25,465,587, ...).email-sslMeaning: enables SMTP TLS/SSL. Values:true | false.email-userMeaning: SMTP username. Values: string.email-pwdMeaning: SMTP password. Values: string/secret.email-sender-address-mailingMeaning: sender for mailing/notification emails. Values: valid email.email-sender-name-mailingMeaning: mailing sender display name. Values: string.email-sender-address-registrationMeaning: sender for registration/activation emails. Values: valid email. Note: since 1.7.13 it no longer turns registration on:registrationEnabled = trueis required.email-admin-registrationMeaning: administrative recipient for registration events. Values: valid email.email_confirm_token_subjectMeaning: subject template for the token confirmation email. Values: string.email_confirm_token_bodyMeaning: body template for the token confirmation email. Values: string (HTML allowed).
AppSettings - Upload and media
uploadFolderMeaning: root folder for file/image uploads. Values: absolute path. A relative value is ignored and<projectDataFolder>/Uploadis used. Note: since 1.7.13 the code that writes the file and the code that reads it back for BLOB columns use the same resolution on every provider.base64ImageMeaning: forces handling of images in base64 format where applicable. Values:true | false.tmpExportRetentionHours(since 1.7.28) Meaning: lifetime in hours of the files inTmp_export(Excel/PDF exports). The folder is served without login (links also arrive by email and from the scheduler), so a link stays valid as long as the file exists: every 30 minutes the files modified more than this many hours ago are deleted. Read on every run. Values: number of hours (decimals allowed, with a dot);0or negative = cleanup off. Default:24(also when empty or not numeric).
AppSettings - Report and report viewer runtime
ReportModeMeaning: 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 thewebfallback.reportQueryTimeoutMeaning: timeout for report dataset queries (seconds), applied to the SQL data sources left at the Designer default timeout (30). Values: positive integer. Note: if absent or invalid, the backend uses the120fallback.
AppSettings - Record translations (legacy keys in AppSettings)
recordTranslationsEnabledMeaning: enables per-field record translation. Values:true | false.recordTranslationsDefaultTableNameMeaning: default record translations table. Values: table name.recordTranslationsTranslationJsonFieldNameMeaning: name of the translations JSON field. Values: column name.recordTranslationsDefaultLanguageMeaning: fallback language for record translations. Values: culture code (e.g.it-IT,en-US).recordTranslationsFieldNamesMeaning: list of translatable fields. Values: comma-separated list.
Related top-level sections (outside AppSettings)
RecordTranslations:EnabledMeaning: main runtime switch for record translations. Values:true | false.RecordTranslations:DefaultTableNameMeaning: physical translations table. Values: table name.RecordTranslations:TranslationJsonFieldNameMeaning: translations JSON field. Values: column name.RecordTranslations:DefaultLanguageMeaning: fallback language. Values: culture code.RecordTranslations:FieldNamesMeaning: translatable fields. Values: array of strings.Scheduler:EnabledMeaning: enables the scheduling hosted service. Values:true | false.Scheduler:PollSecondsMeaning: scheduler polling in seconds. Values: positive integer.Scheduler:MaxTasksPerCycleMeaning: maximum tasks processed per cycle. Values: positive integer.Scheduler:RetryDelaySecondsMeaning: retry delay for failed tasks. Values: positive integer.Scheduler:SqlCommandTimeoutSecondsMeaning: scheduler SQL timeout. Values: positive integer.Notifications:EnabledMeaning: enables the realtime notifications subsystem. Values:true | false.Notifications:ModeMeaning: backend notifications watcher mode. Enum-like values:SqlDependency | Polling.Notifications:PollSecondsMeaning: notifications polling ifMode = Polling. Values: positive integer.notificationInitialSnapshotConcurrency(inAppSettings) Meaning: how many newly opened WebSockets read and send the initial snapshot of unread notifications at the same time; the others wait their turn without holding a thread or a connection to the metadata DB. Values: integer;0or negative = no limit. Note: if absent or invalid, the backend uses32. It is read once, at the first WebSocket connection of the process: restart the backend after changing it. The limit is per process. Why: during a burst of logins (load test with 6000 users, MySQL) every new socket held a metadata pool connection for its snapshot, and the pool ran out before the regular requests.Authentication:OAuth:EnabledMeaning: enables OAuth/OIDC login. Values:true | false.Authentication:OAuth:ProviderMeaning: OAuth provider displayed/handled. Enum-like value used in config:Google(extendable to OIDC-compatible custom providers).Authentication:OAuth:AuthorityMeaning: OIDC authority/issuer. Values: URL.Authentication:OAuth:ClientIdMeaning: OAuth application client id. Values: string.Authentication:OAuth:ClientSecretMeaning: OAuth client secret. Values: string/secret.Authentication:OAuth:RequireHttpsMetadataMeaning: requires OIDC metadata over HTTPS. Values:true | false.Authentication:OAuth:CallbackPathMeaning: signin callback path. Values: absolute path.Authentication:OAuth:SignedOutCallbackPathMeaning: signout callback path. Values: absolute path.Authentication:OAuth:AllowedReturnOriginsMeaning: whitelist of allowed return origins. Values: array of URLs/origins.Authentication:OAuth:ScopesMeaning: 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(...).
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:
"Authentication": {
"OAuth": {
"Enabled": true,
"Provider": "OpenIdConnect",
"Authority": "https://adfs.contoso.com/adfs",
"ClientId": "<application-group-client-id>",
"ClientSecret": "__SET_VIA_SECRET_MANAGER__",
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 withinvalid_scopeduring consent. - Single Logout (SLO):
SignedOutCallbackPathis 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.OAuthsection (browser-redirect federation) andAuthentication.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==Googlebranch usesAddGoogle()with hard-wired scopes. For ADFS set `Provider=OpenIdConnect` (notGoogle), otherwise the pipeline points toaccounts.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.WsFederationorSustainsys.Saml2) and a new branch inStartup.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:
"Authentication": {
"Ldap": {
"Enabled": true,
"Host": "ldap.corp.example.com",
"Port": 389,
"UseStartTls": true,
"BaseDn": "OU=Users,DC=corp,DC=example,DC=com",
Available keys:
Authentication:Ldap:EnabledMeaning: enables the LDAP provider in front of the DB. Whenfalse, the flow is identical to a deployment without the section. Values:true | false.Authentication:Ldap:HostMeaning: hostname of the directory server (AD DC, OpenLDAP, ApacheDS). Values: string.Authentication:Ldap:PortMeaning: port of the directory server. Values: integer. Typically389(plain or StartTLS) or636(LDAPS).Authentication:Ldap:UseSslMeaning: opens the connection directly in LDAPS (TLS at-connect). Values:true | false.Authentication:Ldap:UseStartTlsMeaning: opens in plain and then promotes to TLS via the StartTLS extended op (RFC 4511). Values:true | false. Mutually exclusive withUseSsl.Authentication:Ldap:BaseDnMeaning: base DN under which to search for users. Values: DN string (e.g.DC=example,DC=com).Authentication:Ldap:UserSearchFilterMeaning: 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:UsernameAttributeMeaning: entry attribute from which to read the canonical username (used asusername_column_namein the local users table). Values: string. Default:sAMAccountName.Authentication:Ldap:DisplayNameAttributeMeaning: attribute from which to read the display name (used asuser_description_column_name). Values: string. Default:displayName.Authentication:Ldap:EmailAttributeMeaning: attribute from which to read the email (used asemail_column_name). Values: string. Default:mail.Authentication:Ldap:BindDnMeaning: 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:BindPasswordMeaning: 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:ConnectTimeoutSecondsMeaning: connection timeout (in seconds) to the directory server. On expiry the login falls back to the DB ifFallbackToDbOnFailure=true. Values: positive integer. Default:5.Authentication:Ldap:FallbackToDbOnFailureMeaning: if LDAP is unreachable or returns an error not related to credentials, it falls back to the traditional DB login. Guaranteesadmin/adminaccess during a directory outage. Values:true | false. Default:true.Authentication:Ldap:AutoProvisionMeaning: on the first successful LDAP login of a user unknown to the local DB, automatically creates the row in_metadati__tabelle.user_table_name(defaultutenti) with the default role. Values:true | false. Default:true.Authentication:Ldap:DefaultRoleIdMeaning: role id assigned during auto-provisioning. OverridesAppSettings:default-role-id. If both arenull, the default is1. Values: integer ornull.
Known pitfalls
- Bind password never committed: the
appsettings.linux.*.jsontemplate 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 usesuid. ChangeUserSearchFilterandUsernameAttributeaccordingly. - 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-usercookie. 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 areRestartAndLogout: editing them from the AppSettings editor requires a clean restart.
AppSettings - License
WUIC license keys (RSA signature verified at bootstrap). Hot-reload.
license-emailMeaning: email the license is issued to (see also Core bootstrap). Values: valid email.license-payloadMeaning: license payload in Base64 (tier, enabled features, expiry, machine fingerprint). Read and verified againstlicense-signature+license-public-key-pem. Values: Base64 string.license-signatureMeaning: RSA signature of thelicense-payload. If invalid, the license is rejected and the gated features stay disabled. Values: Base64 string.license-public-key-pemMeaning: 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.
Release packages use MaxAttempts = 3 and BaseDelayMs = 100, and the release pipeline rejects lower values: if an upgraded installation has lower values, set them back to these.
SqlMapperRetry:EnabledMeaning: enables automatic retry on transient SQL errors. Values:true | false.SqlMapperRetry:MaxAttemptsMeaning: maximum number of attempts before propagating the error. Values: positive integer.SqlMapperRetry:BaseDelayMsMeaning: base delay (ms) for the exponential backoff between attempts. Values: positive integer.SqlMapperRetry:UseJitterMeaning: adds random jitter to the delay to avoid thundering-herd. Values:true | false.SqlMapperRetry:RetryReadOperationsOnlyMeaning: limits the retry to read operations only (non-idempotent writes are not retried). Values:true | false.SqlMapperRetry:RetryOnTransactionMeaning: 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:EnabledMeaning: sends the anonymized error details to the private WUIC server. Requires explicit GDPR consent before activation. Values:true | false.CrashReporting:UpstreamUrlMeaning: receiver endpoint. Defaulthttps://errors.wuic-framework.com. To be overridden only for self-hosted on-prem deployments. Values: URL.CrashReporting:ClientIdMeaning: client id override. If empty, the email from the license payload is used as the authoritativeclient_id. Values: string.CrashReporting:DisclaimerAcceptedVersionMeaning: read-only audit field set by the consent flow. Incremented when the disclaimer text changes (forces re-consent). Values: string.CrashReporting:DisclaimerAcceptedAtMeaning: read-only audit timestamp set by the consent flow. Values: string (date/time).CrashReporting:MaxQueueSizeMeaning: capacity of the bounded channel; the oldest entries are dropped under sustained crash-storms. Values: positive integer.CrashReporting:MaxBreadcrumbsLenMeaning: breadcrumb limit per report (UTF-8 bytes). Truncated if exceeded. Values: positive integer.CrashReporting:DedupTtlSecondsMeaning: window within which identical stack hashes are counted as duplicates. Values: positive integer.CrashReporting:DedupFlushEveryMeaning: 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-providerMeaning: provider of the conversational model. Must be set explicitly.anthropicuses the Anthropic format (Claude);openai/openrouter/ollamause an OpenAI-compatible endpoint.ollamapoints to a local Ollama viarag-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-keyMeaning: the ONLY source of the api key, independent of the provider chosen above. Special valueagent-sdk= uses the Agent SDK (claudeCLI) via subscription instead of the metered API, if installed. Forollamaa 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-urlMeaning: 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-modelMeaning: 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-thresholdMeaning: 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 to0to disable auto-compact (the user can still trigger/compactmanually via the UI). Values: integer >=0. Recommended default:30.
Metadata lifecycle (MetaLifecycle)
MetaLifecycle:SystemBaseline:ModeMeaning: startup realignment of the system metadata rows to the framework baseline (3-way comparison, see Metadata lifecycle).applyupdates the non-customized rows and inserts the missing ones, with abefore-framework-upgradesnapshot before writing;reportcomputes and logs without changing anything;offdisables it. Customizations are never overwritten in any mode. Read at startup (restart required). Values:apply(default) |report|off.
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 thatdbmsandmeta-dbmsare both supported by the deployment. - For realtime notifications,
Notifications:Mode=SqlDependencyrequires a compatible SQL setup; alternatively usePolling. - The AppSettings editor (
/api/AppSettings/*) checks the session and thesuperadminrole server-side: a user without that role gets 401, even if namedadminor holding a role called admin.
Real appsettings.json (snapshot)
{
"Logging": {
"LogLevel": {
"Default": "Warning"
}
},
"Authentication": {
Screenshot
