Use cases

Accounting Service provides its data in the Comma Separated Values (CSV) format either via browser calls or direct calls to its API. The separator in use is comma (,).

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. https://accounting.example.com/accounting/report or https://accounting.example.com/accounting/report/2019-03 
• API endpoints e.g. GET /api/v1/accounting/report/2019-03 Host: accounting.example.com


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):

Month,Authentication Method,User Count
2019-03,TUPAS2,558
2019-03,UBAA,341
2019-03,DIRECT.SMS,217
2019-03,DIR.OTP,217
2019-03,DIR.MOBILE.PKI,186
2019-03,MOBILE.PKI,186
2019-03,OPENID.CONNECT,155
2019-03,OAUTH2,155
2019-03,PASSWORD,155
2019-03,SAML,155
2019-03,UNREGISTERED.SMS,155
2019-03,OPENID.RELYING,155
2019-03,UNREGISTERED.SMTP,155
2019-03,MOBILE.CONNECT,93
2019-03,TOTAL,2883

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

1. Open your browser and enter the URL:


   https://accounting.example.com/accounting/report

   1. By default the previous month data is returned

   2. If you need another month's data in the past add month specifier <yyyy-MM> in the URL e.g. 

      https://accounting.example.com/accounting/report/2019-01

2. Your are redirected to SSO for authentication - enter the credentials of the user that has access to the Accounting application in SSO and sign-in

3. 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
4. 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"
5. If you want to take another report enter the respective URL
6. 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

1. Configure Accounting Service API for the first time usage, see detailed instructions from Accounting Service API.
2. Request an OAuth2 access token from SSO, see Accounting Service API / Get the access token.

3. Access GET /api/v1/accounting/report Host: accounting.example.com with the Bearer token in Authorization header (token is wrapped and truncated in the following localhost example)

   Example with curl

   curl -H "Authorization: Bearer eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiemlwIjoiREVGIiwiaXNzIjoi 
   NDBjNDk3MjgtN2Q1YS00MzVmLWE5OGMtYjQ1MjkzYjUyMjRiIn0..RsC94xV8OnZ33SpkB6jLzQ.WWWM2brY7wqdmzzSWZjBHjHCcNoB9oFoya2TPSQDbIl 
   5G9H05vAwtawZhcPw5pah34YEW9ICFJkMmRglzxAKUpTlENc6TuAlh0oenmaVFQFVfWb8oeYwL1LC0LXuCg_V2LzWXiwfhZsQACTGSoOAEvqXlLy-WjM..." 
   localhost:8084/api/v1/accounting/report

   
   

4. Save the response including the header line in a file. Please use <Organization>-<Installation>-<yyyy-MM>.csv as the file name,  e.g. "MyCompany-B2B-2019-03.csv"
5. If you want to take another report access the respective URL and save the response
6. 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):

Date,Authentication Method,Pseudonymised User ID
2019-03-01,OAUTH2,d9d5df54426b80b63c1e3ca29bf6044d0481c17ced52e8bd2d53517edac8c905
2019-03-01,DIR.OTP,302768acb5f7f86ae91540f39fe6fcf405218e4826ed4f5da6ec4d3184b9eb04
2019-03-01,PASSWORD,aacfc9dff3b5da4df41410fe40f6102f5b569b9c0289129c723255af083f11fc
2019-03-01,UNREGISTERED.SMTP,aacfc9dff3b5da4df41410fe40f6102f5b569b9c0289129c723255af083f11fc
2019-03-01,TUPAS2,aacfc9dff3b5da4df41410fe40f6102f5b569b9c0289129c723255af083f11fc
2019-03-01,UBAA,305622ee052f9e576470bd58f948ee1ea016811b14a661055003d7ff6da54da7
...
2019-03-31,UBAA,b4e7371c491350b7f4a45ba10c38320e319c7561bfa08fdd6143f14cf5f4624c
2019-03-31,SAML,b4e7371c491350b7f4a45ba10c38320e319c7561bfa08fdd6143f14cf5f4624c
2019-03-31,TUPAS2,b4e7371c491350b7f4a45ba10c38320e319c7561bfa08fdd6143f14cf5f4624c
2019-03-31,TUPAS2,3da85529c50037de9467884d0b73ddfb2c0649b8fddab0495448df6545dd7b80
2019-03-31,DIR.MOBILE.PKI,3eeae323edc1ba0df70e60d2cefba00d1d1ac2f7b6afbdd690e953d7b291c407
2019-03-31,UNREGISTERED.SMTP,085d28703c50be6a38bbecef2e57cb517c07f075c0909c2b2c462303cb5592de

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.

• Browser endpoint(e.g. https://accounting.example.com/accounting/verify/daily-users/2019-03):

  https://accounting.example.com/accounting/verify/daily-users/<yyyy-MM>

• API endpoint (e.g. GET /api/v1/accounting/verify/daily-users/2019-03:)

  GET /api/v1/accounting/verify/daily-users/<yyyy-MM> Host: accounting.example.com

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):

