Contents

Introduction

NOTE: The basic configuration for Accounting Service is defined in the SSO setup file win32.config/unix.config. See SSO Installation Accounting Service settings about the properties in the configuration template.

There are couple of settings left to be customised during or after SSO installation for the Accounting Service Spring Boot application in the following file:

├── ubilogin
│   ├── custom
│   │   ├── accounting
│   │   │   └── config
│   │   │       └── application.yaml

A file with the default settings is copied from the installation package to this location under ubilogin-sso by the setup script.

Edit the YAML file in this location (ubilogin/custom/accounting/config/application.yaml) and change default values for properties explained under section Configuration settings below. Check also some hints in the notes section below.

After you have made your changes and saved the file execute SSO install / update script which will copy the configuration files to their proper place under ubilogin-sso during runtime before starting the service

├── accounting
│   ├── config
│   │   ├── application-install.properties
│   │   └── application.yaml
│   ├── ids-accounting-service.jar
│   └── logs

Configuration settings

The settings in the application.yaml are organised in a hierarchical way. All Accounting Service specific settings are under ubisecure.ids.accounting: section in the file.

Accounting Service has some additional configuration properties for advanced configuration. These can be communicated separately if a need arises for instance with JMS queue handling or event data security algorithm.

In addition, many of the Spring Boot Common application properties are applicable for the Accounting Service regarding e.g. logging, JMS. or security.

Recommended changes

The following table lists the properties you should always check and change under ubisecure.ids.accounting: section.

Property	Description	Default
`calculation-schedule`	Defines time and interval when the calculator job will process daily events to calculate daily unique users. Use "cron" format starting from seconds on the left. Silent hours on a daily basis to calculate the previous day's events is recommended. NOTE: In a clustered environment the time to execute should be different on each node in order to avoid unnecessary collisions in the SQL database. Finding the events of a 24 hour day is based on `calculation-timespan` setting, see table under Optional changes. Always a full 24 hour day is calculated. The first instant of a day is 0:00:00.000 and the last instant of a day is 23:59:59.000 in Accounting Service reporting time-zone which is by default UTC. Monthly calculation happens always on the last day of the month in the same job. Before monthly calculation the system checks that each day in this month has been calculated and if not calculates the missing days.	`0 0 3 * * *` Each day at 03:00 in the system time-zone Cron format: `<second> <minute> <hour> <day-of-month> <month> <day-of-week> <year>`where `<year>` field is optional
`cleaner-enabled`	Defines if the cleaner job to remove obsolete data will be executed as a Boolean value. If `true`, the cleaner job executes based on the cleaner configuration settings. If `false`, the cleaner job will never run.	`false`
`cleaner-schedule`	Defines time and interval when the cleaner job will be executed. Use "cron" format starting from seconds on the left. Silent hours are recommended. NOTE: In a clustered environment the time to execute should be different on each node in order to avoid unnecessary collisions in the SQL database. See also `cleaner-earliest-age` setting under Optional changes.	`0 0 4 * * *` Each day at 04:00 in the system time-zone
`csv: accounting-filename`	Defines the format for Monthly active unique user counts CSV file name. Supports two arguments: First argument `%1$s` is the report month. Second argument `%2$s` is the file creation time. Recommended naming is: `"<organization>-<installation>-%1$s.csv"` e.g. `"MyCompany-B2C-%1$s.csv"`	`"MonthlyAccounting-%1$s-%2$s.csv"`

Optional changes

The following table lists some optional properties you might want to change under ubisecure.ids.accounting: section.

Property	Description	Default
`audit-log-max-history`	Defines the maximum days of history to preserve for the audit log files as an integer value.	`366`
`calculation-timespan`	Defines time span between the calculation day in UTC and the day for which the events are included in the daily calculation. Use ISO 8601 duration format without time precision. See also `calculation-schedule`, which specifies the calculation day, above. About the duration format see e.g.: https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm	`P1D` Unique users for the previous (full) day
`cleaner-earliest-age`	Defines the maximum age for events and daily unique users data which are preserved in the database during the cleaning process. Use ISO 8601 duration format without time precision. Minimum value for this setting is 180 days in order to keep data to verify monthly calculations during the billing process. Monthly data is never cleaned by the system. For statistics purposes you may want to preserve the data for a longer period of time or even disable the cleaner. Consider using RDBMS utilities to backup and archive data.	`P180D` Data of age more than 180 days is cleaned
`reporting-timezone`	Defines time-zone for specifying the offset of start and end of the day for the events as a time-zone ID supported by Java. This affects to which events are included in the daily calculation or Daily events report. The events are always stored in UTC time-zone in the database. Consider changing this only during the installation process if your system time-zone is not UTC (as recommended). NOTE: You should never change this in the middle of the month when some days have already been calculated for this month. About Java time-zone IDs see e.g.: https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html	`UTC`
`csv: daily-users-filename`	Defines the format for Daily active unique users CSV file name. Supports two arguments: First argument `%1$s` is the report month. Second argument `%2$s` is the file creation time.	`"MonthlyUsersPerDay-%1$s-%2$s.csv"`
`csv: events-filename`	Defines the format for Daily successful authentication events CSV file name. Supports two arguments: First argument `%1$s` is the report month. Second argument `%2$s` is the file creation time.	`"DailyEvents-%1$s-%2$s.csv"`

