Configuration Management
Manage Elsa Server, Elsa Studio, and modular host configuration with appsettings, environment overrides, and source-backed section names for release 3.8.0.
This guide shows how Elsa 3.8 hosts read configuration, which section names they actually bind in the release source, and where environment overrides fit. It focuses on the shipped host patterns in release/3.8.0:
Elsa.Server.Webinelsa-coreElsa.ModularServer.Webinelsa-coreElsa.Studio.Host.ServerandElsa.Studio.Host.Wasminelsa-studio
Use this guide when you need to answer questions such as:
Which settings belong in
appsettings.jsonversus code?Which keys can I override with environment variables?
Why did a setting not change anything?
Which settings must stay aligned across Elsa Server, Studio, and my reverse proxy?
How Elsa Reads Configuration
Elsa does not add a custom global configuration system on top of ASP.NET Core. The shipped server hosts start with WebApplication.CreateBuilder(args), and the WASM Studio host starts with WebAssemblyHostBuilder.CreateDefault(args). After that, each host binds specific configuration sections into options inside Program.cs.
That means two things:
A setting only works if the host or feature actually binds it.
Most overrides follow normal .NET configuration rules, including
appsettings.json, environment-specific JSON files, user secrets, command line arguments, and environment variables for server-side hosts.
The Three Main Host Shapes
1. Standalone Elsa Server (AddElsa(...))
AddElsa(...))The sample Elsa.Server.Web host binds these release-backed sections:
Http
HTTP activity base URL, base path, content types, and related HTTP activity options
Identity
configuration-based users, applications, roles, and token settings
Identity:Tokens
signing key and token lifetime settings
Multitenancy
configuration-based tenants
IngressRateLimiting
fixed-window rate limit settings for Elsa APIs and HTTP workflow ingress
Scripting:CSharp
C# expression engine options
Scripting:Python
Python engine options such as DLL path and scripts
DistributedRuntime:AllowLocalLockProviderInDistributedRuntime
development/single-host override for distributed runtime locking
The important constraint is that this host does not use a single Elsa:* root. The sections above are bound explicitly in code.
2. Elsa Studio Hosts
The standalone Studio hosts bind a different set of sections:
Backend
Elsa Server API base URL
Authentication:Provider
selects ElsaIdentity, OpenIdConnect, or ElsaLogin depending on host
Authentication:OpenIdConnect
OIDC authority, client IDs, scopes, and token behavior
Localization
default culture and supported cultures
Shell
server-hosted Studio shell options
DesignerOptions
flowchart designer options such as UseReactFlow
Set Authentication:Provider explicitly. The defaults differ by host:
Elsa.Studio.Host.Serverfalls back toElsaIdentityif the setting is missing.Elsa.Studio.Host.Wasmfalls back toOpenIdConnectif the setting is missing.
3. Modular Elsa Server (CShells)
CShells)Elsa.ModularServer.Web uses shell-based configuration instead of the standalone AddElsa(...) pattern. Its primary sections are:
CShells:Shells:*
per-shell feature enablement and feature settings
Diagnostics:OpenTelemetry:Exporter
OTLP endpoint and protocol
Nuplane
package feeds and autoload behavior
Elsa:PlatformIntegration:ShellOverlayPath
optional JSON overlay file path loaded at startup
In this host, persistence, authentication, HTTP, secrets, and routing settings live under shell feature names such as Identity, FastEndpoints, SqliteWorkflowPersistence, Http, or Secrets.
Configuration Map by App Type
Standalone Elsa Server example
The Elsa.Server.Web sample app ships with settings shaped like this:
Use this shape when you host Elsa directly in your own ASP.NET Core app with builder.Services.AddElsa(...).
Identity signing key rules in 3.8.0
Identity:Tokens:SigningKey is validated in the released server code:
it is required outside the
DevelopmentandDemoenvironmentsit must not contain leading or trailing whitespace
it must use printable ASCII characters only
it must be at least 32 characters long
known sample values such as
CHANGE_ME_TO_A_SECURE_RANDOM_KEYare rejected outside development-oriented environments
Elsa Studio example
The standalone Studio hosts expect settings shaped like this:
For Blazor WebAssembly, these values usually live in wwwroot/appsettings.json. Browser clients do not read server environment variables directly, so production overrides usually happen during build, publish, or host-page generation.
OIDC defaults in 3.8.0 Studio hosts
When Authentication:Provider is OpenIdConnect, the released Studio hosts apply a few defaults that are easy to miss:
if
AuthenticationScopesis empty, Studio restoresopenid,profile, andoffline_accessGetClaimsFromUserInfoEndpointdefaults tofalsethe Blazor Server host defaults callback paths to
/signin-oidcand/signout-callback-oidcwhen you do not set them explicitly
Modular server example
The modular server sample uses shell feature configuration like this:
Use this model when you need multiple shells, per-shell routing, or feature configuration that can vary by shell.
Environment Variables and Overrides
For server-side hosts, normal .NET environment variable mapping applies:
:in configuration paths becomes__keys are case-insensitive on the .NET side
later providers override earlier providers
Examples:
Prefer environment variables, user secrets, or a secret manager for:
signing keys
API keys and client secrets
database credentials
secrets encryption keys
Do not commit production secrets into appsettings.json.
Settings That Must Stay Aligned
Public URLs
If Elsa is exposed behind a reverse proxy or ingress, keep these consistent:
Http:BaseUrlshould reflect the public Elsa Server URL.Backend:Urlin Studio should point to the public Elsa API URL, usually ending in/elsa/api.Reverse proxy rules must preserve the same public API path that Studio uses.
If these drift apart, generated links, callbacks, or Studio API calls can fail even when the application itself starts correctly.
HTTP workflow base path versus Elsa API path
These are separate concerns:
Http:BasePathcontrols whereHttpEndpointactivity routes are mounted.Elsa API endpoints use
ApiEndpointOptions.RoutePrefix, whose default iselsa/api.
In 3.8, HttpActivityOptions.ApiRoutePrefix is obsolete. Do not treat Http:ApiRoutePrefix as the source of truth for Elsa API routing in new host code.
Authentication mode
Studio and Server must agree on the authentication story:
If Studio uses
OpenIdConnect, Elsa Server must trust the same identity provider and scopes.If Studio uses
ElsaIdentityorElsaLogin, Elsa Server must expose the corresponding identity endpoints and configured users or applications.
Migrations and Persistence Toggles
Database connection strings alone do not switch persistence providers. The host must also call the provider-specific Elsa persistence configuration methods.
For EF Core persistence, automatic migrations are controlled on the persistence features through RunMigrations, not through a built-in global Elsa:AutoMigrate setting.
That distinction matters because:
changing only
ConnectionStrings:*does not move Elsa off in-memory storesmigration behavior belongs to the configured persistence feature
different hosts can expose migration toggles differently
See Database Configuration and EF Core Migrations for provider-specific examples.
Common Pitfalls
A config key exists in docs but nothing reads it
Check the host's Program.cs. Elsa settings are often bound explicitly, so an unbound section does nothing.
Studio can load, but API calls fail
Check Backend:Url, the API route prefix, CORS, and auth provider alignment before debugging the workflow engine itself.
WASM settings do not change after updating server environment variables
Blazor WASM reads client configuration from static assets such as wwwroot/appsettings.json. Updating server environment variables alone does not rewrite those files.
Reverse proxy deployments generate wrong absolute links
Set Http:BaseUrl to the public URL seen by clients, not only the internal container or pod address.
Distributed runtime warns about local locking
If you enable the distributed runtime and keep a local-only lock provider, Elsa logs a warning because that setup does not coordinate across nodes. Treat DistributedRuntime:AllowLocalLockProviderInDistributedRuntime=true as a single-host acknowledgement for development or tests, not as a clustering solution.
Related Guides
Last updated