Introduction

The browser endpoints explained in Using Accounting Service can be used directly as REST API endpoints with OAuth2 authentication.

Since v. 1.2.0 Accounting Service offers in addition a new API to get detailed event information for further analysis.

Configuring Accounting Service API

When using any Accounting Service API endpoints for the first time the following additional configuration is recommended due security.

Do not use Accounting application credentials

Do not use or expose Accounting OAuth2 application secrets to integrate with Accounting Service API. The Accounting OAuth2 application secret is meant for Accounting Service browser endpoints access and internal use in SSO.

Creating a new OAuth2 application

Create new OAuth2 client application as instructed in Management UI Applications or alternatively use the Management API. Allow Accounting Users to access the newly created application and enable for example password.1 method or your preferred method for the application.

The following OAuth2 client metadata describes a simple OAuth2 client that can request an access token using OAuth2 Resource Owner Password Credentials Grant

{
  "client_id": "... redacted ...",
  "client_secret": "..redacted...",
  "allowed_methods": [
    "password"
  ]
}

After the application has been configured proceed with defining an API user.

Define API user

Add a user to Accounting Users group e.g. with the Management UI. You can choose from the following options:

Create a new user with password method allowed, and add it
Add an existing user with password method allowed
Add an existing group

Any of these actions can also be performed using the Management API.

Using Accounting API

Locate API scope

In order to access the Accounting API you need its client ID for the scope parameter of the OAuth2 Token Request. This client ID is visible in System → Accounting → Applications → Accounting as depicted here

Get the access token

Get the access token e.g. with OAuth2 Password grant. You may use the --insecure flag in case self-signed certificates are used:

$ curl \
  --request POST 'https://<sso-base-url>/uas/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'scope=openid <accounting-client-id>' \
  --data-urlencode 'client_id=<oauth2-client-id>' \
  --data-urlencode 'client_secret=<oauth2-client-secret>' \
  --data-urlencode 'username=<accounting-api-user>' \
  --data-urlencode 'password=<accounting-api-password>'

Where:

Parameter	Description
accounting-client-id	The client_id of the Accounting OAuth2 application retrieved in Locate API scope section
oauth2-client-id	The client_id of your OAuth2 client application you created in Creating a new OAuth2 application section
oauth2-client-secret	The client_secret of your OAuth2 client application you created in Creating a new OAuth2 application section
accounting-api-user	The username of the user you created in Define API user section
accounting-api-user-password	The password of the user you created in Define API user section

Using Accounting API

The Accounting API is documented using Swagger. You can access Swagger UI in https://<accounting-base-url>/swagger-ui/ by providing Accounting user credentials. Swagger documentation defines the endpoints, payloads, and responses. Note that the Swagger UI Try it out feature is not supported.

Swagger API specification

The API specification for your installation is available in https://<accounting-base-url>/v3/api-docs

Authentication

Add the OAuth2 access token received from SSO like explained in Get access token to the Authorization header as a bearer token:

Authorization header via curl

--header 'Authorization: Bearer <your access token here>'

When using API 401 HTTP status code is returned if access token is missing or not valid.

Accounting Service reporting API

These API endpoints having a respective browser endpoint are described on this page Using Accounting Service:

/api/v1/accounting/report/(<yyyy-MM>)
/api/v1/accounting/verify/daily-users/<yyyy-MM>
/api/v1/accounting/verify/events/<yyyy-MM-dd>

Event details API

Description

Retrieves detailed information about SSO ticket granted events recorded during a time period. The time period can be selected between one minute and one month. The events can be returned either in ascending (default) or descending order by event creation time.

The endpoint streams the response either as a JSON document (default) or CSV file based on the Accept request header.

The endpoint has been designed having e.g. the following kind of use cases in mind when the raw data is further analyzed:

