Fisheye 4.0 and later versions, include a new user directories handling mechanism. Due to important differences in the way users and groups are stored in the Fisheye database, migrating from a pre-4.0 version involves migrating the user directories configuration, the users and/or groups themselves as well as users' permissions. Migration is performed automatically as part of upgrading to Fisheye 4.0 (or later), and in most cases will execute smoothly and will require no additional action. 

This page describes the user directories management process, and is primarily intended to assist with troubleshooting.

User directories

Fisheye 4.0 introduces the concept of user directories for storing users and groups. In Fisheye versions earlier than 4.0, as well as built-in user management, you could define one of many external authentication methods, such as Jira/Crowd, LDAP, etc. In Fisheye 4.0 an ordered list of user directories can be defined, each of different type (Jira, LDAP, etc.). This section describes how existing authentication method settings are mapped to the new user directories configuration.

By default, the Internal Directory is always created for local users storage. Additional directories may be created if an authentication method was previously configured.

LDAP authentication

If LDAP authentication was previously configured, an LDAP directory is set up in "Read only with local groups" mode, which means that the users it contains cannot be altered inside Fisheye, but they can be added to local groups. The user directory gets the "Generic LDAP" type by default, so you are encouraged to manually change that to the LDAP type actually used (e.g. Open LDAP or MS Active Directory).

As of Fisheye 4.0, per-repository LDAP query permissions are removed, so all users that only had access to repositories based on those (as opposed to having access based on belonging to groups) will lose their access. Administrator should manually configure appropriate access levels via group-based repository permissions.

All existing LDAP connection properties are migrated except for the auto-add option (it's not possible now to disable forcing the user synchronization after the first login) and the automatic synchronization switch (it's always on).

Jira/Crowd authentication

If Jira/Crowd authentication was previously configured, a Remote Crowd directory is set up.

As with the LDAP case above, all properties are migrated except for the auto-add option and the automatic synchronization switch (both are now always on).

Custom / AJP authentication

If custom or AJP authentication was previously configured, no additional directories are created. Authentication properties can be still modified through Admin > Security Settings > Authentication > Authentication Settings.

Host-based authentication

As of Fisheye 4.0, the host-based authentication method is no longer supported.

Users and groups migration

All users of the built-in, host and custom authentication types are migrated to the Internal Directory. Only built-in users have their passwords migrated.

If LDAP authentication was previously configured, users with the LDAP authentication type are also migrated. Users with the Crowd authentication type are not migrated and will be synchronized after the instance starts.

Users with the custom, AJP or host-based authentication type are migrated to the internal directory, although their passwords are reset.

Users with a legacy, weak password hashing scheme will have their password reset. This should only happen for users that haven't logged in since version 2.x.

The upgrade process ensures all users have unique case-insensitive usernames (i.e. there will be no usernames that differ by case only). Should any collisions be found (e.g. "John" and "john"), only one of the accounts will preserve it's original name, and others are renamed by adding the "_migrationX" suffix.

User permissions migration

In Fisheye 4.0 we have introduce a new concept of global permissions which replaces previously existing toggles determining whether a user has a Fisheye or Crucible license enabled. Two global permissions are defined instead: "Access to Fisheye" and "Access to Crucible" and can be assigned to selected groups. Every member of a group with a given permission assigned is automatically granted that permission.

During the upgrade process, two local groups are created: "fisheye-users" and "crucible-users". These groups are granted appropriate global permissions. All local and LDAP users are added to the "fisheye-users" and/or "crucible-users" groups depending on their actual status. 

If Jira/Crowd authentication was previously configured and there were some groups selected as "groups to synchronize", those groups (and effectively all their members) get the global Fisheye/Crucible permission, which may result in your license limit being exceeded if previously only some members of the selected groups were synchronized. In case where no groups were selected, users need to be granted Fisheye/Crucible permissions manually after the migration process finishes.

Additional information

Various upgrade details are logged to a dedicated $FISHEYE_INST/var/log/atlassian-fisheye-EmbeddedCrowdUpgradeTask.log file. Please refer to the log file to make sure the upgrade proceeded smoothly.