Accounting Service additional configuration - SSO
- John Jellema
Contents
Introduction
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.
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 |
|---|---|---|
| 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 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. |
Each day at 03:00 in the system time-zone Cron format:
|
cleaner-enabled | Defines if the cleaner job to remove obsolete data will be executed as a Boolean value. If | false |
| 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 |
Each day at 04:00 in the system time-zone |
| Defines the format for Monthly active unique user counts CSV file name. Supports two arguments: First argument | "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 About the duration format see e.g.: https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm |
Unique users for the previous (full) day |
| 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. |
Data of age more than 180 days is cleaned |
| 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: | Defines the format for Daily active unique users CSV file name. Supports two arguments: First argument | "MonthlyUsersPerDay-%1$s-%2$s.csv" |
csv: | Defines the format for Daily successful authentication events CSV file name. Supports two arguments: First argument | "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
| 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
| 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
SSO v. 8.4-8.6 with Accounting Service 1.0.x
| Defines location and prefix of log files. Audit log file has a suffix More information about logging in Accounting Service logging. | "logs/ids-accounting" |
Since SSO v. 9.0- with Accounting Service 2.x
SSO 8.4-8.x with Accounting
| 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):
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.yamlwhich includes the rest of the settings from theapplication-install.propertiesfile - A setting in
application-install.propertieshas a higher precedence than a setting with the same name inapplication.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/configdirectory 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.yamlfile 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.propertiesfile which is generated during the SSO installation and upgrade process based on thewindows/unix.configsettings. 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.