Web Client Configuration

Information

Here you will find a description of the PLANTA Web Client configuration.

Basics

Information

There are several ways to apply configurations. Below, all options are listed from lowest to highest priority.
If a variable has been defined at more than one position, the position with the highest priority will be used:
1. appsettings.json: Main (default) configuration, changes are not recommended
2. appsettings.[Environment].json: environmental specific (e.g. production) configuration
3. Environment Variables
4. Command line parameter

Define parameters outside the JSON format

Information

You have to use a particular format for conversion variables and command line parameters:

Define parameters within a block

JSON:	Command line:
JS `{ "ConnectionSettings": { "User": "username" } }`	CODE `--ConnectionSettings:User=username`

Define parameters within an array

JSON:	Overwrite ServerB port in the command line:
JS `{ "ConnectionSettings": { "Servers": [ { "Host":"serverA", "Port":1234 }, { "Host":"ServerB", "Port":4567 } ] } }`	CODE `--ConnectionSettings:Servers:1:Port=9999`

Parameter

Information

The following parameters can be used to configure the Web Client.

Dotnet Settings

Information

The ASPNETCORE_ENVIRONMENT can be set to Development this will enable a button on the error screen which allows the copying of the stacktrace.

Connection Settings

Information

Parameters which define the server start and the communication with the PLANTA Server.
They must be defined within the ConnectionSettings block.

Parameter	Type	Default	Description
`CompressionLevel`	int	6	Zlib compression level, number between 0 and 9. Will be ignored if `UseCompression` = “false”.
`CultureCode`	string	de-DE	Culture Code which is used by the application. Depends on the host operating system. A list of culture codes can be found online as well.
`IndividualParameters`	string	null	`individual_parameters`-Parameter which is sent upon server start
`KeepAliveTimeout`	int	60	Time interval between keepalive signals sent to the PLANTA Server in seconds
`RoutingRequestTimeout`	int	5	Request timeout for routing requests to PLANTA link
`RoutingWebHook`	string	null	The PLANTA link webhook which is required for routing
`PanelDestructionDelay`	int	1440	Time in minutes for which the web server saves panel information when the user has interrupted the connection or left the page
`Password`	string	null	`password` parameter which is sent upon server start
`SessionDestructionDelay`	int	7200	Time in minutes for which the web server saves session information when the user has interrupted the connection or left the page
`Servers`	array	null	List of the PLANTA Server must at least contain one entry. Further information
`UseCompression`	bool	true	Defines whether communication with the PLANTA Server is to be compressed
`User`	string	null	`individual_parameters` parameter which is sent upon server start
`UseSSL`	bool	false	Defines whether SSL is to be activated for communication with the PLANTA Server

Settings of the Servers parameter

Parameter	Type	Description	From/Up to Version
`Host`	string	server host name
`Port`	int	server port

AI Settings

Parameter	Type	Description	From/Up to Version
`ChatHost`	string	URL of the AI assistant chat.

The AI assistant is configured in a separate container. See here.

Data Protection Settings

Information

Parameters to control the Data Protection API.
They must be defined within the DataProtectionSettings block.

Parameter	Type	Default	Description
`ApplicationName`	string	PLANTA Webclient	The name of the application for data protection purposes.
`KeysDirectory`	string	%ApplicationFilesPath%/DataProtectionKeys	Directory path where data protection keys are stored.
`EncryptionAlgorithm`	string	AES_256_CBC	The encryption algorithm used for data protection, for possible values see here.
`ValidationAlgorithm`	string	HMACSHA256	The validation algorithm used for data protection, for possible values see here.
`EncryptionCertificateThumbprint`	string		The thumbprint of the encryption certificate used for data protection, if empty the keys file will not be encrypted.

Authentication Settings

Information

Parameters which are used to configure whether and how the reverse proxy informs us about the authenticated user. This requires the use of PLANTA secure.
The parameters must be defined within the AuthenticationSettings block.

