How to ensure an AD change to the userPrincipalName Attribute is reflected properly in Confluence
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Purpose
This article will help ensure Confluence properly maps usernames in the user directory when a business requires a change of the userPrincipalName Attribute in Active Directory from sAMAccountName to mail.
For example, a username change from jsmith to john.smith@example.com in AD needs to be reflected in Confluence as the user's new username.
Environment
Usage of this article depends on your current setup and how the change is performed.
- If the existing User Unique ID Attribute does not change, then your users will be automatically renamed (rather than creating duplicates). We strongly recommend this approach.
- If the existing User Unique ID Attribute will change, then you will end up with duplicate users. This will require manual DB manipulation to migrate content ownership and permissions. Thus. we do not recommend this approach.
Solution
Please follow best practices for Change Management and test and validate these settings in a Test/Development and Staging environment prior to rolling any changes into a Production environment. This is to validate these changes and ensure that they will function well within your infrastructure prior to placing these changes in production.
Changing user names in Confluence - Recommended Method
To migrate from sAMAccountName (e.g. jsmith) to email address (e.g. john.smith@example.com), and maintain content ownership, review the steps below:
- Navigate to
> General configuration > User Directories - Edit the appropriate directory
- Expand User Schema Settings
- Locate the User Unique ID Attribute:
- Verify that this attribute is configured to use an actual unique attribute (e.g. objectGUID) which will not change with the change from username to mail.
- Change the User Name Attribute from sAMAccountName to mail:
- Save your changes
- Perform a directory sync
- Validate the changes were successful