Removing unused clients with the UUC

The UUC (Unused Client Cleanup) is a facility/tool for removing clients that have either never been accessed or have not been access according to various criteria. There are many cases where automatic removal of clients is desireable. For instance, if OA4MP is configured to be a standalone issuer, it may permit only public clients and auto-approve them on registration. A common case though is that a user registers a client and then never actually uses it. This causes a massive accumulation of clients in the store and no easy way to remove them. It is suggested to enable this at the initial server deployment so that it is not grafted onto an already running OA4MP install. See the onlyCreatedAfter property below.

What can it do? Here are the supported rules that may be configured

In addition to the rules, each may have filtering applied to restrict the clients to which the rule applies. You may also set filtering at the top level for alll rules.

The XML configuration. This is for the top-level tag unusedClientCleanup

Attribute Required? Default Description
alarms N false Comma delimited list of times of the form hh:mm:ss. Times are on a 24 hour clock and fractions of seconds are ignored. Monitoring will happen daily at these times. These have right of way over setting an interval.
blacklist N - A collection of either client_id elements or regex elements that are always deleted when found. See the note below on the syntax.
debug N false This enabled low-level debugging of the thread used in the UUC. It is intended for tracking down odd server behavior and will be quite verbose, so don't enable this unless you really need to. Note especially that this is entirely independent of the server debug/logging flags. the reason is that you do not want this spitting out messages unless you plan it.
enabled N false Whether or not to enable this. If disabled, then the thread on the server will not be run. In the CLI you can override this and run the cleanup manually.
gracePeriod N 6 hours Specifies that time an unused client may be on the system before getting removed. Default is in seconds, but you can specify any standard unit. E.g. If this is 3600 (one hour), then unused clients that were created/modified more than 3600 seconds ago are removed. See A note on time and units
interval N false The length of time for the thread to sleep between looking for unused clients. You may set this or set the alarms. See A note on time and units
testModeOn N false A boolean. If set to true, then no actual deletes are done. This overrides all configurations and allows you to toggle printing the results vs. having them executed. In the CLI you can print out the client ids that would have been removed.
whitelist N - A collection of either client_id elements or regex elements that are never deleted when found. See the note below on the syntax.

Common attributes for all rules

Attribute Required? Default Description
action N delete Specifies one of delete, acrchive or test as the arctions for this rule. The results are
  • delete = delete the client. Nothing of the client remains. Permissions are removed as well
  • archive = archive the client. The client still remains, but is now in the archive for the store
  • test = run the filter, print out what would have been done. No changes to the store are made.
deleteVersions N false If true, then versions of clients are also removed if they match the criteria of the configuration.

Filtering. This is for the tag filter which may be in any rule or if in the unusedClientCleanup element, applies to all unless overridden.

Attribute Required? Default Description
archived N -- Options are
  • only = restrict processing to archived clients only
  • skip = no archived clients are included in this rule
  • include = archived clients are processed in this rule
date N -- Element that refers to a date.

Note on absolute dates and relative times You may use either. Dates are ISO 8601, e.g., 2024-02-08T20:22:48-05:00 or 2024-02-07T14:12:11Z.

White and black list syntax

The whitelist and blacklist configurations have the same set of internal tags. One reason for having them in tags is that they may be enclose in CDATA tags if there is an issue with escaping:

Attribute Required? Default Description
clientID N N/A The client identifier.
regex N N/a A regular expression.


Attribute Required? Default Description
when N -- When to apply the date. Options are
  • after = dates after the given date, inclusive
  • before = dates before the given date, inclusive
type N N/a The type of date. Options are
  • accessed = last accessed date. This include if logins for the client
  • created = the date of creation for the client
  • modifed = the last actual modification, i.e., update to this client

Adding the UUC facility to your existing OA4MP server

A not uncommon situation is that you have had an OA4MP server running for a long time and have noticed all manner of dead client. Obviously, this facility is what you want, but if the version is older (so before 5.4.3) then the statistics this facility needs are not in place and may cause problems. There are two way to do this.

(1) The truly safe way

Upgrade OA4MP, let it run for some specified period (a couple of weeks) in which you are sure that everyone who is using the system would have logged in, then enable the UUC. Probably in test mode initially (look in the logs for the stats).

(2) Another way

You could enabled this moving forward, so just set the onlyCreatedAfter value to the current date. No client created before this date will be touched. This would allow you to vet those as needed while ensuring that new clients are monitored and removed if they fit your criteria.

Typical example configurations

    <unusedClientCleanup gracePeriod="6 hr"
                         interval="4 hr">

In this example, every 4 hours the thread wakes up and checks. If a client has been created and not used within the grace period (6 hours) then it is removed. Versions are ignored. There is a white list consisting of a few specific clients (such as templates for creating other clients), any client id that starts with localhost and any client for comanage. The blacklist removes a specific client (used for testing the registration endpoint only) as well as any client id's that start with test.