Configuration

Local installation

Setting the application behavior by editing parameters in the configuration file.

Sample layout of the appsettings.json file :

{
"Logging": {
"LogLevel": {
"Default": "Information",
"System": "Warning",
"Microsoft": "Warning"
},
"Console": {
"FormatterName": "simple"
},
"ApplicationInsights": {
"LogLevel": {
"Default": "Information",
"System": "Error",
"Microsoft": "Error"
}
}
},
"DebugIndicators": "App,Detail,Logic",
"ApplicationInsights": {
"InstrumentationKey": null
},
"ConnectionStrings": {
"DbDataContextConnectionString": "Server=.;Database=FrontStage;Trusted_Connection=True;"
},
"DatabaseType": "MsSql",
"Kestrel": {
"Endpoints": {
"Web": {
"Url": "https://localhost:5001"
}
},
"EndpointDefaults": {
"Protocols": "Http1AndHttp2"
},
"Certificates": {
"Default": {
"Path": null,
"Password": null
}
}
},
"AllowedHosts": "\*",
"CookieName": "FrontStage.ReactClient.Cookies",
"CertificateFromDb2Path": null,
"AuthConfiguration": {
"FacebookClientID": "",
"FacebookClientSecret": "",
"GoogleClientID": "",
"GoogleClientSecret": "",
"MicrosoftClientID": "0cbc44c1-62e6-4809-a519-1bb36ceXXXXX",
"MicrosoftClientSecret": "XXXXXXXXXXXXXXXXXXXX"
},
"TeamsConfiguration": { //Teams local
"Instance": "https://login.microsoftonline.com/",
"TenantId": "",
"AadAppId": "",
"AppSecret": "",
"ApplicationIdURI": "",
"AuthUrl": "/oauth2/v2.0/token",
"ValidIssuers": ""
},
"PbxProxyParameters": null,
"LocalServerName": "localhost",
"ImportFolder": "/tmp",
"CsrfNonce": "k*5V",
"CsrfTokenExpiration": 1440,
"RestrictXhrGet": true
}

Part of the configuration can be split into another file appsettings.ENVIRONMENT.json. Where ENVIRONMENT is the name of the environment, which can be specified using an environment variable named DOTNET_ENVIRONMENT. It is used during development and testing.

Logging section

It contains the default settings (subsection Logging:Loglevel) and then a subsection for individual providers (where the LogLevel structure is repeated). The providers Logging:Console, Logging:Debug, Logging:EventSource, Logging:ApplicationInsights and, when deployed on Windows, Logging:EventLog are also considered.
Logging in detail

Loglevel structure

In a subsection, there’s usually stated a Default loglevel, which is then common for all the levels, that are not mentioned explicitelly. Specific loglevels can be then stated as standalone parameter. Loglevels are commonly set as FQDN C# classes. Possible degrees: Trace, Debug, Information, Warning, Error, Critical and None.

Console provider

The most common provider, which content can be seen in a running application window, if the console is triggered (also in Kubernetes log). The output format can be set via Logging:Console:FormatterName parameter, possible values are simple, systemd and json.
Formatting in detail

Debug provider

It is possible to use it on Windows (can be watched with a help of DbgView) or Linux, where the output is inserted to /var/log/syslog or /var/log/message folder.

ApplicationInsights section.

It has only one parameter ApplicationInsights:InstrumentationKey in .NET Core 6.0, which specifies the key to the ApplicationInsights repository.
AppInsights Configuration Details

ConnectionStrings section and DatabaseType parameter

In the ConnectionStrings section, there is a single parameter named ConnectionStrings:DbDataContextConnectionString that contains the connection string to the database. For more info see Connectionstring.
The DatabaseType parameter specifies whether it is an MS SQL database (value MsSql) or PostgreSQL (value PgSql). This parameter controls the format of the connection string.
Connection strings for MS SQL
Connection Strings for PostreSQL

Kestrel section

The web server allows detailed setting of its parameters in many subsections.
Kestrel server details
Deployment is possible directly to the Internet (then SSL settings are used), or behind a reverse proxy.
Explaining the use of a reverse proxy

