Configuration

The system is configured by changing configuration files in the file system and/or during installation, using a shared parameters file for the installation script.

Each service has its own set of configuration files, and the web client reads its configuration from a config file in the web-site.

The main entries in the configuration files are being automatically populated from installation parameters through the installation script, but you may tweak the installation by editing the files yourself.

You may also need to change the configuration files manually if your environment is changing, i.e. server names.

Settings that are omitted from the configuration files are inheriting the default value if available as described below.

The following configuration file examples origins from our cloud deployment and pictures a setup with:

  • An SSL star-certificate for *.plassdata.net
  • All services deployed to the same server
  • Database service is Microsoft SQL Express running an ‘SQLEXPRESS’ instance
  • Main hostname: https://dvi6test.plassdata.net
  • Host is Windows Server 2016 with default settings, using drive C: for everything

Angular Client

appconfig.json

Example C:\inetpub\dvi6root\clients\apps\kmd-dvi\assets\config\appconfig.json:

{
  "apiServer": {
    "baseUrl": "https://api-dvi6test.plassdata.net",
    "jwtWhitelistedDomains": "api-dvi6test.plassdata.net;dvi6test.plassdata.net"
  },
  "idsServer": {
    "baseUrl": "https://ids-dvi6test.plassdata.net"
  },
  "auth": {
    "clearHashAfterLogin": "false",
    "requireHttps": "true",
    "sessionChecksEnabled": "true",
    "showDebugInformation": "false",
    "silentRefreshTimeout": "5000",
    "strictDiscoveryDocumentValidation": "true",
    "timeoutFactor": "0.25",
  }
  "env": {
    "name": "Prod"
  },
  "skin": {...},
  "customMenuItems": [...],
  "isConfig": "true"
}
Option Default Usage
“apiServer”: {
“baseUrl”: “URL
}
[must be specified] Endpoint-URL of the API server. Keep in sync with *1
“apiServer”: {
“jwtWhitelistedDomains”: “list-of-domain;domain;domain…
}
[must be specified] Domain-names of accepted token origins. Typically the domain part of the API endpoint and the Angular client file endpoint
“idsServer”: {
“baseUrl”: “URL
}
[must be specified] Endpoint-URL of the Identity server. Keep in sync with *2
“auth”: optional section This whole auth section is optional, and only relevant settings from it should be included if a change is necessary
“auth”: {
“clearHashAfterLogin”: “false”
}
false Defines whether to clear the hash fragment after logging in
“auth”: {
“requireHttps”: “true”
}
“remoteOnly” Defines whether https is required. Default is “remoteOnly” which only allows http for localhost, while every other domains need to be used with https
“auth”: {
“sessionChecksEnabled”: “true”
}
true If true, the lib will try to check whether the user is still logged in on a regular basis as described in http://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification
“auth”: {
“showDebugInformation”: “false”
}
false Defines whether additional debug information should be shown at the console. Note that in certain browsers the verbosity of the console needs to be explicitly set to include Debug level messages
“auth”: {
“silentRefreshTimeout”: “20000”
}
20000 Timeout in ms for silent refresh
“auth”: {
“strictDiscoveryDocumentValidation”: “true”
}
true Defines whether every url provided by the discovery document has to start with the issuer’s url
“auth”: {
“timeoutFactor”: “0.75”
}
0.75 Defines when the token_timeout event should be raised. If you set this to the default value 0.75, the event is triggered after 75% of the token’s life time
“skin”: {…} optional section See separate article
“customMenuItems”: {…} optional section See separate article
“isConfig” [must be specified] Alway set to “true”
web.config (Windows, IIS)

C:\inetpub\dvi6root\clients\apps\kmd-dvi\web.config:

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Redirect all requests" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
              <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
              <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
          </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

web.config has a static content that instructs Internet Information Services to redirect all requests that is NOT for a specific file or folder to the root of the client where it is picked up and routed by Angular javascript.

plassidweb.conf (Linux, nginx - example naming)

/etc/nginx/conf.d/plassidweb.conf:

