Connect 2024 - User Manual

Configuration (Connect 2024)

The Debug section (JSON object)

This section contains settings for error analysis.

The section HttpLogging (JSON Object)

In this section, logging of incoming and outgoing HTTP traffic can be enabled. Please note that a considerable amount of data can be written to the logs when this is done and that logging has a noticeable impact on the performance of the overall system. The functionality should only be enabled if the target of the logging is a file or the console. The following values can be stored here:

Property

Type

Function

Enabled

Boolean

This option enables or disables logging of incoming from outgoing HTTP traffic. Since this functionality can also be enabled or disabled at runtime via the GUI if required, it is recommended to leave this preset at the value "false".

Include

Array with values of type String

This value contains a list of regular expressions. Only URIs that match one of the regular expressions listed here are included in the logging. If this value is not defined, all URIs are generally included in the logging.

Exclude

Array with values of type String

This value contains a list of regular expressions. Only URIs that do not match one of the regular expressions listed here will be considered for logging. If this value is not defined, no URIs will be excluded from logging.

ForceHexDump

Boolean

If this value is not defined or is set to false, the Connect Server decides, based on the content type, to what extent the content of an HTTP message is displayed as text or as a hexdump. If this value is set to true, the content of HTTP messages is forced to be displayed as a hexdump (regardless of the content).

The EnableBackgroundExceptions section (JSON value of type Boolean).

This value controls the handling of exceptions that occur during background processing. If possible, this option should not be defined or set to the value false. The value true only makes sense during debugging or within unit tests.

Example

The Endpoints section (JSON Array)

This section is used to configure the integrated web server and contains an array with information about the endpoints. The individual elements of the array have the following properties:

Property

Type

Function

Uri

String

This property contains the URI of the desired endpoint. Schema and host are mandatory, the specification of a port is optional. If no port is specified, the respective default ports (80 for HTTP and 443 for HTTPS) are used. If no IP address is specified as the host, the specified name is converted to an IP address using DNS lookup. The IP addresses 0.0.0.0 or * represent all available IP addresses of the server.

Certificate

JSON object

This property was used in previous versions to specify the server certificate when using HTTPS. For more information on the specification of the certificates to use, see below.

This property is only supported for compatibility reasons. Please use the ServerCertificates property to specify the server certificate, which also supports the use of multiple server certificates.

ClientCertificates

JSON object

This property is only taken into account when using HTTPS and allows authentication at connection level using client certificates (mutual TLS authentication / mTLS). A detailed description can be found in a separate section below.

ServerCertificates

JSON object

This property is only required when using HTTPS and is used to specify the server certificates to use. A detailed description can be found in a separate section below.

HttpProtocols

JSON array

This property specifies the HTTP protocols supported by the endpoint. The following values (as strings) are allowed here:

http1
Support for HTTP/1.

http2
Support for HTTP/2.

If this property is not specified, HTTP/1 and HTTP/2 are supported. Support for HTTP/3 is not yet stable in the current version of the .NET Framework, so it is not offered at the moment.

SslProtocols

JSON array

This property specifies the SSL protocols supported by the endpoint when using HTTPS. The following values (as strings) are allowed here:

tls1.0
Support for TLS 1.0.

tls1.1
Support for TLS 1.1.

tls1.2
Support for TLS 1.2.

tls1.3
Support for TLS 1.3.

If this property is not specified, TLS 1.2 and TLS 1.3 are supported. Support for TLS 1.0 and TLS 1.1 is provided for compatibility reasons, but these deprecated protocols are no longer considered secure.

HandshakeTimeout

Integer

This property defines the maximum duration of the SSL handshake in seconds before it is aborted with a timeout on the server side.

The ClientCertificates section (JSON Object)

This configuration section defines the handling of client certificates. If no client certificates are to be used, the entire section can be omitted. Currently, the following properties are supported:

Property

Type

Function

Mode

String

Defines the behavior when establishing a connection. The value "allowed" allows client certificates but does not explicitly request them from the other side, the value "required" explicitly requests a client certificate from the other side.

Authentication

JSON object

Defines the authentication behavior at the application level (not at the connection level). This object has only one property of type boolean with the name "Enabled". If this is set to true, the name in the certificate (subject name) automatically specifies the current user. Provided that the certificate has been successfully validated, no further input of a user name or password is required for logging in. If the client certificates come from a public certification authority, the subject name should also be checked in addition to the general validity check (via SubjectRegex) in order to block foreign client certificates at the connection level.

Validation

JSON object