Endpoints section

Specifies which IP addresses and ports the web application should listen to. The section contains named objects. In the example, there is one section named “Web” - Kestrel:Endpoints:Web.

Parameter Kestrel:Endpoints:Web:Url - the pseudo URL is given, the scheme is used to know whether it is http or https, the server address is either localhost (then the server listens only to 127.0.0.1 and [::1], or \ then the server listens to any IPv4 and IPv6 (IPv6 always only if configured), the port can be given after the colon. Another option is to specify specific numeric IPv4 or IPv6 addresses for the server to use.
Endpoint specification details

Certificates section

Specifies the certificates to be used for SSL (if the application is exposed directly to the Internet). The section contains named objects, the default certificate must be named “Default” - Kestrel:Endpoints:Web:Certificates.
Details to indicate the source of the certificate
If the certificate is read from a PFX file, the parameters Kestrel:Certificates:Default:Path and Kestrel:Certificates:Default:Password need to be specified.
Certificate configuration
If the certificate is stored in the OS storage, then Kestrel:Certificates:Default:Subject, Kestrel:Certificates:Default:Store, and Kestrel:Certificates:Default:Location need to be specified
Details for referencing a certificate from the repository

EndpointDefaults section

Parameter Kestrel:EndpointDefaults:Web:Protocols - allows to specify whether only Http1 or Http1AndHttp2 is used for SSL
Details of the special options section

Limits

The Kesterel.Limits.MaxConcurrentConnections parameter specifies the maximum number of HTTP basic connections.
The Kesterel.Limits.MaxConcurrentUpgradedConnections parameter specifies the maximum number of HTTP connections converted to WebSocket.
The Kesterel.Limits.MaxRequestBody parameter specifies the maximum HTTP request size in bytes, the default value is 30000000 bytes.
Details on the limits section

AllowedHosts parameter

Paramert is related to the reverse proxy - More details

CookieName parameter

A cookie with this name is used to temporarily store the authentication token. Two web applications running on the same domain (the part before the slash) cannot use the same named cookie because they would overwrite each other and force users to keep logging in repeatedly.

CertificateFromDb2Path parameter

The SSL certificate can be persisted in the database in the Ssl.ReactAdmin key in the Configuration table as a base64 string. If the CertificateFromDb2Path parameter is filled in, the certificate is retrieved from the database and stored in this path when the web application starts. The path should be the same as the path specified in Kestrel:Certificates:Default:Path. The mechanism is particularly relevant for containerized deployments.

AuthConfiguration section

It contains pairs of data for configuring the external Open ID Connect authentication authority - one parameter with the ID ending and one with the Secret ending. If the data pair is left blank (“” or null), the authority is not offered in the login prompt.

Supported authorities:

  • Microsoft - AuthConfiguration:MicrosoftClientID and AuthConfiguration:MicrosoftClientSecret

  • Google - AuthConfiguration:GoogleClientID and AuthConfiguration:GoogleClientSecret

  • Facebook - AuthConfiguration:FacebookClientID and AuthConfiguration:FacebookClientSecret

TeamsConfiguration section

The section allows you to enter the data needed for authentication when running within the MS Teams application:
TeamsConfiguration:Instance
TeamsConfiguration:TenantId
TeamsConfiguration:AadAppId
TeamsConfiguration:AppSecret
TeamsConfiguration:ApplicationIdURI
TeamsConfiguration:AuthUrl
TeamsConfiguration:ValidIssuers

PbxProxyParameters parameter

PbxProxyParameters is an alternative specification of the pbxstring to connect to the ProServer (it is the Cti.Proxy connector). The duplicate entry can be entered in the Device table for the device type (DeviceType) “PbxProxy”. The parameter in the configuration file is typically used in containerized deployments. The string has four parts - the first is the IP address or DNS name of the ProServer (ProService or ProRelay service), the second is the IP port, the negative number indicates the use of the MsgPack transport, the third is the connection control timeout in milliseconds, the last parameter is the password.
Example: proserver,-18321,30000,TESTPWD

LocalServerName parameter

LocalServerName is a parameter that allows you to specify a DNS name for macro expansion in script nodes such as QueryUrlJson and other places. Typically, it specifies the DNS name of the ReactClient server as seen by these services. The parameter in the configuration file is typically used in containerized deployments.

ImportFolder parameter

ImportFolder specifies the path to the folder where the application should store the temporary imported files for processing by ServiceBulk and other services or the location from where ReactClient should retrieve the processed results when exporting. The folder must be shared (visible) by all services (SB, SA, SS).

CsrfNonce parameter

CsrfNonce specifies the secret key added to the encryption of CSRF tokens used by the ReactClient website. If the parameter is empty (“” or null), the CSRF mechanism is disabled. CSRF Details

CsrfTokenExpiration parameter

CsrfTokenExpiration specifies the validity period of the CSRF token in minutes.

RestrictXhrGet parameter

RestrictXhrGet is a boolean parameter (true/false) that enables the control of XHR GET operations to come from pages with the same domain as the XHR operation domain. If this is not the case, the browser will equip the HTTP request with the X-Requested-With header, which indicates the domain, and the site from where the XHR was initiated. The application rejects such requests. This is an additional security measure to CSRF and CORS.

RateLimiter section

Parameters:

The Enabled parameter set to true enables the Rate Limiter.

Note

Setting a Rate Limiter means that when the set limits are exceeded, the agent is limited by IP address to query APIs and other resources from the server until the set time elapses and usage resumes (partially/completely). For more see the official developer text - does not protect against DDOS if the attacker is able to attack from many IP addresses. The bigger risk is for instances that can be seen from the Internet - there it is recommended to do limiting already on proxy, load-balancer, server.

IncludeLoopback disables the function for localhost, do not enable it in production deployment, this is essential for developers if they are testing extensively to avoid hitting limits during internal testing. Bucket:TokenLimit sets the request usage per client (the number of requests it can draw without slowing down) Bucket:QueueProcessingOrder allows options:

  • NewestFirst: requests that are the newest in the queue will be processed - preferable because the client can navigate to another page and old requests are dropped

  • OldestFirst: requests will be processed in the order in which they were submitted (the probability that an outdated request will be processed is higher)

Bucket:QueueLimit is a global limit for ALL requests on the server, the setting should take into account the maximum possible number of agents/users. For example, if the expected number of users is 100 and we assume that no more than 50% of the agents will ever be online, we set it to \(TokenLimit*(100*0.5)\) or if we are not sure about the production data, we set it rather higher. The Bucket:TokensPerPeriod sets the amount (number) of times the server request limit is refreshed (equal to or less than the Bucket:TokenLimit) Bucket:ReplenishmentPeriod is the time after which the server request limit is refreshed Bucket:AutoReplenishment sets the refresh: if true refresh will occur periodically for the set time. The value false is not supported, the refresh would have to occur manually.

appsettings.json example:

"RateLimiter": {
"Enabled": false,
"IncludeLoopback": true,
"Bucket": {
"TokenLimit": 50,
"QueueProcessingOrder": "OldestFirst",
"QueueLimit": 500,
"ReplenishmentPeriod": "00:00:15",
"TokensPerPeriod": 30,
"AutoReplenishment": true
}
}

Portal setup example:

  • The average number of queries to load one page is 32, most of them are cached, so 3-4 queries after the first loading of the portal (can be found in the tab “Network” in Chrome devtools - key F12)

  • In order to load 10 pages in the given time limit, the agent needs a \(32+4*9=68\) ( TokenLimit = 68).

  • If there are 500 agents, it is reasonable not to set QueueLimit to less than half of \(AgentCount*TokenLimit\) –> \(68*500/2=17000\) .

  • The ReplenishmentPeriod is the time limit for how long we expect the agent to deplete the limit. For example, an agent on average visits 10 pages in 5 minutes –> ReplenishmentPeriod = “00:04:30” (it is better to give some reserve so that harmless use of the service is not blocked).

  • The TokensPerPeriod can be set to \(3/4*TokenLimit\), this is the number of tokens that will be replenished after the ReplenishmentPeriod.