The following table lists some optional Spring framework properties you might want to change. Some of the properties have changed since SSO v. 8.7.

Property	Description	Default
Since SSO v. 8.7- with Accounting Service 1.1.x `server.forward-headers-strategy`	When running behind a proxy, the caller wants a link to the proxy and not to the physical address of the machine hosting your app. With this setting the absolute links are rendered correctly when the proxy adds conventional X-Forwarded-For and X-Forwarded-Proto headers. If this feature is not needed you may consider removing the setting. https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#howto-use-behind-a-proxy-server	`native`
SSO v. 8.4-8.6 with Accounting Service 1.0.x `server.use-forward-headers`	When running behind a proxy, the caller wants a link to the proxy and not to the physical address of the machine hosting your app. With this setting the absolute links are rendered correctly when the proxy adds conventional `X-Forwarded-For` and `X-Forwarded-Proto` headers. If this feature is not needed you may consider setting it back to the value false due security, see https://tools.ietf.org/html/rfc7239#section-8.	`true`
Since SSO v. 8.7- with Accounting Service 1.1.x `logging.file.name` SSO v. 8.4-8.6 with Accounting Service 1.0.x `logging.file`	Defines location and prefix of log files. Audit log file has a suffix `_audit` in its file name. More information about logging in Accounting Service logging.	`"logs/ids-accounting"`
Since SSO v. 9.0- with Accounting Service 2.x `logging.logback.rollingpolicy.max-history` SSO 8.4-8.x with Accounting Service 1.x `logging.file.max-history`	Defines the maximum days of history to preserve for the application log files as an integer value.	`10`
`logging.level.com.ubisecure`	Defines logging level for Accounting Service implementation. Can be one of the following (case insensitive): `trace` `debug` `info` `warn` `error` Note that you can also change the log level when the system is running, see Accounting Service management.	`info`
spring.mvc.async.request-timeout	Define how long time in milliseconds a asynchronous request is processed until it is stopped. This applies to event streaming endpoints. Specify a greater value if you really want to download a huge amount of events which takes more than 1 hour. Specify a smaller value to prevent clients requesting too much data to overuse system resources.	3600000

Notes about editing application configuration files

General notes

Never remove the first line of the application.yaml which includes the rest of the settings from the application-install.properties file
A setting in application-install.properties has a higher precedence than a setting with the same name in application.yaml
Since Accounting Service is a Spring Boot application it is able to read configuration settings in various ways. This is both a benefit and a caveat so pay attention to have the configuration files only in accounting/config directory during runtime and not to leave any extra configuration files (old, temp etc.) in the runtime directories

About YAML syntax

Comments begin with the number sign #
The following examples are equal:

ubisecure.ids.accounting.csv.accounting-filename: "MonthlyAccounting-%1$s-%2$s.csv"

ubisecure.ids.accounting:
  csv:
    accounting-filename: "MonthlyAccounting-%1$s-%2$s.csv"

Using quotation marks is not always necessary but when using them in a context like above you don't need to think about escaping reserved characters

How to speed up troubleshooting

If troubleshooting or experimenting you may modify the application.yaml file in the runtime location (ubilogin-sso/accounting/config) and restart the Accounting Service in order to put the changes into effect.

When you are satisfied with the contents of application.yaml file remember to copy the resulting file into the primary location (under custom directory) so that your changes are not lost in further SSO updates.

It is not recommended but you may try to modify directly the application-install.properties file which is generated during the SSO installation and upgrade process based on the windows/unix.config settings. Note that most of the settings there needs to be in sync with SSO server

When you are satisfied with the contents of application-install.properties file remember to modify the respective settings in the windows/unix.config file so that your changes are not lost in further SSO updates.

Browser not supported