1.17.2. Reporting#

Starting with LinOTP 2.9 a new reporting API was introduced. It can be used to query information about the number of tokens. This can be useful for accounting in multitenancy environments or statistical purpose.

The comprehensive API documentation can be found here:

https://www.linotp.org/doc/api/linotp.controllers.reporting.html

The basic API call is:

https://<LINOTP>/reporting/<ReportingController>?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]

The available controllers are:

show: displays historical count data
period: displays historical count data in a specific period (from to)
maximum: displays highest values counted
delete_all: clean the counter database
delete_before: delete all values in the counter database recorded before a defined date

Tip

Detailed information about the handling of the session cookie can be found at Session parameter

Prerequisites#

The reporting API can be accessed by the token managers. The available queries have to be configured before via policies as described in Reporting Policies.

Tip

After adding new states to be recorded in the policies the next count will be performed after an event was triggered potentially changing the counted value. So for example if a new token is enrolled the counters are recalculated and can be queried.

Configuration#

The reporting feature must be activated so that LinOTP starts recording events. We will only be able to evaluate reporting for events that have been recorded after the reporting has been enabled.

Activating Reporting and Reporting access#

Reporting is enabled by configuring a policy in the reporting scope. Within the user interface manage UI in the scope reporting, with the action token_status=. The action can be used multiple times to configure different status types for reporting.

Policy complete example

[Reporting]
realm = *
name = Reporting
action = 'token_total, token_status=assigned&active, token_status=unassigned&active,
token_status=assigned&inactive, token_status=unassigned&inactive, token_status=active,
token_status=inactive, token_status=assigned, token_status=unassigned'
client = *
user = *
time = * * * * * *;
active = True
scope = reporting

Reporting_access is activated with the corresponding policy from the reporting_access scope.

[Reporting_access]
realm = *
name = Reporting_access
active = True
client = *
user = *
time = * * * * * *;
action = "show, period, maximum, delete_all, delete_before"
scope = reporting.access

Current limitations#

tokens not assigned to a realm are not reported in the APIs that group by realm.
To get exact numbers the call is necessary for each realm individually.

You can look at the LinOTP documentation for Poliy about token_total reporting.

Reporting Modes#

LinOTP can log reporting in two different modes:

token_total reporting:

Basic reporting of total Number of Tokens only - reporting/[maximum|status|period]?

The entire available period is evaluated retroactively up to the last ‘reporting/delete_before’.

Total is determined without status and realms

token_status reporting:

Advanced reporting for different token states - reporting/show or reporting/period

Explanation of the available token states:

active

counts only active tokens

inactive

counts only deactivated tokens

assigned

counts only tokens assigned to users

unassigned

counts only tokens which are not assigned to any user

active&assigned

counts tokens which are active and assigned to a user

active&unassigned

counts active tokens which are not assigned to any user

inactive&assigned

counts disabled tokens assigned to users

inactive&unassigned

counts disabled tokens which are not assigned to any user

total

counts all tokens that are assigned to a realm

*

only for delet_all or delete_before the star stands for each status

reporting_period define a reporting period:

The status of the tokens can be queried as with reporting and show for a period ‘from=YYY-mm-dd&to=YYY-mm-dd’.

With ‘period’ and the desired status e.g. ‘status=active%26assigned’ an exact report about the used tokens in the specified period ‘from=2022-04-01&to=2022-05-01’ can be generated.

The feature of ‘token_total’ is fully supported in mode ‘token_status’, which is why we only cover the advanced reporting using the token_status reporting.

Note

Calling ‘reporting/show?’ without any further parameters will output all raw reporting data. Of course only with a valid session cookie!

Evaluation / Reporting APIs#

Reporting is based on an index that is created and updated with token management activities. To get an exact count of the status for a period of time it may be useful to rebuild the index. This can be done by deleting the index with ‘reporting/delete_all’ or ‘delete_before’. The next change of the status of a token leads to a rebuild of the index. This can take a long time with large token databases.

Report of the current number of tokens in the specified status or period

/reporting/show?: show number of tokens in the specified status and/or realm
/reporting/period?: show number of tokens in the specified status and/or realm in a period from to
period is the time period from day to day in the format:: from=YYY-mm-dd&to=YYY-mm-dd in the calls with reporting/period in place reporting/show

http://<linotp_ip>/reporting/show?session=<session>&status=total&
sortby=timestamp&sortdir=desc&pagesize=1&page=1&realms=<realm>

http://<linotp_ip>/reporting/period?session=<session>&status=
active,assigned,active%26assigned,unassigned&from=2022-03-01&to=2022-04-01

session: Cookie of the valid admin session fetched in the same browser or in a script with ‘admin/getsession’.
status: active%26assigned,active,…
sortby: Optional, serves the readability of the output
pagesize=1&page=1: Optional
realms: “Realmname” Optional, allows the output of the specified realm.
from=...&to=...: the period of the report

Report on the maximum number of tokens

/reporting/maximum?: maximum number of tokens in the specified status

Again, tokens that are not assigned to a realm are not counted. These reports are currently not recommended for the license report.