Administrator is able to see which of the specific authentication methods have been used recently
- including periodic polling to offer near real-time utilisation
Administrator is able to see which of the specific authentication methods are the most used ones
Administrator is able to see which applications have been used recently
- including periodic polling to offer near real-time utilisation
Administrator is able to see which applications are the most used ones

Request URL

Request URL defines the time period and sort direction for the events to return.

Examples

/api/v1/statistics/events/day/2021-04-24 – get the events occurred on the given day (2021-04-24 00:00 - 2021-04-24 23:59:59.999999)
/api/v1/statistics/events/hour/2021-04-24T13?sort=- – get the events occurred up to the given hour in descending order (2021-04-24 12:00:00:000001 - 2021-04-24 13:00)
/api/v1/statistics/events/minute?sort=- – get the events occurred the latest minute, in descending order

Request method

GET

Request URL parameters

Path parameters

Parameter name Description

period

Parameter name	Description
period	The period of the time from which to return the events: MINUTE, HOUR, DAY, WEEK (7 days), MONTH - case insensitive. NOTE that you should choose such a period that produces a reasonable amount of events in the response so that you don't overuse resources. In typical installations, a period longer than a DAY is not recommended. It is better to make consecutive calls with a shorter period. See also `spring.mvc.async.request-timeout` property in Accounting Service additional configuration.
datetime	Optional date/timestamp for the earliest events to include with ascending order or latest events to include with descending order. The required precision for the parameter depends on the given period. If not given, derived from the current time and given period. MINUTE 2021-03-19T08:23 HOUR 2021-03-19T08 DAY 2021-03-19 WEEK 2021-03-19 - meaning 7 days starting from /ending by the given day MONTH 2021-03 The times are handled in UTC time zone so if you specify e.g. `day/2021-03-31` with ascending order, then the events from `2021-03-31T00:00Z` for 24 hours shall be included.

The period of the time from which to return the events: MINUTE, HOUR, DAY, WEEK (7 days), MONTH - case insensitive.

NOTE that you should choose such a period that produces a reasonable amount of events in the response so that you don't overuse resources. In typical installations, a period longer than a DAY is not recommended. It is better to make consecutive calls with a shorter period. See also spring.mvc.async.request-timeout property in Accounting Service additional configuration.

datetime

Optional date/timestamp for the earliest events to include with ascending order or latest events to include with descending order. The required precision for the parameter depends on the given period. If not given, derived from the current time and given period.

MINUTE 2021-03-19T08:23
HOUR 2021-03-19T08
DAY 2021-03-19
WEEK 2021-03-19 - meaning 7 days starting from /ending by the given day
MONTH 2021-03

The times are handled in UTC time zone so if you specify e.g. day/2021-03-31 with ascending order, then the events from 2021-03-31T00:00Z for 24 hours shall be included.

Query parameters

Parameter name	Description
sort	Sort direction, provide '-' for descending order by timestamp, otherwise ascending order by timestamp is used.

Headers

Header name Description

Header name	Description
Authorization	Mandatory bearer token e.g. 'Authorization: Bearer eyJjdHkiOiJKV1Q...' (token truncated)
Accept	Optional case insensitive media type for the response. If not provided or allows all media types, `application/json` media type is returned. If CSV output is desired, media type `text/csv` needs to be specified. Note that due error handling in case of CSV it is recommended to add also `application/json` media type to the header with lower precedence as an error response is always JSON. You can use either the order or q-value to specify the precedence. Examples: `'Accept: text/csv, application/json'` - CSV is returned `'Accept: application/json;q=0.9,` text/csv' - CSV is returned `'Accept: /'` - JSON is returned

Authorization

Mandatory bearer token e.g. 'Authorization: Bearer eyJjdHkiOiJKV1Q...' (token truncated)

Optional case insensitive media type for the response. If not provided or allows all media types, application/json media type is returned.

If CSV output is desired, media type text/csv needs to be specified. Note that due error handling in case of CSV it is recommended to add also application/json media type to the header with lower precedence as an error response is always JSON. You can use either the order or q-value to specify the precedence.