server {
  listen 0.0.0.0:80;
  server_name web.dvitraefik.local;
  large_client_header_buffers 4 16k;
  root /usr/share/nginx/html;
  location / {
    try_files $uri $uri/ /index.html;
  }
}

plassidweb.conf instructs nginx to redirect all requests that is NOT for a specific file or folder to the root of the client where it is picked up and routed by Angular javascript. The server_name entry is necessary to point to the root path of the DVI client web site if other sites are running at the same nginx web server. Other changes may be necessary to adapt the file to your specific environment.

API Data Server

Example C:\inetpub\dvi6root\api\appsettings.json:

{
  "CORS": {
    "AllowedHosts": "https://dvi6test.plassdata.net;https://api-dvi6test.plassdata.net;https://ids-dvi6test.plassdata.net"
  },
  "connectionStrings:DefaultConnection": "",
  "connectionStrings:TempReportDVIConnection": "XpoProvider=MSSqlServer;Persist Security Info=true",
  "deployment:enableSwagger": "false",
  "deployment:platform": "windowsvm",
  "server:apiPublicEndpoint": "https://api-dvi6test.plassdata.net",
  "server:apiLocalEndpoint": "https://api-dvi6test.plassdata.net",
  "server:idsPublicEndpoint": "https://ids-dvi6test.plassdata.net",
  "server:idsLocalEndpoint": "https://ids-dvi6test.plassdata.net",
  "sql:api2sql:dataSource": ".\\SQLEXPRESS",
  "sql:ids2sql:dataSource": ".\\SQLEXPRESS",
  "sql:job2sql:dataSource": ".\\SQLEXPRESS",
  "token:Audience": "vic_api_res",
  "token:LifetimeMinutes": "5",
  "token:NameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

Common settings

Common settings can/must be put in both the API Data Server and IdentityServer configuration files

Option Default Usage
“CORS”: {
“AllowedHosts”: “list-of-host;host;host…
}
[must be specified] List of all host URLs that may originate HTTP requests, separated by ;
connectionStrings:DefaultConnection empty Template connectionstring where datasource, catalog and authentication options are added according to settings. Enables you to specify further SQL connections settings such as encryption or certificates
dataPath:LicenseFolderSubPath Data/LicenseFiles Server harddisk subfolder where the license file(s) is stored
deployment:allowHttp false set to ‘true’ to allow endpoints to be bound to a port not requiring HTTPS, see important note
deployment:enableForwardedHeaders false set to ‘true’ to use forwarded headers, supported are XForwardedFor, XForwardedProto and XForwardedHost see Mozilla
deployment:enableSerilogRequestLogging false set to ‘true’ to log all incoming http requests to the service
deployment:enableSwagger false set to true to enable swagger endpoint for API definition readout
deployment:platform windowsvm reserved for future use
server:idsPublicEndpoint [must be specified] Binding of Plass.Id.Identity service on the public boundary server, i.e. https://ids-dvi6test.plassdata.net
ids-dvi6test is used instead of ids.dvi6test as https * certificates does only cover one level above certificate root.
You may choose any binding supported by your certificates.
Keep in sync with *2
server:idsLocalEndpoint [must be specified] Binding of Plass.Id.Identity service on the local server. If you are not using a boundary server (proxy, firewall etc), you must specify it identical to the above public endpoint
sql:[xxx]2sql:authorization integrated [xxx] = ‘api’, ‘ids’ or ‘job’
Authentication method from service to SQL Server. Change to SQL to use configuration-stored username and password (not recommended on Windows)
sql:[xxx]2sql:dataSource [must be specified] SQL Server Hostname, i.e. .\\SQLEXPRESS for a local SQL Express server.
[xxx] = ‘api’, ‘ids’ or ‘job’
sql:[xxx]2sql:password [must be specified if SQL authorization] SQL Server Authorization User Password if SQL specified in sql:[xxx]2sql:authorization
[xxx] = ‘api’, ‘ids’ or ‘job’
sql:[xxx]2sql:user [must be specified if SQL authorization] SQL Server Authorization User Name if SQL specified in sql:[xxx]2sql:authorization
[xxx] = ‘api’, ‘ids’ or ‘job’
sql:ids2sql:catalog PLASS_ID_IDENTITY Name of database used by Plass.Id.Identity.exe, IdentityServer4 Service
token:LifetimeMinutes 5 Must be included in config file, recommended value 5
token:NameClaimType http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Must be included in config file as-is
Note on HTTPS versus HTTP

Using HTTPS is a very important security aspect, and you should only allow HTTP if you have other security measures in place, i.e. perimeter HTTPS proxies, for the communication between clients and your server.
Enforcing end-to-end HTTPS security is being increasingly required by all kinds of components that takes part in the information exchange, and KMD is not able to ensure that the use of HTTP only, even only between our internal servers, will remain a possible option, and your network administrators should be aware of this.
If you are offloading SSL on boundary servers, you should configure these to forward the external headers and enable deployment:enableForwardedHeaders and deployment:allowHttp. You must also configure all xxxLocalEndpoint to reflect the differing internal protocol and urls on the inside of the boundary server.
:exclamation: Already now, you will not be able to authenticate and test the sites using only HTTP if using Chromium based browsers, as their cookie protection does not allow cookies from different sites (id-server versus api-server) to be stored when not using HTTPS. This behavior may propagate to other browsers over time.

API Service specific settings
Option Default Usage
dataPath:AdvancedSearchDatamodelSubPath Data/Datamodels Server harddisk subfolder where datamodels for the advanced search are stored
dataPath:AfisStorageFolderSubPath Data/AfisStorage Server harddisk subfolder where NIST files for AFIS are stored (reserved for future)
dataPath:AttachmentStorageFolderSubPath Data/AttachmentStorage Server harddisk subfolder where file attachments are stored (reserved for future, where you may select to store attachments separate from the database tables)
dataPath:DashboardDefinitionsFolderSubPath Data/Dashboards Server harddisk subfolder where Dashboard Definition Files are stored
dataPath:ReportDefinitionsFolderSubPath Data/Reports Server harddisk subfolder where Report Definition Files are stored
dataPath:LicenseFolderSubPath Data/LicenseFiles Server harddisk subfolder where the license file(s) is stored
dataPath:WorkFileFolderSubPath Data/WorkFiles Server harddisk temporary workfiles are stored i.e. during import, export and some report generation
server:apiPublicEndpoint [must be specified] Binding of Plass.Id.Data.Api service on the public boundary server, i.e. https://api-dvi6test.plassdata.net
api-dvi6test is used instead of api.dvi6test as https * certificates does only cover one level above certificate root.
You may choose any binding supported by your certificates.
Keep in sync with *2
server:apiLocalEndpoint [must be specified] Binding of Plass.Id.Data.Api service on the local server. If you are not using a boundary server (proxy, firewall etc), you must specify it identical to the above public endpoint
server:idsAuthorizationPath /connect/authorize reserved for future use
sql:api2sql:catalog PLASS_ID_COMMON Name of database used by Plass.Id.Data.Api.exe, API Data service
sql:job2sql:catalog PLASS_ID_JOBS Name of database used by Plass.Id.Data.Api.exe, Jobs Scheduler Service
deployment:enableForwardedHeadersLogging false Log all incoming HTTP headers if also DEBUG log level is set
endpoints:signalr:match /signalr/match Hub endpoint for matching-status messages (not yet configurable client-side)
endpoints:signalr:message /signalr/message Hub endpoint for inter-process or personal messages (not yet configurable client-side)
endpoints:signalr:job /signalr/job Hub endpoint for job-server progress messages (not yet configurable client-side)
search:limits:advancedRecords 10000 Maximum number of Advanced Search matches to return to client
search:limits:fulltextRecords 10000 Maximum number of Fulltext Search matches to return to client
token:Audience vic_api_res Must be included in config file as-is
web.config (Windows, IIS)

C:\inetpub\dvi6root\clients\apps\api\web.config:

<configuration>
	<location path="." inheritInChildApplications="false">
		<system.webServer>
			<handlers>
				<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified"/>
			</handlers>
			<aspNetCore processPath=".\Plass.Id.Data.Api.exe" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess"/>
			<security>
				<requestFiltering>
					<requestLimits maxQueryString="4096"/>
				</requestFiltering>
			</security>
		</system.webServer>
	</location>
</configuration>

Besides the setting for maxQueryString, the content of the web.config is standard and shouldn’t be altered.

The default value of maxQueryString (if it is not assigned) is 1024, but the search routines in DVI V6 requires more space allocated for the parameters, hence the value of 4096.

Identity Server

Example C:\inetpub\dvi6root\ids\appsettings.json:

{
  "CORS": {
    "AllowedHosts": "https://dvi6test.plassdata.net;https://api-dvi6test.plassdata.net;https://ids-dvi6test.plassdata.net"
  },
  "authentication:passwordRuleHistoryLimit": 3,
  "authentication:passwordRulesEnforcePasswordExpire": true,
  "authentication:passwordRulesInactivityLockoutExpireDays": 30,
  "authentication:passwordRulesMaxPasswordChangesPerDay": 2,
  "authentication:passwordRulesPasswordExpireDays": 90,
  "authentication:passwordRulesPreventSequentialPasswords": true,
  "connectionStrings:DefaultConnection": "",
  "deployment:enableSwagger": false,
  "deployment:platform": "windowsvm",
  "lockout:allowedForNewUsers": true,
  "lockout:defaultLockoutTimeSpan": {
    "hours": 0,
    "minutes": 30,
    "seconds": 0
  },
  "lockout:maxFailedAccessAttempts": 3,
  "password:RequireDigit": true,
  "password:RequireLowercase": true,
  "password:RequireNonAlphanumeric": true,
  "password:RequireUppercase": true,
  "password:RequiredLength": 10,
  "password:RequiredUniqueChars": 0,
  "server:apiPublicEndpoint": "https://api-dvi6test.plassdata.net",
  "server:apiLocalEndpoint": "https://api-dvi6test.plassdata.net",
  "server:idsPublicEndpoint": "https://ids-dvi6test.plassdata.net",
  "server:idsLocalEndpoint": "https://ids-dvi6test.plassdata.net",
  "sql:ids2sql:dataSource": ".\\SQLEXPRESS"
  "token:Audience": "ids_api_res",
  "token:LifetimeMinutes": "5",
  "token:NameClaimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
}

Authentication Policies

Option Default Usage
token:accessTokenLifetime 3600 Access token lifetime in seconds
authentication:passwordRuleHistoryLimit 0 How many old passwords should be refused for reuse
authentication:passwordRulesEnforcePasswordExpire false Whether password change should be required on expiry
authentication:passwordRulesInactivityLockoutExpireDays 0 Whether a user is permanently locked out after x days of inactivity
authentication:passwordRulesMaxPasswordChangesPerDay 0 How often a password may be changed per day, 0 = no limit
authentication:passwordRulesPasswordExpireDays 0 Password lifetime in days, 0 = indefinite
authentication:passwordRulesPreventSequentialPasswords false Prevent use of password patterns with a sequential number change on new password
lockout:allowedForNewUsers true Whether a new user can be locked out on inactivity before first login attempt
lockout:defaultLockoutTimeSpan { “hours”: 0, “minutes”: 5, “seconds”: 0 } Timespan a user is locked out for when a lockout occurs
lockout:maxFailedAccessAttempts 5 Number of failed access attempts allowed before a user is locked out
password:RequireDigit true  
password:RequireLowercase true  
password:RequireNonAlphanumeric true  
password:RequireUppercase true  
password:RequiredLength 10  
password:RequiredUniqueChars 0 Minimum number of different characters in password

Other settings like the Common Settings plus:

Option Default Usage
server:webPublicEndpoint [must be specified] Binding of Angular client file URL path on the public boundary server, i.e. https://dvi6test.plassdata.net, used to validate claimed callback-path from IdentityServer to Angular client.
server:webLocalEndpoint [must be specified] Binding of Angular client file URL path on the local server. If you are not using a boundary server (proxy, firewall etc), you must specify it identical to the above public endpoint
token:Audience ids_api_res Must be included in config file as-is