Configuration¶

Stegflow is configured through environment variables. Every setting has a safe default, so a container runs with no configuration at all.

All variables use the STEGFLOW_ prefix. Nested settings are separated by a double underscore (__), and array entries use a numeric index. Names are case-insensitive; they are shown here in uppercase, the usual convention for environment variables.

Booleans are true / false, durations use the hh:mm:ss format (for example 00:00:30), and provider names are case-insensitive.

Hosting and ports

The listening port, HTTPS and related host settings are handled by the ASP.NET runtime, not by Stegflow. They use the standard ASPNETCORE_ prefix, for example ASPNETCORE_HTTP_PORTS=8080. The container listens on port 8080 (HTTP) by default.

Engine¶

STEGFLOW_ENGINE__STRICTAWSMODE: Enforce strict AWS States Language compatibility. Default: false.
STEGFLOW_ENGINE__ADMINEMAILS__0, __1, ...: Email addresses of the global administrators. Default: none.
STEGFLOW_ENGINE__DEFAULTTIMEZONE: Time zone used to display dates when a user has no explicit or provider value. Default: UTC.
STEGFLOW_ENGINE__MAXTENANTSALLOWED: Per-user quota: how many tenants a user may own. A per-user override set by a global administrator takes precedence over this global default. 0 means the user may create none. Default: 2.
STEGFLOW_ENGINE__ALLOWTENANTCREATIONFORALLUSERS: Who may create tenants at all. true: any authenticated user. false: only global administrators (STEGFLOW_ENGINE__ADMINEMAILS). Default: true.
STEGFLOW_ENGINE__ALLOWPRIVATENETWORKHTTPTARGETS: Allow HTTP tasks to reach private, loopback and link-local addresses. Off by default to prevent SSRF. Default: false.
STEGFLOW_ENGINE__EXECUTIONRETENTIONDAYS: Days a terminated execution is kept before the cleanup worker purges it and its events. 0 or less disables cleanup. Default: 90.

How the two tenant-creation settings combine

Creating a tenant passes two independent checks. First permission: STEGFLOW_ENGINE__ALLOWTENANTCREATIONFORALLUSERS decides who may attempt it (everyone, or only global administrators). Second quota: the user's effective STEGFLOW_ENGINE__MAXTENANTSALLOWED (their per-user override, otherwise the global default) must be above the number of tenants they already own. The quota applies to everyone, administrators included, so a global default of 0 blocks creation for anyone without a per-user override, even when permission is granted.

Database¶

Set both variables below to persist data. A fully durable deployment also needs Valkey (see below).

STEGFLOW_ENGINE__DATABASE__PROVIDER: Storage provider. One of Sqlite or PostgreSql. Default: none (in-memory).
STEGFLOW_ENGINE__DATABASE__CONNECTIONSTRING: Connection string for the selected provider. For SQLite, point it at a file on a mounted, writable volume (for example Data Source=/data/stegflow.db). Default: none.

Valkey¶

STEGFLOW_ENGINE__VALKEY__CONNECTIONSTRING: Valkey/Redis connection string. When empty, async tasks stay in memory and are lost on restart. Default: (empty).

Authorization cache¶

STEGFLOW_ENGINE__AUTHORIZATIONCACHE__ENABLED: Enable the authorization decision cache. Default: true.
STEGFLOW_ENGINE__AUTHORIZATIONCACHE__TTL: How long a decision is trusted. Keep it short. Default: 00:00:30.
STEGFLOW_ENGINE__AUTHORIZATIONCACHE__MAXENTRIES: Hard cap on cached decisions. Least-recently-used entries are evicted past this limit. Default: 50000.

Metrics (Prometheus)¶

Controls access to the /metrics endpoint.

STEGFLOW_METRICS__BEARERTOKEN: Token a scraper must present as Authorization: Bearer <token>. Default: (empty).
STEGFLOW_METRICS__ALLOWEDNETWORKS__0, __1, ...: Source networks (CIDR) allowed to scrape without a token. Default: none.
STEGFLOW_METRICS__ALLOWANONYMOUS: Serve /metrics with no token and no source check. Default: false.

/metrics is closed by default

With the defaults, /metrics returns 401. To enable scraping, set a BearerToken, or list trusted AllowedNetworks, or set AllowAnonymous to true on a network you already isolate.

Tracing (OpenTelemetry)¶

Distributed tracing is off by default. Unlike metrics, it needs an external OTLP collector, so it is wired up only when explicitly enabled.