Examples:

'Accept: text/csv, application/json' - CSV is returned
'Accept: application/json;q=0.9, text/csv' - CSV is returned
'Accept: */*' - JSON is returned

Curl example

You may use the --insecure flag in case self-signed certificates are used. Add Accept header with value 'Accept: text/csv, application/json' for CSV output.

curl \
  --location \
  --request GET 'https://<accounting-base-url>/api/v1/statistics/events/minute/2021-04-10T00:00' \
  --header 'Authorization: Bearer eyJjdHkiOiJKV1Q...' \

Response Document

JSON output

An EventDetailsResponse object with NavigationLinks and list of EventDetails matching request parameters is returned (see Swagger API models for additional information)

{
    "links": {
        "self": "https://<accounting-base-url>/api/v1/statistics/events/minute/2021-04-10T00:00",
        "prev": "https://<accounting-base-url>/api/v1/statistics/events/minute/2021-04-09T23:59",
        "next": "https://<accounting-base-url>/api/v1/statistics/events/minute/2021-04-10T00:01"
    },
    "events": [
        {
            "timestamp": "2021-04-10T00:00:00",
            "authMethodType": "OAUTH2",
            "authMethodName": "oauth2.1",
            "authRequestOrigin": "CN=Appl-1,CN=Server,OU=System,CN=Ubilogin,DC=test",
            "userId": "ab242444f48d515d1df97823c41b1c7b08d33e4fbee62cef0c82a8eeccfecdf2"
        },
        {
            "timestamp": "2021-04-10T00:00:20.123",
            "authMethodType": "UNREGISTERED.SMTP",
            "authMethodName": "smtp.1",
            "authRequestOrigin": "CN=Appl-2,CN=Server,OU=System,CN=Ubilogin,DC=test",
            "userId": "1ebdb54103a7867918d4f4843328ad76fd0a5baf3c5a7a42f77becdd37d66088"
        },
        {
            "timestamp": "2021-04-10T00:00:40.246",
            "authMethodType": "PASSWORD",
            "authMethodName": "password.1",
            "authRequestOrigin": "CN=Appl-2,CN=Server,OU=System,CN=Ubilogin,DC=test",
            "userId": "c9179041cf81d54cd262e01601caefe03aab9d0ebebd120191360e54a7ef56d1"
        }
    ]
}

CSV output

A header row and a row for each event matching request parameters is returned

Timestamp,Authentication Method Type,Authentication Method Name,Authentication Request Origin,Pseudonymised User ID
2021-04-10T00:00:00,OAUTH2,oauth2.1,CN=Appl-1,CN=Server,OU=System,CN=Ubilogin,DC=test,ab242444f48d515d1df97823c41b1c7b08d33e4fbee62cef0c82a8eeccfecdf2
2021-04-10T00:00:20.123,UNREGISTERED.SMTP,smtp.1,CN=Appl-2,CN=Server,OU=System,CN=Ubilogin,DC=test,1ebdb54103a7867918d4f4843328ad76fd0a5baf3c5a7a42f77becdd37d66088
2021-04-10T00:00:40.246,PASSWORD,password.1,CN=Appl-2,CN=Server,OU=System,CN=Ubilogin,DC=test,c9179041cf81d54cd262e01601caefe03aab9d0ebebd120191360e54a7ef56d1

Error handling

When accepting JSON media type and an error happens an ErrorResponse object is returned (see Swagger API models)

400 when request with invalid period value

{
    "error": "invalid_request",
    "error_description": "Valid values for the time period: minute, hour, day, week, month."
}

When accepting only CSV media type and an error happens typically HTTP status code 406 Not Acceptable is returned.

With JSON, if the streaming has already started with status code 200 and an error happens during processing, an error element may be included to the EventDetailsResponse.

With CSV, an error after streaming has started causes just end of streaming.

Accounting service log can be studied for error details.

Browser not supported