Timestamp,Authentication Method,Pseudonymised User ID
2019-03-15T00:01:12Z,TUPAS2,68067309a5f858da9a6ed1b4aadfbd971b5d0968ac97e95c7ee9a85fefbfa942
2019-03-15T00:04:48Z,UBAA,637f9ba98ce2b690815a978f58fe0425fe7f737034acb2259e8f493ffb261670
2019-03-15T00:22:48Z,UNREGISTERED.SMS,2b6b4d2fbd25a3c848bed5848ad2e45f3c242f73311b95945046cdf5456ada83
2019-03-15T00:28:48Z,OPENID.RELYING,b4e7371c491350b7f4a45ba10c38320e319c7561bfa08fdd6143f14cf5f4624c
2019-03-15T00:09:00Z,TUPAS2,a5a83b53c0bd52cf0d7672f018bd2a05990aa37614aa2971901650db2ccffa2b
2019-03-15T00:15:00Z,TUPAS2,e41b71f03f30ef8ee4045fa54805208793ccc9369a8284c11a31018a4832669e
2019-03-15T00:21:00Z,TUPAS2,e1759e47c17f536bdb82c3e7472bbe6ffa7881d40326e6c0c0597ccf829acbc4
2019-03-15T00:33:00Z,PASSWORD,aacfc9dff3b5da4df41410fe40f6102f5b569b9c0289129c723255af083f11fc
2019-03-15T00:39:00Z,TUPAS2,a5a83b53c0bd52cf0d7672f018bd2a05990aa37614aa2971901650db2ccffa2b
2019-03-15T00:45:00Z,UNREGISTERED.SMS,637f9ba98ce2b690815a978f58fe0425fe7f737034acb2259e8f493ffb261670
2019-03-15T00:57:00Z,MOBILE.PKI,99f6b4e6b82dfc3c0abd9e85c4207c85f92eaa0c05b220e188f802288e823ded
2019-03-15T01:03:00Z,TUPAS2,a5a83b53c0bd52cf0d7672f018bd2a05990aa37614aa2971901650db2ccffa2b
2019-03-15T01:09:00Z,PASSWORD,3b4e5ba2d62e69b6de6730d407f94c999b01c17e10b0d110ed98dfffcbd92191
2019-03-15T01:15:00Z,TUPAS2,32ad93ca9b5c5b69b79293363cb4f0c5fafbb3a33212fcdfd03b10a2ea6ba1f3
2019-03-15T01:21:00Z,TUPAS2,e41b71f03f30ef8ee4045fa54805208793ccc9369a8284c11a31018a4832669e
2019-03-15T01:27:00Z,TUPAS2,b2dcb0eaa57a89181dd330dc24002ba99ca82c082addc29d59d95fa1f9b5479d
2019-03-15T01:45:00Z,TUPAS2,e41b71f03f30ef8ee4045fa54805208793ccc9369a8284c11a31018a4832669e
2019-03-15T01:51:00Z,OPENID.CONNECT,e41b71f03f30ef8ee4045fa54805208793ccc9369a8284c11a31018a4832669e
2019-03-15T01:57:00Z,SAML,d7caf5f576bec81b98079f7384bea6db0c467e7c7e06bd898daf0c7ff845d6cb
2019-03-15T02:03:00Z,DIRECT.SMS,b4e7371c491350b7f4a45ba10c38320e319c7561bfa08fdd6143f14cf5f4624c
2019-03-15T02:09:00Z,UNREGISTERED.SMS,dd51a878524180e9c8abb17170ce75e625002b132d3e59132a3ebb4c463f011d
2019-03-15T02:15:00Z,UNREGISTERED.SMTP,aacfc9dff3b5da4df41410fe40f6102f5b569b9c0289129c723255af083f11fc
2019-03-15T02:21:00Z,OAUTH2,d9d5df54426b80b63c1e3ca29bf6044d0481c17ced52e8bd2d53517edac8c905
2019-03-15T02:27:00Z,MOBILE.PKI,99f6b4e6b82dfc3c0abd9e85c4207c85f92eaa0c05b220e188f802288e823ded
2019-03-15T02:33:00Z,CERT.AGENT,d7caf5f576bec81b98079f7384bea6db0c467e7c7e06bd898daf0c7ff845d6cb
2019-03-15T02:39:00Z,UNREGISTERED.SMS,dd51a878524180e9c8abb17170ce75e625002b132d3e59132a3ebb4c463f011d
2019-03-15T02:45:00Z,UNREGISTERED.SMS,3f87c0462acc38820d5715d9c948b498e02fdb3c2b2c25be5d637122c3c40a3b
2019-03-15T02:51:00Z,MOBILE.PKI,53f04c4381e4674a55eb7c876408332f36deb44cf2b308d9a462f47af515aa51
2019-03-15T02:57:00Z,OPENID.CONNECT,e41b71f03f30ef8ee4045fa54805208793ccc9369a8284c11a31018a4832669e
2019-03-15T03:03:00Z,PASSWORD,53f04c4381e4674a55eb7c876408332f36deb44cf2b308d9a462f47af515aa51
...

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. https://accounting.example.com/accounting/verify/events/2019-03-15)


  https://accounting.example.com/accounting/verify/events/<yyyy-MM-dd>

• API endpoint (e.g. GET /api/v1/accounting/verify/events/2019-03-15):

  GET /api/v1/accounting/verify/events/<yyyy-MM-dd> Host: accounting.example.com