This property defines the validation behavior for client certificates. It should be noted here that the validation functions of the underlying operating system are only extended by these settings. Validation is therefore initially performed by the operating system on the basis of the certificates stored there. If this validation is not successful, additional certificates can be included in the validation. Filter settings can be used to exclude certificates that are actually valid. Furthermore, an explicit check of the revocation lists can be performed, which is usually not carried out by the operating system for performance reasons. The following properties can be configured here:

CheckRevokation
A boolean value that specifies whether to check the revocation lists to reject revoked certificates.

Filters → SubjectRegex
A regular expression that can be used to define additional filtering by Subject Name.

IntermediateCertificates
An array of certificates from intermediate certificate authorities which are included in the validation if the validation by the operating system was not successful. This allows intermediate certificate authorities to be included without having to store them in the certificate store of the operating system. More information on the specification of the certificates to be used can be found below.

TrustedClientCertificates
An array of client certificates which are considered valid without further checks. More information about the specification of the certificates to be used can be found below.

TrustedRootCertificates
An array with certificates from root certification authorities which are included in the validation if the validation by the operating system was not successful. This allows root certificate authorities to be included without having to store them in the certificate store of the operating system. More information on the specification of the certificates to be used can be found below.

The ServerCertificates section (JSON Object)

This configuration section currently contains only one property named “Bindings”. This JSON array contains the certificate bindings for the endpoint in the form of JSON objects with the following properties:

Property

Type

Function

Conditions

JSON object

This property defines the preconditions for using the associated server certificate. The following specifications are supported here:

Host
The hostname used in the request.

LocalNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the target address of the request, the condition is fulfilled.

RemoteNetwork
An IP address or a network (CIDR address) can be specified here. If this network contains the source address of the request, the condition is fulfilled.

The specification of preconditions is optional. Preconditions can consist of any subset of the supported constraints. Preconditions with multiple constraints are fulfilled if all specified constraints apply.

Certificate

JSON object

This property specifies the server certificate that will be assigned to the endpoint if the preconditions defined in “Conditions” apply. For more information on the specification of the certificates to be used, see below.

The certificate bindings are processed in the sequence defined by their array positions. The first element whose preconditions specified under "Conditions" are met or for which no preconditions have been specified will define the server certificate. Additional elements are not taken into account during processing.

It is recommended to specify a certificate without preconditions as the last element. This is then used as a fallback value.

Use of certificates

Wherever certificates can be specified, a JSON object is expected. This object supports the following properties:

Property

Type

Function

Source

String

Specifies the location of the certificate. The following values are supported:

File
The certificate is available as a file.

UserStore
The certificate is located in the user-specific certificate store.

SystemStore
The certificate is located in the system-specific certificate store.

Store
The certificate is stored in a certificate store and Connect tries to determine it based on the other data. The user-specific certificate store is searched first. If this search does not produce any results, the search continues in the system-specific certificate store.

Path

String

For source "File" only: The path to the certificate file or the path to the directory containing the certificate file.

Name

String

For source "File" only: If the "Path" property contains the directory that contains the certificate file, the file name of the certificate file must be specified here. Otherwise, this property can be omitted.

Password

String

For source "File" only: The password for the private key contained in the certificate file.

FriedlyName oder DisplayName

String

Selection criterion for the certificate store: The display name (friendly name) of the certificate to be used.

SerialNumber oder SerialNo oder Serial

String

Selection criterion for the certificate store: The serial number of the certificate to be used.

IssuerName oder Issuer

String

Selection criterion for the certificate store: The issuer of the certificate to be used.

IssuerDistinguishedName

String

Selection criterion for the certificate store: The issuer of the certificate to be used as Distinguished Name (CN=...)

SubjectName oder Subject

String

Selection criterion for the certificate store: The subject of the certificate to be used.

SubjectDistinguishedName

String

Selection criterion for the certificate store: The subject of the certificate to be used as Distinguished Name (CN=...)

Thumbprint

String

Selection criterion for the certificate store: The fingerprint (thumbprint) of the certificate to be used.

The selection criteria are only evaluated if the certificate is to be read from a certificate store. Not all possible selection criteria need to be specified, but the certificate search must lead to a unique result. If several certificates fulfill all specified selection criteria and only one of them is valid, the valid certificate is used. If several valid certificates fulfill all specified selection criteria, the web server cannot be started.

Example

The "Frontend" section (JSON object)

The SupportedLanguages section (JSON array with string type values).

This section defines the languages that can be selected in the dialog for maintaining language-dependent texts. Both generic language keys (such as "en" or "de") and area-specific language keys (such as "en-US", "en-UK", "de-DE" or "de-AT") are supported.

