Accounting Service additional configuration - SSO

Owned by ubisebastian
Last updated: 2021-01-19Version comment

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 (https://en.wikipedia.org/wiki/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.

PropertyDescriptionDefault

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.

PropertyDescriptionDefault
audit-log-max-historyDefines 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.

PropertyDescriptionDefault

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-servernative

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

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"
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

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.


Ubisecure Privacy Policy & Cookie Statement