要約

You've setup JIRA connected to an external LDAP User Directory and now your organization is migrating users to another domain or LDAP directory where the username format is different.

Using "Charlie Atlassian" as the example user, in the original directory his username is "catlassian", but in the new directory it will be "charlie.atlassian".  

You want to make sure that once you've migrated to the new directory, Charlie still has all the same issues assigned, history and so on. Simply adding the new directory then disabling the original directory will not transfer over issue associations.

This guide describes two methods to switch user authentication from an Active Directory to another Active Directory and keep user history.  You will need to log in as a user with the 'Jira System Administrators' global permission to access the Settings menu.

回避策

Using a temporary attribute

Using a temporary additional attribute to change the usernames used in the original(old)directory before migrating to the new directory allows you to preserve associations in the course of migrating.

1. Identify an attribute you can use, or create a new one, in your original external directory.  In Active Directory, for example, there are a number of "extension attributes" named things like "extensionAttribute2" which can be used. 
2. Populate the above-identified attribute with the username for the new domain/directory.
3. Modify your JIRA User Directory Configuration in () (Administration) > User Management > User Directories so that the "User Name Attribute" and "User Object Filter" (in User Schema Settings) is changed to the temporary attribute.
   
4. Synchronize the directory.  At this point you should see your user's usernames updated to the new format. 
5. Verify all users are able to login and have not lost any data.
   1. Users will need to log in by using whatever has been set in their "extension attributes".
6. Add a new User Directory, as detailed in Connecting to an LDAP directory to add the new Active Directory.
7. If you sync at this point, you should not see new Users in JIRA because they will have the same usernames as the Users synced from the original directory.
8. Promote the new directory above the old directory.
   

The result of this should be that your users are able to log in using the new username, which will be authenticated against the new directory server, and you are safely able to disable and/or remove the old directory connector (after testing that everything is working as expected). 

Using JIRA's internal directory

If for whatever reason you aren't able to make use of another directory attribute in your external directory for the purposes of this migration, it is still possible to perform the migration but instead using JIRA's Internal Directory as an intermediate step for the purpose of updating usernames to match the new directory. 

1. Start with the JIRA Internal Directory ordered below the external directory.
2. Disable the external directory. 
3. Create users in the Internal Directory with their username matching the original/old external directory.  It may be worthwhile to script this using something like the JIRA REST API to avoid manually entering these. 
4. Promote the Internal Directory above the external directory.  At this point if you had manually set a password for the Internal Directory users, you should be able to log in as one and verify that associations are still intact. 
5. Rename each user to use the user name format of the new external directory.  As above, it's probably best to script or otherwise automate this step.
6. Add the new directory connector. If you sync at this point, you should not see new Users in JIRA because they will have the same usernames as the Users in the JIRA Internal Directory.
7. Promote the new directory connector above the JIRA Internal Directory. 

The result here should be the same as above, in that users are able to log in with their new usernames, be authenticated against the new directory connector, and retain their existing associations.  One notable difference here is that if ever you remove the external directory connectors or otherwise promote the Internal Directory to the top of the list, all of those users will still be in there and may need to be cleaned up at that point. 

Caveats and Limitations

• Group membership information won't be maintained using this approach.  
• If Groups are managed entirely externally, you'll need to make sure before migrating that the correct groups are configured in the new directory before switching JIRA over. 
• If Groups are managed locally in JIRA, you may be able to make use of the approach described in JIRA KB - Migrate local group memberships between directories.
• If you use userPrincipalName as the new attribute, there is known BUG JRASERVER-63858 - Getting issue details... STATUS and there is a recommendation not to use userPrincipalName for User Name Attribute.