User Cleanup
To clean up users and groups, you must be logged in as a user with the Confluence System Administrator global permission.
Use Instance Optimizer to find and clean up Confluence users that may be inactive, duplicate, unused bot or never-used accounts. You can also find and clean up groups and directories that have no members, or no active members.
User cleanup scans your instance and shows users that match one or more cleanup recommendations. From the scan results, you can review users and deactivate, reactivate or delete them in bulk.
You can also review your groups and directories, export any of these views to CSV, delete groups and disable directories.
Scan users and groups
To scan users and groups:
Go to Confluence administration > General configuration.
In the sidebar, under Instance Optimizer, select User cleanup.
Select Run scan.
The scan creates a point-in-time result set. After changing users, groups or the cleanup limits, run a new scan to refresh the results. Only one scan runs at a time across your cluster.
The scan checks for users, groups and directories that match these recommendations:
Recommendation | Description |
|---|---|
Total users per instance | User counts exceeding 1M per instance |
Potentially inactive users | Users that have not logged in for more than 6 months |
Bot accounts | Helps identify bot accounts and their recent activity |
Never logged-in users | Users created more than 6 months ago that have never logged in |
Duplicate accounts | Accounts that share an email address with at least one other account |
Total users per group | Groups that have more than 290,000 members |
Groups with no members | Groups that don't have any members |
Groups with no active members | Groups that only have members who haven't logged in for more than 6 months, or have never logged in |
Total groups per directory | Directories that have more than 250,000 groups |
Directories with no users | Directories that don't have any users |
Directories with no active users | Directories that only have users who haven't logged in for more than 6 months, or have never logged in |
Configure limits
User cleanup uses default limits to identify users that may need review.
Limit | Default value |
|---|---|
Inactive months | 6 |
Created months | 6 |
Bot groups and patterns | Empty |
Total users | 1M |
Users per group | 290k |
Groups per directory | 250k |
To change these limits, open User cleanup, then select Configure User cleanup.
Configure bot identification
Bot identification tells User cleanup which accounts are service or automation accounts, so they surface under the Bot accounts recommendation instead of looking like ordinary inactive users. No account is treated as a bot until you add at least one rule.
To set it up, open User cleanup, select Configure User cleanup, then use the Bot identification section.
There are two kinds of rules, and an account is flagged if it matches either one:
Rule | Description |
|---|---|
Bot groups | Accounts belonging to listed Confluence groups. Search and add groups by name (max 100). |
Bot username patterns | Regular expressions matched against each account's username and display name (max 25). |
A pattern matches anywhere in the name unless you anchor it, so svc- also matches mysvc-1. Use ^svc- to match only names starting with svc-, or -bot$ for names ending in -bot.
Select Save bot identification to apply your changes. Bot rules are read when a scan starts, so run a new scan to see the effect. Results from earlier scans don't change.
Apart from bot identification and bulk action limits, we don't recommend adjusting default limits in production instances without consulting Atlassian support. The default limits are optimized for performance.
Review and filter results
After a scan finishes, Instance Optimizer shows the matching users and the top recommendations.
You can filter results by:
User name
Status
Directory
Group
Licensed
Optimization area
Last active
Directory and group filters
The Group filter becomes available after you select a single directory. Type in the filter to search for a group by name within that directory. You can select multiple groups to narrow the results.
Users in more than one directory
If the same username exists in more than one directory, Confluence treats one of those accounts as the authoritative one. User cleanup shows the other entries for information only, and skips them when you deactivate or reactivate users, so the change always applies to the account Confluence actually uses.
Review groups and directories
Group and directory recommendations open a group or directory view rather than filtering the user table. The group view lists each group with its member counts, and the directory view lists each directory with its group and member counts and whether it's currently active.
From these views you can review groups with no members, groups with no active members, directories with no users and directories with no active users. Select a member count to see those users in the user table. Each view has its own filters, sorting and CSV export.
Export results to CSV
You can export the user table, the group view or the directory view to a CSV file for review.
To export results:
Open the view you want to export, and apply any filters.
Select Export CSV.
The export includes the rows matching your current filters, in the order shown. Without filters, it includes every row from the latest scan.
Exports are limited to 50,000 rows and 250 MB by default. If a view holds more rows than the limit, Export CSV is disabled until you narrow the filters. An export can't start while a scan, a cleanup action or another export is running.
To change the export limits, set the following system properties, then restart Confluence:
confluence.optimizer.plugin.user.cleanup.csv.export.max.rows, capped at 100,000 rows.confluence.optimizer.plugin.user.cleanup.csv.export.max.bytes, capped at 500 MB.
Bulk actions: Users
You can select up to 1,000 users for cleanup at a time. Selected users can be deactivated, reactivated or deleted.
Before deactivating or deleting users, we recommend exporting them to a CSV file. Deleted users can't be recovered from Instance Optimizer.
Two restrictions always apply and can't be turned off:
You can't include your own account in a cleanup action.
You can't deactivate, reactivate or delete another Confluence system administrator. Use Confluence user management for those accounts.
Only one cleanup action runs at a time, and it can't be cancelled once it has started. Users are processed one at a time, so a problem with one user doesn't stop the rest. When the action finishes, Instance Optimizer reports how many users succeeded, failed and were skipped, along with the reason. The latest result stays available if you leave the page and come back.
Deactivate users
Deactivating a user prevents them from signing in and releases their license seat. Their content stays in place, and they can be reactivated later.
A user can only be deactivated when their user directory allows Confluence to change the account. Users in a read-only directory are skipped, and must be changed in the source directory instead.
Reactivate users
Reactivating a user lets them sign in again. A licensed user will consume a license seat once reactivated.
As with deactivation, the user's directory must allow Confluence to change the account.
Delete users
Deleting a user permanently removes the account and can't be undone. Their spaces, pages and comments stay in place. If you may need an account again, deactivate it instead.
Users in a read-only directory can't be deleted.
Bulk actions: Groups and directories
From the group and directory views, you can select up to 1,000 groups or directories for cleanup at a time. Selected groups can be deleted, and selected directories can be disabled. Both actions ask for confirmation before they run, and follow the same one-at-a-time rules as user actions.
Before deleting groups or disabling directories, we recommend exporting them to a CSV file. Deleted groups cannot be recovered.
Delete groups
Deleting a group removes it from its directory. Any permissions, notifications or restrictions granted through the group stop applying to its members immediately.
Groups in a directory that doesn't allow groups to be deleted, and groups that were already deleted, can't be selected.
Disable directories
Disabling a directory stops it from authenticating. Its members can't log in while the directory is disabled, even if their account is active. The directory itself isn't deleted, and you can enable it again from User directories in Confluence administration.
You can't disable the directory that holds your own account.
Change the bulk action limits
To change the maximum number of users, groups or directories in one cleanup action, open User cleanup, select Configure User cleanup, then use the Bulk actions section. Each limit accepts 1 to 5,000. Changes apply to the next action without a new scan.
You can also set the limits with these system properties, then restart Confluence. A value saved on the configuration page takes precedence.
confluence.optimizer.plugin.user.cleanup.bulk.action.max.usersconfluence.optimizer.plugin.user.cleanup.bulk.action.max.groupsconfluence.optimizer.plugin.user.cleanup.bulk.action.max.directories
Audit logs
User cleanup adds entries to the Confluence audit log when a scan starts and finishes, when you change a limit or a bot identification rule, and when a cleanup action starts and completes. Each deleted group and disabled directory is also recorded individually.
Every entry title starts with User cleanup, so searching the audit log for "User cleanup" shows the full history.
Scheduled scans
User cleanup includes a preconfigured scan schedule:
Task | Default schedule |
|---|---|
Scan | Weekly on Sundays at 3:00 AM |
The scheduled scan runs once across your cluster, in Confluence's default time zone.
To change the schedule:
Go to Confluence administration > General configuration > Scheduled Jobs.
Find Instance Optimizer user cleanup scan and select Edit.
Enter a new cron expression, then save.
By using a cron expression, you can specify exactly when the scan occurs. For example, the default value 0 0 3 ? * SUN schedules the user cleanup scan every Sunday at 3:00 a.m.
From the same page you can also run the scan immediately, or disable the schedule. Disabling it doesn't affect manual scans. Learn more about scheduled jobs