Parameter	Type	Default	Description	From/Up to Version
`ProxyAuth`	bool	false	If this option is activated, the Web Client sends a message to the server during session initialization which informs him/her about the pre-authentication and the corresponding user code.
`JwtAuth`	bool	false	When enabled, the Webclient will use JWT/OIDC for authentication (enables OIDC flows). Deprecated from 3.7.2 Use `OidcEnabled` instead.	Up to 3.7.1
`JwtAuthOnClient`	bool	false	When true the client initiates the OIDC login flow by itself; otherwise the OIDC login flow will be initiated by reverse proxy. Deprecated from 3.7.2 Use `OidcEnabled` instead.	Up to 3.7.1
`OidcEnabled`	bool	false	Enables OIDC authentication. Replaces the previous parameters `JwtAuth` and `JwtAuthOnClient`.	From 3.7.2
`ProxyUserFormat`	string	plain	The format in which the value is provided. So far, only the "plain" format has been implemented, which passes the header value to the server.
`ProxyUserHeader`	string	x-forwarded-user	Name of the HTTP header field that contains the user ID authenticated by the reverse proxy.
`ProxyUserAccessToken`	string	x-forwarded-access-token	Name of the HTTP cookie that contains the JWT access token
`ProxyUserIdToken`	string	x-forwarded-id-token	Name of the HTTP cookie that contains the JWT access token
`AppPathBase`	string	/	Web base path that the reverse proxy uses for the Web Client, e.g. if the Web Client can be accessed on the reverse proxy under http://www.example.com/webclient, the base path will be /webclient.
`ProxyLogoutRoute`	string		Logout route which is opened when the user wants to terminate his/her session on the reverse proxy.
`OidcSettings`	OIDC Settings		Configuration for the OpenID connect authentication
`ReverseProxyJwtSettings`	ReverseProxyJwtSettings		Configuration for the JWT authentication via reverse proxy (Cloudflare by default).

ReverseProxyJWT Settings

Parameter	Type	Defaut	Description
`HeaderKey`	string	`Cf-Access-Jwt-Assertion`	HTTP header key that contains the application JWT from the reverse proxy (default: `Cf-Access-Jwt-Assertion`). The authentication service also checks if the header name contains `Cf-` to detect Cloudflare usage. The HTTP header key that contains the application JWT from the reverse proxy. The authentication service also checks whether the header name contains `Cf-` to recognize the use of Cloudflare.
`IssuerUrl`	string		Expected `iss` claim value of the incoming token (e.g. your Cloudflare Access Issuer URL).
`JwksUrl`	string		JWKS end point URL used for validating the token signature.
`Audience`	string		Expected `aud` claim value. In Cloudflare Access, it is usually the 64 digit hex tag.

Notes

When JwtAuth is true and JwtAuthOnClient is false, the client tries to find the tokens made available by the reverse proxy either in cookies (standard OIDC cookies) or in the configured HeaderKey. If HeaderKey contains a Cf prefix and a matching request header exists, the reverse proxy/Cloudflare flow is used. .
After successful validation, the client sends an XML message of the <ProxyToken type="1" .../> type that contains the application token in access_token to the backend. The backend must support type="1" and access_token as validated reverse proxy JWT.

OIDC Settings

Information

Parameter for configuring the OpenID connect authentication.
They must be defined within the AuthenticationSettings.OidcSettings block.

Parameter	Type	Description	From/Up to Version
`ClientId`	string	Oauth client ID that is used for token validation.
`ClientSecret`	string	Client secret that is used for authentication to the OIDC provider.
`DiscoveryUrl`	string	URL for the OIDC discovery document. Deprecated from 3.7.2 Use `IssuerUrl` instead.	Up to 3.7.1
`IssuerUrl`	string	The base issuer URL of the OIDC provider (e.g. `https://login.microsoftonline.com/tenant/v2.0`). Replaces `DiscoveryUrl`. The discovery URL is derived automatically.	From 3.7.2
`Scope`	string	Access area requested by the OIDC provider.

Authentication: Examples and Setup

Information

Below are common configuration scenarios and concrete examples for setting values via appsettings.json, environment variables, or command line.

Example A — Reverse-proxy header authentication (proxy tells backend the user ID)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "ProxyAuth": true,
    "ProxyUserHeader": "x-forwarded-user"
  }
}

Environment variable (Windows PowerShell):

POWERSHELL