STEGFLOW_TRACING__ENABLED: Capture and export traces for ASP.NET Core, outgoing HTTP, Entity Framework Core and the engine's own spans. Default: false.
STEGFLOW_TRACING__OTLPENDPOINT: OTLP collector endpoint, for example http://collector:4317. Default: (empty).
STEGFLOW_TRACING__SERVICENAME: Service name reported on the OpenTelemetry resource, for both traces and metrics. Default: Stegflow.

Single-user auth¶

When no OIDC authority is configured, Stegflow runs in single-user mode: every request is authenticated as one fixed identity (admin@stegflow.local by default). If no administrator is configured either, that identity is promoted to global administrator on startup, with a loud warning in the logs, so a fresh container is usable with no setup. Setting OIDC or STEGFLOW_ENGINE__ADMINEMAILS turns the auto-promotion off. This mode has no real authentication and must never be exposed to untrusted networks.

STEGFLOW_SINGLEUSERAUTH__EMAIL: Email that identifies the signed-in user. Default: admin@stegflow.local.
STEGFLOW_SINGLEUSERAUTH__NAME: Display name of the signed-in user. Default: Default Administrator.
STEGFLOW_SINGLEUSERAUTH__SUB: Subject identifier of the signed-in user. Falls back to the email when unset. Default: admin@stegflow.local.

Testing access control. Set a real administrator with STEGFLOW_ENGINE__ADMINEMAILS__0 so the single-user identity is not auto-promoted, then point STEGFLOW_SINGLEUSERAUTH__EMAIL at a non-admin user. Change that email to sign in as different users and check what each one is allowed to do, without setting up an identity provider.

OpenID Connect (OIDC)¶

Single sign-on against an external identity provider. The client authenticates with a shared secret, or with a signed assertion when a certificate is set.

STEGFLOW_OIDC__AUTHORITY: Issuer/authority URL of the provider. Default: (empty).
STEGFLOW_OIDC__CLIENTID: Client identifier. Default: (empty).
STEGFLOW_OIDC__CLIENTSECRET: Client secret. Leave empty when using a certificate. Default: (empty).
STEGFLOW_OIDC__REQUIREHTTPSMETADATA: Require the discovery and JWKS endpoints over HTTPS. Set to false only for local development. Default: true.
STEGFLOW_OIDC__CERTIFICATE__PATH: Path to a PFX/PKCS#12 or PEM file with the certificate and private key, for private_key_jwt. Default: (empty).
STEGFLOW_OIDC__CERTIFICATE__PASSWORD: Password protecting the PFX file. Ignored for PEM. Default: (empty).

Claim mapping¶

Maps the claims returned by the identity provider onto user attributes.

STEGFLOW_OIDC__CLAIMS__NAME: Claim holding the display name. Default: name.
STEGFLOW_OIDC__CLAIMS__EMAIL: Claim holding the email address. Default: email.
STEGFLOW_OIDC__CLAIMS__TIMEZONE: Claim holding the time zone. Default: timezone.
STEGFLOW_OIDC__CLAIMS__AVATARURL: Claim holding the avatar URL. Default: picture.
STEGFLOW_OIDC__CLAIMS__DEBUGCLAIMS: Log the received claims to help diagnose mapping issues. Default: false.

Example¶

PostgreSQL, Valkey for durable async tasks, OIDC sign-on, and one global admin:

docker run -p 8080:8080 \
  -e STEGFLOW_ENGINE__ADMINEMAILS__0="admin@example.com" \
  -e STEGFLOW_ENGINE__DATABASE__PROVIDER=PostgreSql \
  -e STEGFLOW_ENGINE__DATABASE__CONNECTIONSTRING="Host=db;Database=sf;Username=sf;Password=secret" \
  -e STEGFLOW_ENGINE__VALKEY__CONNECTIONSTRING="valkey:6379" \
  -e STEGFLOW_OIDC__AUTHORITY="https://id.example.com/realms/stegflow" \
  -e STEGFLOW_OIDC__CLIENTID="stegflow" \
  -e STEGFLOW_OIDC__CLIENTSECRET="..." \
  stegflow/stegflow:beta

Configuration file (JSON)¶

Instead of environment variables, the same settings can be supplied as a JSON file mounted at /app/appsettings.Production.json. Use the section names (the "setting" column) as nested keys. An environment variable always overrides the same key from the file.

{
  "Engine": {
    "AdminEmails": [ "admin@example.com" ],
    "Database": {
      "Provider": "PostgreSql",
      "ConnectionString": "Host=db;Database=sf;Username=sf;Password=secret"
    },
    "Valkey": { "ConnectionString": "valkey:6379" }
  },
  "Oidc": {
    "Authority": "https://id.example.com/realms/stegflow",
    "ClientId": "stegflow",
    "ClientSecret": "..."
  }
}