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

whitelist by client ID and regex. Any client on the whitelist is never removed. This lets you retain certain clients (such as templates, or testing clients) that are rarely accessed but need to stay. Whitelists are processed before any other rule.
blacklist by client ID and regex. Any client on the blacklist is always removed. This allows, for instance, an adminstrator to make single use temporary clients with specific ids and have them removed. The blacklist is processed after every other rule.
unused clients are defined as being within a certain grace period of creation, but never having been accessed.
abandoned clients are defined as not having been accessed after a certain date. E.g. clients that have not been accessed in over a year.

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.

created only before or after a given date.
Allows for filtering clients that were last accessed only before or after a given date.
Versioned clients may optionally be processed as well. Remember though that versioned clients are accessed much less frequently (if ever) than active clients, so it is quite likely setting this to true will remove more of them than you would like.
May optionally be run on a thread either at intervals or by alarms.
The CLI may be used to run this as well. Some administrators prefer to only run this manually.

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.

Dates

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"
                         deleteVersions="false"
                         enabled="true"
                         interval="4 hr">
        <whitelist>
           <clientID>template:/basic</clientID>
           <clientID>template:/cern</clientID>
           <regex>^localhost.*</regex>
           <regex>.*comanage.*</regex>
        </whitelist>
        <blacklist>
           <clientID>dev:/registration/test/42</clientID>
           <regex>^test.*</regex>
        </blacklist>
    </unusedClientCleanup>

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.

OA4MP

Project Documentation