Accounting Service provides its data in the
NOTE: You must adjust the example URLs and paths like
on this page based on your network configuration, see Network requirements.
Accounting Service CSV download endpoints are secured by OAuth2 SSO being the OAuth2 provider. The necessary OAuth2 configuration on client and provider side is done during the installation process. There are two layers of access:
- Browser endpoints e.g.
- API endpoints e.g.
GET /api/v1/accounting/report/2019-03 Host: accounting.example.com
NOTE for Excel users: You can open the resulting CSV files in Microsoft Excel but depending on the volumes you may reach the limits of Excel regarding the allowed rows especially for Daily events. In addition, Excel may format the date and time columns in an undesired format.
Accounting Database size requirements
You can find estimations for the size of database required for the Accounting Service on the System Recommendation page, see Accounting login events. The number of login events are not time based, so if your environment will experience 1 000 000 login events per month, then the annual disk usage would be 12 GB provided you alter the default deletion of records which is set at 180 days.
Monthly active unique user counts report
This is the basic report which contains monthly unique user counts for each authentication method that has been used in this month. The most used method is on the top and the total is calculated on the last row.
The following imaginary example shows the contents of the CSV file (month requested 2019-03):
In order to provide correct information to Ubisecure for monthly billing purposes you need each month to:
- Get the report
- Send the report
Below you will find instructions on how to achieve this.
Get the report
You have two options to get the CSV contents from the system:
- Download the CSV file via browser
- Access the Accounting Service API which returns a response in CSV format
Steps for browser download
Open your browser and enter the URL:
- By default the previous month data is returned
If you need another month's data in the past add month specifier
<yyyy-MM>in the URL e.g.
Your are redirected to SSO for authentication - enter the credentials of the user that has access to the
Accountingapplication in SSO and sign-in
Depending on your environment and browser either the CSV file is automatically downloaded or you get a dialog and you can save it - save the file
- The downloaded file will have a prefix of the value set in Accounting Service additional configuration property:
ubisecure.ids.accounting.csv.accounting-filename. If you have not customised it, please prefix the file with e.g. "MyCompany-B2B-2019-03.csv"
- If you want to take another report enter the respective URL
- Accounting Service session length is by default configured to be 10 minutes before new authentication is requested. There is no logout action but when you are finished you can close the browser or remove cookies to clear you session before the 10 minutes timeout
Steps for using the API endpoint
- Configure Accounting Service API for the first time usage, see detailed instructions from Accounting Service API.
- Request an OAuth2 access token from SSO, see Accounting Service API / Get the access token.
GET /api/v1/accounting/report Host: accounting.example.comwith the
Authorizationheader (token is wrapped and truncated in the following
- Save the response including the header line in a file. Please use
<Organization>-<Installation>-<yyyy-MM>.csvas the file name, e.g. "MyCompany-B2B-2019-03.csv"
- If you want to take another report access the respective URL and save the response
- Token expiration time is configured to be 60 minutes by default in the SSO OAuth2 application
Send the report
To send in your monthly report of usage to Ubisecure, use "Monthly report from
<Organization + Installation>" as the subject of the mail, where
<Organization> is your Company name and
<Installation> is B2B or B2C if you have different installations. If you are unsure where to send your report, please contact Support.
Daily active unique users report
Additional reports can be used for instance to verify calculations. Monthly active unique user counts are calculated from the daily active unique users data so that each combination of an authentication method and user ID for the entire month is calculated as one active unique user for this authentication method. Daily active unique users report contains data for each of the day for the given month in the ascending order by date.
The following imaginary example shows partial contents of the CSV file (month requested 2019-03):
The example URLs for the Daily active unique users report are below. Otherwise follow the how-to steps for Monthly active unique users count report.
API endpoint (e.g.
Daily successful authentication events report
Daily successful authentication events report contains each SSO recorded ticket granted event and the amount of them should be the same as in the SSO audit log. Daily active unique users are derived from the events so that each unique combination of an authentication method and user ID during the day (between 00:00:00.000 - 23:59:59.999) is recorded as one daily active unique user. Daily successful authentication events report contains data for the given 24 hour day in the ascending order by time of the event.
NOTE: since SSO v. 8.8. with Accounting Service 1.2.x the event table column structure has been optimised for better performance. Therefore this endpoint shall return "Unknown Authentication Method Type" instead of the actual authentication method type for all events created before the upgrade. See Accounting Service database about the change.
The following imaginary example shows partial contents of the CSV file (date requested 2019-03-15):
The example URLs for the Daily successful authentication events report are below. Otherwise follow the how-to steps for Monthly active unique users count report.
Browser endpoint: (e.g.
Since SSO v. 8.8. with Accounting Service 1.2.x there is a new endpoint to request past events which is more flexible and is able to produce also JSON instead of CSV. See Accounting Service API section Event details API.