$env:AuthenticationSettings__ProxyAuth = "true"
$env:AuthenticationSettings__ProxyUserHeader = "x-forwarded-user"

Example B — Cloudflare Access / Reverse-proxy JWT (reverse proxy injects application JWT)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": false,
    "ReverseProxyJwtSettings": {
      "HeaderKey": "Cf-Access-Jwt-Assertion",
      "IssuerUrl": "https://your-team.cloudflareaccess.com",
      "JwksUrl": "https://your-team.cloudflareaccess.com/cdn-cgi/access/certs",
      "Audience": "PASTE_THE_64_CHAR_HEX_TAG_HERE"
    }
  }
}

Notes

The application will detect Cloudflare usage when the configured HeaderKey contains Cf- and a matching header exists on the request.
Ensure JwksUrl, IssuerUrl and Audience exactly match the token claims issued by Cloudflare Access. If they do not match validation will fail.

Example C — OIDC client-initiated login with PKCE (browser performs OIDC flow)

appsettings.json:

JSON

{
  "AuthenticationSettings": {
    "JwtAuth": true,
    "JwtAuthOnClient": true,
    "OidcSettings": {
      "ClientId": "APPLICATION_CLIENT_ID",
      "ClientSecret": "YOUR_CLIENT_SECRET",
      "DiscoveryUrl": "https://login.example.com/.well-known/openid-configuration",
      "Scope": "openid profile email"
    }
  }
}

Behavior

The client will start the Authorization Code flow with PKCE and exchange the authorization code for id_token/access_token in the browser.
Tokens are validated and then forwarded to the backend with ProxyToken type="0".

WebAPI Authentication Settings

Parameter	Type	Default	Description	From/Up to Version
`APIKey`	string	APIKEY	API key which is used to access the web API end points

Adaptive Card Settings

Signature Settings

Parameter	Type	Default	Description	From/Up to Version
`RsaPrivateKeyXml`	string		XML formatted private RSA key for signing Adaptive Cards

Upload Settings

Information

Parameters that define the behavior in file uiploads.
They must be defined within the FileUploadSettings block.

Parameter	Type	Default	Description
`CompressionLevel`	int	6	Zlib compression level, number between 0 and 9. Will be ignored if `UseCompression` = `false`
`AllowedExtensions`	string	.doc, .docx, .xls, .txt	File endings which can be uploaded
`MaxFileSize`	int	2000000	Maximum size of files in kB
`ChunkSize`	int	100000	If a number > 0 is defined, the file will be uploaded in chunks according to the specified size. If 0 is defined, the file will be iploaded in a request.
`TemporaryFilePath`	string	.	Path under which the files are temporarily saved during upload

Help Center Settings

Information

Parameters to configure the links and commands used in the Help Center menu.
They must be defined within the HelpCenterSettings block.

Parameter	Type	Default	Description
`MainHelpUrl`	string	https://help.planta.de/	URL for the main help center page.
`VideoTutorialsUrl`	string	https://www.youtube.com/@planta_gmbh/videos	URL for video tutorials.
`TextTutorialsUrl`	string	https://help.planta.de/de/project/	URL for text-based tutorials/documentation.
`PrivacyPolicyUrl`	string	https://www.planta.de/datenschutzerklaerung/	URL for the privacy policy page. When set, a privacy policy link will be displayed in the feedback component.
`AiConfigurationUrl`	string	https://help.planta.de/de/tec/Container-ab-39.5.24/konfiguration-des-ki-assistenten-fur-webclient	URL for AI assistant configuration documentation. This link is shown when the AI assistant is disabled to help users learn how to set it up.
`ModuleHelpCommandId`	int?	null	Optional command ID to execute for module-specific help.
`FieldHelpCommandId`	int?	null	Optional command ID to execute for field-specific help.
`MaxFeedbackTextLength`	int	1000	Maximum character length allowed for feedback comment text. This limits how much text users can enter in the feedback form.
`FeedbackTo`	array	null	List of feedback destinations. Each destination has a `Name` and optional `Args`. Supported destinations: `Console`, `Logger`, `File`, and `Service`.

Feedback to Destination Details

Information

