12.4. Tools¶
eduMFA comes with a list of command line tools, which also help to automate tasks. The tools can be found in the directory edumfa/bin.
12.4.1. edumfa-token-janitor¶
eduMFA comes with a token janitor script. This script can find orphaned tokens, unused tokens or tokens of specific type, description or token info.
It can unassign, delete or disable those tokens, it can set additional tokeninfo or descriptions and perform other tasks on the found tokens.
It can also set the tokenrealms of the found tokens.
If you are unsure to directly delete orphaned tokens, because there might be a glimpse in the connection to your user store, you could as well in a first step mark the orphaned tokens. A day later you could run the script again and delete those tokens, which are (still) orphaned and marked.
The token janitor script can also filter for token attributes and attribute values. It is also possible to check just for the existence or not-existence of a certain tokeninfo-value.
12.4.1.1. Find¶
With the token-janitor you have the possibility to search for tokens in different ways. You can find tokens by providing filter parameters. Note, that you can combine as many filter parameters as you want to. This way you can reduce the set of found tokens. Several filter parameters allow to search with regular expressions.
The parameters tokentype and username are exact matches and will be applied before any other filters. This means
that only tokens of given tokentype and username will be processed.
If neither of those two parameters is given all tokens will be processed and checked against other filters.
Actions will then be performed only on this reduced set.
These are important filter parameters:
12.4.1.1.1. Orphaned¶
Searches for tokens, that are orphaned. Orphaned tokens are assigned to a user. But the user does not exist in the user store anymore. This can happen e.g. if an LDAP user gets deleted in the LDAP directory.
Example:
edumfa-token-janitor find --orphaned 1
This returns all orphaned tokens for later processing.
12.4.1.1.2. Active¶
Searches for tokens that are either active or inactive, this means enabled or disabled.
Example:
edumfa-token-janitor find --active False
This returns all disabled tokens. May you later want to delete these disabled tokens.
12.4.1.1.3. Assigned¶
Searches for tokens that are either assigned to a user or unassigned.
Example:
edumfa-token-janitor find --assigned False
This returns all tokens, that are not assigned to a user. You could combine this with other filters
like the tokenkind to find out how many hardware tokens are not assigned and still available for assignment.
12.4.1.1.4. Last_auth¶
Searches for all tokens, where the last authentication happens longer ago than the given value:
Example:
edumfa-token-janitor find --last_auth 10d
This will find all tokens, that did not authenticate within the last 10 days. You can also use “h” and “y” to specify hours and years.
Since the last_auth is an entry in the tokeninfo table you could also search like this:
edumfa-token-janitor find --tokeninfo-key last_auth --tokeninfo-value-after '2021-06-01 18:00:00+0200'
12.4.1.1.5. Description¶
Searches through all tokens and returns the ones with the selected description.
Example:
edumfa-token-janitor find --description '^fo.*'
Return all tokens where the description begins with “fo”.
12.4.1.1.6. Serial¶
Searches through all tokens and returns the ones with the selected serial.
Example:
edumfa-token-janitor find --serial OATH0013B2B4
Return all tokens with the serial OATH0013B2B4.
By searching for regular expressions, it is e.g. possible to find Yubikeys, which might be a tokentype “HOTP”, but where the serial starts with UBOM.
Example:
edumfa-token-janitor find --serial '^UBOM.*'
12.4.1.1.7. Username¶
Searches through all tokens and returns the ones belonging to the given username.
The username should contain the realm in the format user@realm. If no realm is given the default realm is used.
Example:
eduMFA-token-janitor find --username testuser@testrealm
Return all tokens belonging to the user testuser in the realm testrealm.
Example:
eduMFA-token-janitor find --username testuser
Return all tokens belonging to the user testuser in the default realm.
12.4.1.1.8. Tokentype¶
Searches through all tokens and returns the ones with the selected tokentype.
Example:
edumfa-token-janitor find --tokentype hotp
Return all tokens with the tokentype hotp.
12.4.1.1.9. Tokenattribute¶
Match for a certain token attribute from the database table token.
There are different ways of filtering here.
12.4.1.1.9.1. tokenattribute-value REGEX|INTEGER¶
The value of the token-attribute which should match.
Example:
edumfa-token-janitor find --tokenattribute rollout_state --tokenattribute-value clientwait
Search for all tokens with the tokenattribute-key rollout_state and the associated tokenattribute-value clientwait.
Note that it is also possible to work with regular expressions here.
12.4.1.1.9.2. tokenattribute-value-less-than INTEGER¶
Match if the value of the token attribute is less than the given value.
Example:
edumfa-token-janitor find --tokenattribute failcount --tokenattribute-value-less-than 10
Search for all tokens with the tokenattribute-key failcount and the associated tokenattribute-value below 10.
This way you can find tokens, where the fail counter is less than 10 and thus the tokens are not blocked.
12.4.1.1.9.3. tokenattribute-value-greater-than INTEGER¶
Match if the value of the token attribute is greater than the given value.
Example:
edumfa-token-janitor find --tokenattribute failcount --tokenattribute-value-greater-than 10
Search for all tokens with the tokenattribute-key failcount and the associated tokenattribute-value greater than 10.
This way you can find tokens, where the fail counter is greater than 10 and thus the tokens are blocked.
12.4.1.1.10. Tokeninfo-key¶
This matches on values for tokeninfo, which is actually the database table tokeninfo.
There are different ways of filtering here.
12.4.1.1.10.1. has-tokeninfo-key¶
Filters for tokens that have given the specified tokeninfo-key no matter which value the key has.
Example:
edumfa-token-janitor find --has-tokeninfo-key import_time
Searches for all tokens that have a tokeninfo-key import_time set.
Note, that it is not important, what value the “import_time” actually has!
12.4.1.1.10.2. has-not-tokeninfo-key¶
Filters for tokens that have not set the specified tokeninfo-key.
Example:
edumfa-token-janitor find --has-not-tokeninfo-key import_time
Searches for all tokens that didn’t store the tokeninfo-key import_time.
12.4.1.1.10.3. tokeninfo-value REGEX|INTEGER¶
The tokeninfo-value to match.
Example:
edumfa-token-janitor find --tokeninfo-key tokenkind --tokeninfo-value software
Search for all tokens with the tokeninfo-key tokenkind and the associated tokeninfo-value software.
12.4.1.1.10.4. tokeninfo-value-less-than INTEGER¶
Interpret tokeninfo-values as integers and match only if they are smaller than the given integer.
Example:
edumfa-token-janitor find --tokeninfo-key timeWindow --tokeninfo-value-less-than 200
Search for all tokens with the tokeninfo-key timeWindow and the associated tokeninfo-value below 200.
12.4.1.1.10.5. tokeninfo-value-greater-than INTEGER¶
Interpret tokeninfo-values as integers and match only if they are greater than the given integer.
Example:
edumfa-token-janitor find --tokeninfo-key timeWindow --tokeninfo-value-greater-than 100
Search for all tokens with the tokeninfo-key timeWindow and the associated tokeninfo-value greater than 100.
12.4.1.1.11. Actions¶
Actions are performed by the token janitor on all found tokens.
mark - disable - delete - unassign - export - listuser - tokenrealms
12.4.1.1.11.1. mark¶
Mark makes it possible to mark the found tokens in order to carry out further actions with them later.
The tokens are marked by setting a tokeninfo-key and an associated tokininfo-value.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action mark --set-tokeninfo-key unused --set-tokeninfo-value True
A new tokeninfo-key and the associated tokeninfo-value would be added for the token OAUTH0004C934
and are now marked for later processing. If the token already containd this tokeninf-key, the value
would be changed.
12.4.1.1.11.2. disable¶
With disable the found tokens can be disabled.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action disable
The token with the serial OAUTH0004C934 will be disabled.
12.4.1.1.11.3. delete¶
With delete the found tokens can be deleted.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action delete
The token with the serial OAUTH0004C934 will be deleted.
12.4.1.1.11.4. export¶
With export the found tokens can be exported as csv, yaml or pskc.
CSV will only export HOTP and TOTP tokens. The PSKC file exports HOTP, TOTP and password tokens (PW). YAML in theory can export all token types and all tokeninfo.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action export > OAUTH0004C934.xml
The token with the serial OAUTH0004C934 will be exported and saved in an xml file.
Note
With PSCK you need your encryption key for re-import.
Note
You can also use YAML export or re-encrypting data. See Re-Encrypting data.
12.4.1.1.11.5. listuser¶
With listuser the found tokens are listed in a summarized view.
Example:
edumfa-token-janitor find --action listuser
lists all tokens in a summarized view.
12.4.1.1.11.5.1. sum¶
Sum and listuser together
For all found tokens the token janitor aggregate’s the users and lists how many tokens this user has.
A user without any assigned token is not listed here!
Example:
edumfa-token-janitor find --sum --action listuser
12.4.1.1.11.6. tokenrealms¶
Tokenrealms can be used to assign tokens to different realms.
To do this, the tokenrealms function is also required.
Please note that without a previous selection of a certain token, all found tokens will be assigned to the realm.
Example:
edumfa-token-janitor find --serial OATH0005B88E --action tokenrealms --tokenrealms defrealm
Setting realms of token OATH0005B88E to defrealm.
You can also assign a list of realms by comma separating.
Example:
edumfa-token-janitor find --serial OATH0005B88E --action tokenrealms --tokenrealms defrealm,realmA,realmB
12.4.1.1.12. Set¶
With the tokenjanitor it is possible to set new tokeninfo-values, tokeninfo-keys and descriptions.
It is important to note that this is only possible with a previously marked token.
12.4.1.1.12.1. set-tokeninfo-key and set-tokeninfo-value¶
Set a new tokeninfo-key and a new tokeninfo-value or update the tokeninfo-value of an existing key.
This will only work together it is not possible to set a tokeninfo-key or a tokeninfo-value individually.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action mark --set-tokeninfo-key import_time --set-tokeninfo-value $(date --iso-8601=minutes)
Mark the token with the serial OATH0004C934 and set a new tokeninfo-key import_time and a
new tokeninfo-value $(date --iso-8601=minutes).
12.4.1.1.12.2. set description¶
Set a new description.
It is important to note that this is only possible with a previously marked token.
Example:
edumfa-token-janitor find --serial OATH0004C934 --action mark --set-description L4
Mark the token with the serial OATH0004C934 and set the description example.
12.4.2. edumfa-get-unused-tokens¶
The script edumfa-get-unused-tokens allows you to search for tokens,
which were not used for authentication for a while. These tokens can be
listed, disabled, marked or deleted.
You can specify how old the last authentication of such a token has to be. You can use the tags h (hours), d (day) and y (year). Specifying 180d will find tokens, that were not used for authentication for the last 180 days.
The command:
edumfa-get-unused-tokens disable 180d
will disable those tokens.
This script can be well used with the Script Handler Module.