Accounting Service data and endpoints are secured:

All personally identifiable information (PII) is pseudonymised before stored into the database
Reporting endpoints are secured by OAuth2 authentication
Management endpoints are secured by HTTP Basic authentication - only minimum set of endpoints are exposed by default, see Accounting Service management

NOTE: As Basic Authentication mechanism provides no confidentiality protection for the transmitted credentials it is recommended that the management endpoints are not exposed to the public network or HTTPS must be configured to provide confidentiality.

Pseudonymisation

Pseudonymisation is done by calculating a hash-based message authentication code (HMAC) (https://en.wikipedia.org/wiki/HMAC) using by default HmacSHA256 algorithm and a secret key provided by the administrator. The following fields from the ticket granted audit log entry are pseudonymised:

Ubisecure user identifier
IP Address of the user
Session identifier of the user session
Authentication identifier a.k.a ticket request ID for the authentication

The same algorithm and key is used for all data.

Accounting Service reads the secret key from an external location each time when the service is started. Therefore the administrator should not change the contents of the key file during the reporting period which is a month. If the key in the Accounting Service were changed it would cause the count of active users to become larger than in reality. The only reason to change the key in the middle of the month would be a PII leakage.

NOTE: in a clustered environment you MUST have an identical secret key for each node or otherwise the same user would be counted as many.

Accounting Service has a scheduled job to read a new key in the beginning of each month letting the system administrator to change the key without service restart. Our recommendation is to change the contents of the key file occasionally just before the turn of the month (without restart).

The key location is defined during installation with property accounting.secret-key-location in win32.config/unix.config. The entropy of the key affects to the cryptographic strength of the pseudonym computed from an actual username; and the stronger the pseudonym, the more difficult it is to compute the username from it. Ubisecure recommends using a string of 64 random alphanumeric characters as the key. You can create a random seed based key contents of recommended entropy with the scripts below. Alternatively you can use some password generation utility.

Linux / Bash:

mkdir -p /usr/local/ubisecure/ubilogin-sso/accounting/config \
&& cat /dev/urandom \
| tr -dc 'a-zA-Z0-9' \
| fold -w 64 \
| head -n 1 > /usr/local/ubisecure/ubilogin-sso/accounting/config/accounting-service.secret

Windows / Powershell (Run as Administrator):

$path = "C:\Program Files\Ubisecure\ubilogin-sso\accounting\config"
$file = $path + "\accounting-service.secret"
$chars = [char[]]"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
if (Test-Path $file) {
  Remove-Item -Path $file
}
if (!(Test-Path $path)) {
  New-Item -path $path -type directory
}
foreach ($i in 1..64) { 
  Get-Random -Count 1 -InputObject $chars | Out-File -Append -Encoding ASCII -NoNewLine -FilePath $file
}

OAuth2 authentication

During the SSO installation process an OAuth 2.0 application named Accounting is created in SSO. The installation process creates a random client ID and secret which it uploads as metadata into the SSO application and stores into Accounting Service properties file.

There are two layers of access both controlled by the same OAuth2 application in SSO:

Browser endpoints authorized by OAuth2 login e.g. https://accounting.example.com/accounting/report (the actual URL depends on your network configuration, see Network requirements)
- OAuth2 login results in an access token which is yet validated via token introspection
API endpoints authorized by OAuth2 access token in e.g. GET /api/v1/accounting/report with the Bearer token in Authorization header
- Access token is validated via token introspection


Figure 1 SSO acts as the OAuth2 authentication provider for the Accounting Service

Accounting Service creates a session for the OAuth2 authentication which is by default configured to expire in 10 minutes. Session is stored in a browser cookie (JSESSIONID) that is deleted when the browser is closed.

On SSO side the default configuration after setup ignores session but forces re-authentication which makes authentication to the Accounting Service independent of the SSO authentication. The token validity time is set by default to 60 minutes.

TLS

If you want to configure TLS access to the Accounting Service you specify https scheme to accounting.proxy.local.url during installation. A self-signed certificate is created for you with the configured host name in this URL for testing purposes. A default password for the key-store is set in application-installation.properties.

You should change the key-store password and override the setting by defining server.ssl.key-store-password as part of Account Services configuration in config/application.yaml file. See Spring Boot Common application properties about other TLS settings (server.ssl). Note that changing the password of the shared key-store affects also to the SSO installation and should be updated in the server.xml file of SSO Tomcat installation.

Browser not supported