Console: Logs feedback to the console.
Logger: Logs feedback using the application's logger.
File: Logs feedback to a file. Requires Args.filepath (path to the file) and Args.encoding (file encoding, e.g., utf-8).
Service: Sends feedback to a service. Requires Args.url (URL of the feedback service).

Example configuration for FeedbackTo:

JSON

"FeedbackTo": [
  { "Name": "Console" },
  { "Name": "Logger" },
  {
    "Name": "File",
    "Args": {
      "filepath": "%ApplicationFilesPath%/feedback.log",
      "encoding": "utf-8"
    }
  },
  {
    "Name": "Service",
    "Args": {
      "url": "http://localhost:5159/api/feedback"
    }
  }
]

Message Dumper Settings

Information

Message Dumper saves the communication with PLANTA Server: one xml file per session.
The parameters must be defined within the MessageDumperSetting block.

Parameter	Type	Default	Description	From/Up to Version
`Enabled`	bool	true	Activate Message Dump feature
`LogDirectory`	string	.\Logs\Dump	Path under which message dump files are saved

Virtualization Settings

Information

Virtualization is used to only render what is visible on screen to improve performance.
Within VirtualizationSettings block.

Parameter	Type	Default	Description
`Enabled`	bool	true	Whether to enable virtualization feature

Chart Export Settings

Information

Parameters to control chart export functionality.
Must be defined within the ChartExportSettings block.

Parameter	Type	Default	Description
`ExportScaleFactor`	int	4	Scale factor for exported chart images. Higher values produce higher resolution images but increase file size.
`MaxUploadsPerMinute`	int	60	Maximum number of chart exports allowed per minute (rate limiting).
`MaxFileSizeBytes`	int	15728640	Maximum file size for exported chart images, in bytes (default is 15 MB).

Example configuration

JSON

{
  "ChartExportSettings": {
    "ExportScaleFactor": 4,
    "MaxUploadsPerMinute": 60,
    "MaxFileSizeBytes": 15728640
  }
}

Page Size Settings

Information

Parameters for configuring custom page sizes for PDF export.
The parameter must be defined within the PaperFormatSettings block.

Parameter	Type	Default	Description	From/Up to Version
`Formats`	Array		List of custom page size configurations. Each format must include a localized name and dimensions in millimeters.

Define parameters within an array

CODE

{
  "PaperFormatSettings": {
    "Formats": [
      {
        "Name": {
          "de": "A0",
          "en": "A0",
          "fr": "A0",
          "pt": "A0"
        },
        "Size": {
          "Width": 841,
          "Height": 1189
        }
      },
      {
        "Name": {
          "de": "Tabloid",
          "en": "Tabloid (11x17 in)",
          "fr": "Tabloïd",
          "pt": "Tablóide"
        },
        "Size": {
          "Width": 279,
          "Height": 432
        }
      }
    ]
  }
}

Logging Settings

Information

The PLANTA Web Client uses Serilog for logging.
Serilog uses so-called "Sinks” for showing logs. The Web Client currently supports the following sinks:
- Console
- File

Metrics Setting

Information

Parameters to configure Prometheus metrics endpoint and telemetry.
Must be defined within the MetricsSettings block.

Parameter	Type	Default	Description
`PrometheusEndpoint`	string	/metrics	The Prometheus endpoint path for metrics scraping. Configure this to change the URL where metrics are exposed.
`MeterName`	string	planta_webclient_metrics	Name of the custom OpenTelemetry meter for application metrics. This identifies the meter in OpenTelemetry.
`MetricsPrefix`	string	planta_webclient_	Prefix to add to custom application metrics names. This helps identify custom metrics from this application in monitoring systems. Note: Default system metrics (ASP.NET Core, Runtime, HTTP Client) do not use this prefix.

Example configuration:

JSON

{
  "MetricsSettings": {
    "PrometheusEndpoint": "/custom-metrics",
    "MeterName": "my_application_metrics",
    "MetricsPrefix": "my_app_"
  }
}

Change Host URL

Information

ASP.Net Core applications use ports 5000 (http) and 5001 (https) by default.
With the Urls parameter it can be overwritten as follows:

JSON:	Commanfd line:
JS `"Urls": "http://localhost:9000;https://localhost:9001",`	CODE `--Urls:http://localhost:9000;https://localhost:9001`