Configuration (Connect 2021)
Content
- 1 Content
- 2 General
- 3 Standard configuration
- 4 Installation-specific configuration
- 5 Environment-specific configuration
- 6 Explicit configuration
- 7 Structure of the configuration file
- 7.1 The “Logging” section (JSON object)
- 7.2 The “IdentityServer” section (JSON object)
- 7.3 The “AllowedHosts” section (JSON value of type String)
- 7.4 The “Connect” section (JSON object)
- 7.5 The “Connect/Server” section (JSON object)
- 7.5.1 The "BaseUri" section (JSON value of type String)
- 7.5.2 The "Debug" section (JSON object)
- 7.5.3 The “Passwords” section (JSON object)
- 7.5.4 The “Paths” section (JSON object)
- 7.5.5 The “Database” section (JSON object)
- 7.5.6 The "SupportedLanguages" section (JSON array with values of type String)
- 7.5.7 The "Webserver" section (JSON object)
- 7.6 Special considerations when configuring the Identity Server
- 7.7 Example configuration
- 8 Overriding configuration settings
General
The Connect Server is usually configured using JSON files, which are located in the installation directory of the application. In special cases, overriding via environment variables or via command line parameters is possible.
Standard configuration
The default configuration is located in the “appsettings.Default.json” file. This file should not be changed directly, because these changes may be overwritten by a later upgrade.
Installation-specific configuration
If an installation-specific configuration is to be created, it is recommended to copy the file "appsettings.Default.json" into a file with the name "appsettings.json". This file will not be overwritten in case of an upgrade, so the configuration settings stored here will remain.
The default configuration is still considered, the installation-specific configuration must therefore only contain the desired deltas.
Environment-specific configuration
If an installation directory is used in different environments (e.g., in a template for containers), environment-specific configurations can be created. For this the file "appsettings.Default.json" is copied into a file with the name "appsettings.{environment}.json" ({environment} has to be replaced by the name of the corresponding environment).
In this scenario, the environment can be specified at runtime using the environment variable "ASPNETCORE_ENVIRONMENT". Usually the values "Development", "Staging" and "Production" are used here, the default value is "Production".
The default configuration and any existing installation-specific configuration are still considered, the environment-specific configurations must therefore only contain the desired deltas.
The use of the "Development" environment should be avoided in production environments, as this activates additional debugging functionalities.
Explicit configuration
If required, additional configuration files can be specified on the command line using the argument "settings=...", "-settings=...", "--settings=..." or "/settings=...". The system checks whether the specified configuration file exists and displays an error message if it is not found. This check can be deactivated by appending a question mark to the file name. This allows optional configuration files to be specified on the command line.
The default configuration as well as the installation-specific configuration and the environment-specific configuration(s) are still considered. In this case, the explicit configurations only have to contain the desired deltas.
Structure of the configuration file
The configuration file for the Connect Server is a JSON file with a JSON object as the root element. The corresponding child elements are described in the following chapters.
The “Logging” section (JSON object)
This section contains another JSON object named "LogLevel", which defines the level of detail of the log outputs. The property "Default" contains the standard setting, other existing properties define different settings for certain .NET namespaces. The following values are supported for the level of detail: "Trace", "Debug", "Information", "Warning" and "Error".
Example:
...
"Logging": {
"LogLevel": {
"Default": "Information",
"IdentityServer4": "Warning",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
...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:
The “IdentityServer” section (JSON object)
This section provides configurations for the Connect Server's built-in Identity Server used for authenticating users. The default configuration is useful for development environments or for closed networks since it does not require any additional adjustments. However, if the Connect Server is to be accessible via the Internet, these settings should be adapted. More information about this can be found at the following link:
Example:
...
"IdentityServer": {
"Key": {
"Type": "Development"
},
"Clients": {
"GalileoGroup.Connect.Server.Frontend": {
"Profile": "IdentityServerSPA"
}
}
},
...The “AllowedHosts” section (JSON value of type String)
This section allows you to restrict the host names to which the web server is bound. Thus, access via unwanted host names or via IP addresses can be prevented. Multiple values can be separated by a semicolon. For more information, see the following link:
Example:
...
"AllowedHosts": "connect.mycompany.com;localhost",
...The “Connect” section (JSON object)
This section summarizes all Connect Framework specific configurations.
The “Connect/Server” section (JSON object)
This section contains all settings related to the integrated server functionalities.
The "BaseUri" section (JSON value of type String)
This value specifies the base URI under which the Connect server can be reached. The URI specified here does not necessarily have to correspond to an endpoint of the web server; it can also be an externally reachable URI that is forwarded by a router to one of the endpoints of the web server.
If this value is set to "auto", the server tries to determine the base URI automatically from the data of the first web server endpoint.
The "Debug" section (JSON object)
This section contains settings for error analysis. The following settings are currently supported:
Property | Type | Function |
EnableHttpRequestLogging | Boolean | Enables logging of all incoming http requests. |
The “Passwords” section (JSON object)
This section has no functionality in the current version of Connect Server. In future versions, the parameters for reversible encryption of the passwords for SSL certificates and connection strings can be defined here, so that they no longer need to be stored in plain text.
The “Paths” section (JSON object)
In this section variables for use in file paths can be defined. Subsequent variables can use previously defined variables. Regardless of the operating system, the "/" character must always be used as directory separator.
The following variables are predefined by the Connect Framework, but can be redefined:
Variable | Default value |
ApplicationPath | The installation directory of the Connect Server. |
CertificatePath | {ApplicationPath}/Certificates |
RepositoryPath | {ApplicationPath}/Repositories |
These defaults are always used if no other variable value is defined or if the variable has been assigned the value “auto”.
For use within a file path, the path variables must be enclosed in curly braces.
The “Database” section (JSON object)
This section contains configuration data for connecting to the databases used by the application. For each database, a child JSON object must be created whose name corresponds to the internal ID of the associated database. The Connect Server uses the following databases:
Database ID | Function |
Identity | Identity Server Users and Permissions |
Monitoring | Database for the collection of monitoring data |
Operations | Database for storing expiration data |
The following information can be stored for each database:
Property | Type | Function |
Type | String | Type of database. Normally "Sqlite" is used here, "SqlServer" is currently supported experimentally. Support for "MySql" is planned, but currently the final implementation of the EF Core Adapter for .NET 5.0 is not yet available. |
ConnectionString | String | The connection string for the database to use. |
LogLevel | String | The desired level of detail for database-specific log output. The values "Trace", "Debug", "Information", "Warning" and "Error" are supported. |
EnableSensitiveDataLogging | Boolean | If this value is set to "true", field contents are also output during logging, otherwise they are always suppressed. |
EnableDetailedErrors | Boolean | If this value is set to "true", detailed error messages from the database are output during logging. |
The “RetentionPeriods” section (JSON object)
For the Operations database, additional retention periods can be defined for workflow contexts. The periods are defined in a separate section "RetentionPeriods" and can contain the following information.
Property | Type | Function |
|---|---|---|
OpenContexts | Number | Retention period for uncompleted transactions in days. |
CompletedContexts | Number | Retention period for completed transactions in days. |
Example:
The "SupportedLanguages" section (JSON array with values of type String)
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 region-specific language keys (such as "en-US", "en-UK", "de-DE" or "de-AT") are supported.
The "Webserver" section (JSON object)
This section is used to configure the integrated web server. The following values can be stored here:
Property | Type | Function |
Type | String | To use the integrated web server, use the value "Kestrel". Since this is the default setting, the value "Kestrel" is also used if this property is missing. On Windows, the value "IIS" can be used to enable hosting within IIS. In this scenario, the endpoints configured here are ignored, as these are defined via the bindings in IIS. You can find more information about hosting in IIS under the following link: |
RootPath | String | Specifies the root directory of the web server. It is recommended not to change this value, as this may cause page effects when hosting the WebAssembly based frontend. |
Endpoints | Array | This array of JSON objects specifies the endpoints of the integrated web server. The property "Uri" 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 into an IP address using DNS lockup. The IP addresses 0.0.0.0 or * represent all available IP addresses of the server. When using HTTPS, the property "CertificateSource" must also be specified, which can have different values. Which value must be specified is defined by where the certificate is located. If the certificate is located in the store, the value must correspond to the requestor. For example, if the requestor of the certificate is "CN = localhost", the value for "CertificateSource" must be "localhost". The direct path to a certificate or its file name can also be specified. If only a file name is specified, this is searched for in the path defined by the "CertificatePath" path variable. For this the value can be e.g. like "test.cer|" or "test.cer|NochEinPassword". Here "test.cer" is the filename of the certificate and "NochEinPassword" is the password to access the private key of the certificate. The separator "|" is mandatory, no matter if a password is entered or not. If there is no password, the value ends with a "|". The use of multiple certificates on the same endpoint is currently not supported. If an endpoint can be reached via different hostnames, these must be listed in a certificate. Wildcard certificates are supported without restrictions. |
Special considerations when configuring the Identity Server
In the default configuration, the Connect Server uses the Identity Server to authenticate and authorize users. There is one configuration variant that differs from the standard:
If a value with the name "AutoCreate" and the value "true" is created within the "Key" section, then, if the referenced certificate file does not exist, a self-signed certificate is generated at startup. This behavior is primarily intended to allow the server to start without manual configuration changes.
Example:
If there is no file with the name "connect.pfx" in the directory specified under "CertificatePath", a self-signed certificate is created at startup and stored using this name. The password "Connect!" specified here is used for the encryption of the private key.
Example configuration
The following example shows the possible Connect-specific configuration settings:
Overriding 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.
Overriding using 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 to the setting in the JSON file. A double underscore (__) should be used as path separator.
You can find more information on this topic at the following link:
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 to the setting using the ":" character as the path separator. Key value pairs can be specified in various ways:
<name1>=<value1> <name2>=<value2> .../<name1> <value1> /<name2> <value2> ...--<name1> <value1> --<name2> <value2> ...
You can find more information on this topic at the following link:
Example: