Reporting Policies

1.6.9. Reporting Policies#

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

The comprehensive API documentation can be found here:

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

The reporting API is to activated by policies and can be accessed by the token managers. The actions allowed for each management account can be configured by policies as described below.

Please have a look at Reporting for example queries.

Activate Reporting#

The available queries must be activated with policies in the scope reporting.

Total Number of Tokens#

This makes the reporting of the total numbers of tokens available.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.

  • Action: token_total

  • User: This is a comma separated list of usernames or resolver names the token count should be performed for. Please see Users in policies. This should be set to * to cover all users.

  • Realm: Enter the names of the realms where reporting should be available.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Token in certain States#

This policy configures the counting of tokens in certain states. If a state is not configured here it can not be used for a query.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.

  • Action: token_status

    token_status can be a list of:

    • assigned

    • unassigned

    • active

    • inactive

    … or sensible combinations of those states.

States can be joined with “&”.

The syntax is:

token_status = STATE1[&STATE2][, token_status=,STATE3[&STATE4]]...

  • User: This is a comma separated list of usernames or resolver names the token count should be performed for. Please see Users in policies. This should be set to * to cover all users.

  • Realm: Enter the names of the realms where reporting should be available.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

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

Example:

This makes all possible state combinations available for queries.

[reporting]
scope = reporting
action = "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"
user = *
realm = *
client = ""
time = ""
active = True

Configure Access#

Token manager can be allowed to query selected activated information using the reporting interface. This is configured with policies in the scope reporting.access.

Show Token#

The action show returns the numbers of tokens with a certain state. The search can be limited to certain realms.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.access.

  • Action: show

  • User: This is a comma separated list of usernames or resolver names who are allowed to perform the queries. Please see Users in policies. This can be set to * to cover all management users.

  • Realm: Enter the names of the realms the reporting should be allowed for.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Example

Allow the users managerA and managerB to query token information for realm realmA and realmB:

[reporting_access]
scope = reporting.access
action = "show,"
user = managerA, managerB
realm = realmA, realmB
client = ""
time = ""
active = True

Please have a look at Reporting for example queries.

Show Maximal Number of Tokens#

The action maximum returns the the highest number counted of tokens with a certain state. The search can be limited to selected realms. This is useful for accounting purposes. E.g: the maximal number of active tokens can be queried at the end of the month. After this the counter is deleted and can be reused for the next month.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.access.

  • Action: maximum

  • User: This is a comma separated list of usernames or resolver names who are allowed to perform the queries. Please see Users in policies. This can be set to * to cover all management users.

  • Realm: Enter the names of the realms the reporting should be allowed for.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Example

Allow the user managerA to query the highest number of tokens through time for realms realmA and realmB:

[reporting_access]
scope = reporting.access
action = "maximum"
user = managerA
realm = realmA, realmB
client = ""
time = ""
active = True

Please have a look at Reporting for example queries.

Delete data from Reporting Database#

Delete all data#

The action delete_all removes all data from the reporting database. This is useful for cleaning the database, eg. if the data are already processed or to reset the maximum counter.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.access.

  • Action: delete_all

  • User: This is a comma separated list of usernames or resolver names who are allowed delete entries of the database. Please see Users in policies. This is set to * to cover all management users.

  • Realm: Enter the names of the realms of which the reporting can be deleted.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Example

Allow the user managerA and managerB to delete reporting information for realms realmA and realmB:

[reporting_access]
scope = reporting.access
action = "maximum"
user = managerA, managerB
realm = realmA, realmB
client = ""
time = ""
active = True

Please have a look at Reporting for example queries.

Delete data before a certain date#

The action delete_before removes all data from the reporting database older than the given date. This is useful for cleaning the database, e.g. if the data are already processed or to reset the maximum counter.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to reporting.access.

  • Action: delete_before

  • User: This is a comma separated list of usernames or resolver names who are allowed delete entries of the database. Please see Users in policies. This is set to * to cover all management users.

  • Realm: Enter the names of the realms of which the reporting can be deleted.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Example

Allow the user managerA and managerB to delete reporting information before a certain date for realms realmA and realmB:

[reporting_access]
scope = reporting.access
action = "delete_before"
user = managerA, managerB
realm = realmA, realmB
client = ""
time = ""
active = True

Please have a look at Reporting for example queries.