http://<linotp_ip>/reporting/maximum?session=<session>&status=active,
assigned,active%26assigned,unassigned,active,inactive

Perform Queries#

show or period#

Displays the token counters recorded over time. The output can be filtered regarding the token states and the realms.

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]

Available parameters:

realms [optional]: Limit the counter output to the given realms.
status [optional]: Limit the counter output to tokens with of certain states.

Tip

Please make sure to use exactly the same token states for the queries as defined in the reporting policies (Reporting Policies)

Displays all available historical numbers of all tokens of all states

https://linotp.example.net/reporting/show?session=45e939b02[...]

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 30,
           "report_rows": 30
        },
        "data": [
           {
              "count": 132,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
           },
           {
              "count": 150,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "total",
              "event": "token_tokenrealm"
           },
[...]

Display token counts for certain realms

Show token count numbers for ‘realm1’ and ‘realm2’:

https://linotp.example.net/reporting/show?session=45e939b02[...]&realms=realm1,realm2

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 30,
           "report_rows": 30
        },
        "data": [
           {
              "count": 132,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
           },
           {
              "count": 150,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "total",
              "event": "token_tokenrealm"
           },
[...]

           {
              "count": 300,
              "realm": "realm2",
              "description": "",
              "timestamp": "2016-07-25 13:27:54",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
          },
[...]
}

Display token count numbers for certain states

Show count numbers for unassigned active tokens:

https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 6,
           "report_rows": 6
        },
        "data": [
           {
              "count": 11,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 11:37:58",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&active",
              "event": "token_enable"
           },
           {
              "count": 12,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 13:00:10",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&active",
              "event": "token_init"
           },
[..]
}

Display token count numbers for certain states

Show count numbers for assigned active tokens in a period:

https://linotp.example.net/reporting/period?session=45e939b02[...]
&status=active,assigned,assigned%26activei&from=2022-04-01&to=2022-05-01

{
  "version": "LinOTP 2.12.5",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "period": {
           "to": "2022-04-01T00:00:00",
           "from": "2022-05-01T00:00:00"
        },
        "realms": [
           {
              "maxtokencount": {
                 "active": 6,
                 "assigned": 6,
                 "active&assigned": 6
              },
              "name": "users"
           },
           {
              "maxtokencount": {
                 "active": null,
                 "assigned": null,
                 "active&assigned": null
              },
              "name": "admin"
           },
           ...
           {
              "maxtokencount": {
                 "active": 1,
                 "assigned": 1,
                 "active&assigned": 1
              },
              "name": "realm2_user"
           },
        ]
     }
  },
  "id": 1
}

maximum#

Display the highest number counter for token of a certain state in realms.

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE[&realms=REALMA,REALMB,...]
[&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

Available parameters:

status [optional]

realms [optional]

Show total number of tokens

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE

Show highest numbers of total tokens counted for all realms:

https://linotp.example.net/reporting/maximum?session=45e939b02[...]

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "realm1": {
           "total": 270
        },
        "realm2": {
           "total": 178
        }
     }
  },
  "id": 1
}

Show number of tokens of certain states from specific realms

https://linotp.example.net/reporting/maximum?session=45e939b02[...]
&status=inactive,unassigned&realms=realm1

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "realm1": {
           "unassigned": 15,
           "inactive": 25
        }
     }
  },
  "id": 1
}

Delete counters from database with delete_all#

Available parameters:

status: [optional, Without status only token ‘total’ is deleted]
realms: [optional, Without realms all realms are processed.]

Delete all count data

https://linotp.example.net/reporting/delete_all?session=45e939b02...
&status=*

{
  "version": "LinOTP 2.9rc2",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 586
  },
  "id": 1
}

Delete token counter of selected realms

Delete all tokens counter from realm1:

https://linotp.example.net/reporting/delete_all?session=45e939b02[...]
&status=*&realms=realm1

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 432
  },
  "id": 1
}

Delete token counter for selected states

Delete all tokens counter of the state inactive or disabled:

https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&status=inactive,disable

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 18
  },
  "id": 1
}

Delete counters from database with delete_before#

Delete entries from the database before a given date. The removal can be optionally selective regarding the realm and the token states.

https://<LINOTP>/reporting/delete_before?session=SESSIONCOOKIE&date=YYYY-MM-DD
[&realms=REALMA,REALMB,...][&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

Available parameters:

date: the date before counters are deleted in format YYYY-MM-DD
status: [optional, Without status only token ‘total’ is deleted]
realms: [optional, Without realms all realms are processed.]

Remove all count data recorded before 2016-07-22:

https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&date=2016-07-22

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 157
  },
  "id": 1
}

Remove count data for all active token from realm1 recorded before 2016-07-26:

https://linotp.example.net/reporting/delete_before?session=45e939b02[...]
&status=active&realms=realm1&date=2016-07-26

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 68
  },
  "id": 1
}

Reporting

Contents

1.17.2. Reporting#

Prerequisites#

Configuration#

Activating Reporting and Reporting access#

Current limitations#

Reporting Modes#

Evaluation / Reporting APIs#

Perform Queries#

show or period#

maximum#

Delete counters from database with delete_all#

Delete counters from database with delete_before#