Renaming LDAP users in Jira and Confluence

Slightly different from the usual stuff but I’ve just had to do this and it turned out to be rather complex!

Firstly apologies for the long gap in posts.   Various factors have been soaking up my time.

Anyway…   I am the admin for the Jira and Confluence servers that are primarily used by engineering but also used for QA, health & safety and even facilities management.   Recently part of the company was split off and as such they wanted to take their part of Jira and Confluence with them.

The first issue is you can’t easily split Jira into bits.   I had to clone the server, rename it and then strip out the unwanted projects manually.   It would be nice if you could package up a whole project and move it to a different instance.   Same goes for confluence.

The biggest problem was the IT person for the spinoff decided to change the usernames for everyone!   We used LDAP authentication from both Jira and Confluence as it gives a single username and password for your PC as well as the logins for the applications.

The original usernames were in the format:


The new usernames are in the format:


In theory Jira can cope with a username change via LDAP as it uses a unique ID from the LDAP (Active directory in out case) information.   And it you change the username it should pick this up and update the internal user database.

BUT…. the hew LDAP server was created from scratch so the unique IDs were lost.   Meaning we had a problem.

I was recommended to use Bob Swift’s Jira CLI tool but this wanted to edit the LDAP data rather than renaming the user in the Jira database.

The easy option was to go ‘hey, just use new usernames and manually clean up the mess’ but I was not going to give in.

The solution!

Firstly take a backup of your database!!   Really, do not skip this!   I had to roll back a few times before I cracked it.

Usual disclaimer.   I am not responsible if you totally fudge up your Jira or Confluence.   If you don’t take a backup and mess something up then you are going to be in trouble and don’t come crying to me.

Shut down Jira and confluence and take the backup.

Look in the cwd_directories table and locate the ID for the internal directory.   For Jira this was 1, for Confluence it was some silly number I have in my note book.

Find all the users you want to migrate in cwd_users and change the directory ID to match the internal directory ID.

Restart Jira/Confluence.

Log in using an admin account in the internal directory.

Disable the old LDAP user directory so you’re only dealing with the users you want.   Now go into the user settings and manually rename them.   Jira and Confluence will very kindly remap all the usernames linked to issues, comments etc..

So yay, you now have your renamed users and the contents of your Jira and Confluence have not been trashed.

The final bit differs between Jira and Confluence.   In both add the new user directory.   I decided as it was for only 18 users I would use the ‘local user database with LDAP password auth’ option.

In Jira 7 there is a ‘migrate users’ option on the user directories page.   Just use this and move the users from the internal directory to the new LDAP one.   Job done!

This does not exist in confluence so it is time to shut it down and go mess in the database.   Taking a backup before again just in case.

Do the same as before.   Identify the ID for the new user directory and edit the directory field in the users.   Then restart and all should be good.

So best of luck!