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.

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.

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

accounting-client-id

oauth2-client-id

oauth2-client-secret

accounting-api-user

accounting-api-user-password

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.

Authentication

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

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

Query parameters

Headers

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)

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