Example

The Logging section (JSON object)

This section contains another JSON object called "LogLevel" which defines the level of detail of the log output. The property "Default" contains the default setting, other properties may define different settings for specific .NET namespaces. The following values are supported for the level of detail: "Trace", "Debug", "Information", "Warning" and "Error".

Example

If required, the level of detail can be specified depending on the logging target (console, event log, etc.). Further information can be found under the following link:

https://docs.microsoft.com/en-us/dotnet/core/extensions/logging

The Security section (JSON object)

The IpFiltering section (JSON object)

In this section, access to the Connect Server can be restricted to specific IP addresses. The following values can be stored here:

Property

Type

Function

Enabled

Boolean

This option enables or disables filtering by IP addresses.

Blacklist

Array with values of type String

This value contains a list of IP addresses or networks (CIDR addresses) that should be excluded from accessing the web server. If the blacklist is empty or not specified, only the whitelist is considered.

Whitelist

Array with values of type String

This value contains an explicit listing of the IP addresses or networks (CIDR addresses) that are allowed to access the web server (if they are not included in the blacklist). If the whitelist is empty or not specified, only the blacklist is considered (if available).

The JsonEncryption section (JSON object)

To avoid important informations (e.g. passwords) in plain text, they can be encrypted before being stored in files or in the database. The exact behavior is defined by the following properties:

Property

Type

Function

Enabled

Boolean

This option enables or disables partial encryption for objects stored as JSON. If this option is not specified, encryption of important informations (e.g. passwords) is disabled.

Key

String

This value is included in the generation of the key so that only passwords can be decrypted only from Connect Servers where the same value is stored. If this value is not defined or empty, a default key stored in the application is used. Please note that after changing this key, all encrypted informations must be re-entered.

Additional sections

Additional sections are supported for special scenarios The following table lists these sections along with a linke to the corresponding documentation.

Section

Documentation

Identity.AzureAd

Notes for authentication using Azure Active Directory (Connect 2022)

Example

The Workspace section (JSON object)

This section contains configuration data for the connection to a specific data store (workspace). The following values can be stored here:

Property

Type

Function

Id

String

Contains a unique ID to identify the workspace.

DataSource

JSON object

Contains the information for connecting to the database with users, runtime information and, depending on the configuration, the Connect objects. This object supports the following properties:

Name
Contains the ID of the workspace. This value does not normally need to be specified and is automatically pre-populated.

DbType
Defines the type of database used. Currently the values "SqLite", "SqlServer", “PostgreSql” and "MySql" are supported here.

ConnectionString
The connection string used to connect to the database. When using SQLite, this property can be omitted.

RetentionPeriods
This JSON object defines the retention times for specific data types. It contains the following attributes:

OpenContexts
Retention period for uncompleted transactions in days.

CompletedContexts
Retention period for completed transactions in days.

ConnectObjects

JSON object

Defines the behavior when accessing Connect objects. This object supports the following properties:

Provider
Defines the provider used for accessing Connect objects. The values "Database" (storage in the database) and "FileSystem" (storage in the file system) are supported here.

RootPath
If the "FileSystem" provider is used, the root directory for storing the connect objects must be defined here. If an SQLite database is used without specifying a connection string, this path also defines the directory in which the database files are stored.

DbLogging

JSON object

Additional options for logging database access can be defined here. This object supports the following properties:

LogLevel
The desired level of detail for database-specific log output. The values "Trace", "Debug", "Information", "Warning" and "Error" are supported. If this property is not specified, the default value "Error" is used.

EnableSensitiveDataLogging
If this value is set to "true", field contents are also output during logging, otherwise they are always suppressed.

EnableDetailedErrors
If this value is set to "true", detailed error messages from the database are output during logging.

Example

Example configuration

The following example shows the possible Connect-specific configuration settings:

Override configuration settings

The configuration settings stored in the JSON files can be overridden if necessary. This approach makes sense especially when automating Docker-based environments.

Override with the help of environment variables

To override the value of a configuration setting an environment variable can be defined with the prefix "DOTNET_" or "ASPNETCORE_" followed by the path of the setting in the JSON file. A double underscore (__) should be used as path separator here.

You can find more information on this topic at the following link:

https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-5.0

Example:

Override via the command line

If required, configurations can also be overridden using key-value pairs as command line parameters. The name here corresponds to the path of the setting, using the ":" character as the path separator. Key-value pairs can be specified as follows:

<name1>=<value1> <name2>=<value2> ...

Example: