User Store Migration
User Store Migration.
144
Follow this section to migrate the User Store from a source to the target system.
- Log in to the Migration Xpress user interface using the same credentials that you had supplied while launching the Migration Xpress utility.
- In theIntroductiontab, clickGO TO SETUP.
- In theSetuptab, provide connection information for the source and target Identity Manager application servers and the environments to be processed.Notes:
- You can migrate only one environment at a time.
- SelectForce Refreshto pull the latest snapshot of environment details each time you establish a connection to source and target environments. Else, the environment details are pulled from the cache.
- SSL option is not activated.
- In theMappingtab, perform the following tasks:
- In theINTRODUCTIONtab, clickSTART.
- In theROLES & TASKStab, select the environment elements (roles and tasks) for migration.
- In theENVIRONMENT ELEMENTSpanel, select the roles and tasks that you wish to migrate from source to the target environment and clickADD SELECTED.Note that in theSELECTED ELEMENTSpanel, all the selected roles and tasks appear. To remove any selected element, clickREMOVE SELECTED.
- Click theDownloadbutton at the bottom-right of the screen to download the task filtering file -environment.selection.map.The file contains a list of managed objects' names (or tags) and types. For example:ModifyUser, TASKNote:Theenvironment.selection.mapfile is used during the environment migration.
- In theUSER, GROUPandORGtabs, map the source User Store attributes (user, group and organization) to the target environments.
- You can map attributes usingSuggestedand/orManualoptions.
- Suggested:This option suggests attributes for mapping based on physical or well-known names. You can map the attributes by clicking the link icon. To map the suggested attributes in bulk, clickAPPROVE ALL.Notes:
- All the attributes that do not have suggested mapping should be manually mapped.
- You can choose that the tool suggests mapping forAllor just theMandatory(as defined in the User Store XML) attributes on the target environment.
- Manual:This option lets you manually map the attributes from source to the target environment. To map the attributes, click the link icon on both the source and target sides or drag the source link icon and place it on the target link icon.Notes:
- In the target environment, you can considerAllor just theMandatory(as defined in the User Store XML) attributes for mapping.
- In the source environment, you can delete an attribute by hovering over the attribute and clicking the delete icon. To bulk delete attributes, clickSELECT ALLand clickDELETE.
- In the source environment, you can create a duplicate attribute by hovering over the attribute and clicking the duplicate icon. The duplicate option maps an attribute to the self and creates the attribute in the target. To perform a bulk duplicate operation, clickSELECT ALLand clickDUPLICATE.
- Click theDownloadbutton at the bottom-right of the screen to download the following files, respectively:
- user_preparation_<date_time>.zip
- group_preparation_<date_time>.zip
- organization_preparation_<date_time>.zip
- Extract the zip files. The extracted files contain the following attribute mapping files:UserGroupOrgenvironment.userAttrMapping.mapenvironment.groupAttrMapping.mapenvironment.orgAttrMapping.mapim_user_aux.dxcim_group_aux.dxcim_organization_aux.dxcuserstore.user.mapuserstore.group.mapuserstore.org.mapuserStoreUpgradeUser.xmluserStoreUpgradeGroup.xmluserStoreUpgradeOrg.xmlDifferences in File Content:The number of items in each file are most likely to be different as they serve different purposes. For example, if the source %USER_ID% was mapped to cn and the Virtual Appliance %USER_ID% is uid, then:
- Itwill notbeincluded inim_user_aux.dxc,as both are x500 attributes.
- Itwill notbeincluded inuserStoreUpgradeUser.xml,as there is no change in the User Store.
- Itwill beincluded inuserstore.user.map,as the User Store migration will need to transfer the data to the new attribute name.
- Itwill not beincluded in theenvironment.userAttrMapping.map,as it requires no change in the environment.
Notes:- If custom attributes were added, those need to be added to the User Store aux user schema file. X500, dxserver operational attributes or attributes from the out-of-the-box Virtual Appliance environment will not be included.
- Theenvironment.user/group/orgAttrMapping.mapfile includes the mapping of physical and well-knowns between the source and target system. Only items that have changed will be included, so items such as %USER_ID% or %FULL_NAME% will most likely not be included.
- Update the target user store.
- Prerequisite:To perform the target user store update operations, you must switch user to dsa: su -dsa
- User:
- Copy the custom user attributes from the downloaded sourceim_user_aux.dxcfile. For example, copy the following custom user attributes:#objectClass configuration schema set object-classim-UUA-oc:1 = { name = imUserAux subclass-of imUser kind = auxiliary # must-contain may-contain imUserType }; # Name Bindings. schema set name-binding im-UUA-nb:1 = { name = imUserAux-o imUser allowable-parent organization named-by commonName optional surname, dnQualifier }; schema set name-binding im-UUA-nb:2 = { name = imUserAux-ou imUser allowable-parent organizationalUnit named-by commonName optional surname, dnQualifier }; schema set name-binding im-UUA-nb:3 = { name = imUser2Aux-o imUser allowable-parent organization named-by cosineUserid }; schema set name-binding im-UUA-nb:4 = { name = imUser2Aux-ou imUser allowable-parent organizationalUnit named-by cosineUserid };
- Append the copied custom user attributes to the target/opt/CA/Directory/dxserver/config/schema/im_user_aux.dxcfile on all the user store DSA nodes.
- Change themay-containdeclaration fromimUserTypetoall-attributes.
- Following is an example of the target dxc file after appending the custom attributes and changing themay-containdeclaration toall-attributes:# # IM Unified User (UU)Auxiliary Schema # schema set oid-prefix im-UUA-attr = (1.3.6.1.4.1.791.2.3.5.3.6485.1); schema set oid-prefix im-UUA-oc = (1.3.6.1.4.1.791.2.3.5.3.6485.2); schema set oid-prefix im-UUA-nb = (1.3.6.1.4.1.791.2.3.5.3.6485.3); # # IM Unified User Aux Schema (UUS): Attribute Type Definitions # # objectClass configuration schema set object-classim-UUA-oc:1 = { name = imUserAux subclass-of imUser kind = auxiliary # must-contain may-contain all-attributes }; # Name Bindings. schema set name-binding im-UUA-nb:1 = { name = imUserAux-o imUser allowable-parent organization named-by commonName optional surname, dnQualifier }; schema set name-binding im-UUA-nb:2 = { name = imUserAux-ou imUser allowable-parent organizationalUnit named-by commonName optional surname, dnQualifier }; schema set name-binding im-UUA-nb:3 = { name = imUser2Aux-o imUser allowable-parent organization named-by cosineUserid }; schema set name-binding im-UUA-nb:4 = { name = imUser2Aux-ou imUser allowable-parent organizationalUnit named-by cosineUserid };
- Group:
- Copy the custom group attributes from the downloaded sourceim_group_aux.dxcfile.
- Paste the custom group attributes in the target/opt/CA/Directory/dxserver/config/schema/im_group.dxcfile on all the user store DSA nodes. You must paste the custom group attributes after theAttribute Type Definitionssection and beforeObject Class Definitionssection.
- Change themay-containdeclaration fromimUserTypetoall-attributes.# # # IM Unified Group (UG) Schema # # schema set oid-prefix im-UG-attr = (1.3.6.1.4.1.791.2.3.5.3.6490.1); schema set oid-prefix im-UG-oc = (1.3.6.1.4.1.791.2.3.5.3.6490.2); schema set oid-prefix im-UG-nb = (1.3.6.1.4.1.791.2.3.5.3.6490.3); # # # IM Unified Group Schema (UGS): Attribute Type Definitions # # schema set attribute im-UG-attr:1 = { name = imGroupType ldap-names = imGroupType equality = caseExactMatch syntax = directoryString single-valued }; # # # CA Directory Schema: Object Class Definitions # # schema set object-classim-UG-oc:1 = { name = imGroup subclass-of groupOfUniqueNames kind = auxiliary may-contain all-attributes };
- Restart the target user store and router DSAs on all user store DSA nodes.
- Update the user store directory XML by following these steps:
- In the target machine, open the Identity Manager Management Console.
- ClickDirectories.
- Select the User Store.
- ClickExportto export the user directory XML.
- Open the downloaded sourceuserStoreUpgradeUser.xml, userStoreUpgradeGroup.xml and userStoreUpgradeOrg.xmlfiles. Copy the text between the following tags from the respective mapping files and append to the same tags in the user directory XML.User: <ImsManagedObject name="User" description="My Users" objectclass="top,imUser" pagesize="0" maxrows="0" objecttype="USER"></ImsManagedObject> Group: <ImsManagedObject name="Group" description="My Groups" objectclass="top,groupOfUniqueNames" pagesize="0" maxrows="0" objecttype="GROUP"></ImsManagedObject> Organization: <ImsManagedObject name="Organization" description="My Organizations" objectclass="top,organizationalUnit" pagesize="0" maxrows="0" objecttype="ORG"></ImsManagedObject>
- ClickUpdateto import the file.
- Restart Identity Manager environment.
- Update the<Migration_Xpress_download_directory>/conf/file with an appropriate value for each of the properties as explained below:userstore.propertiesPropertySystemObjectDescriptionRequiredSourceFileSourceDirectorySource ldif file for offline mode.Example:SourceFile=<Migration_Xpress_download_directory>\\data\\input.ldifOffline modeTargetFileTargetDirectoryTarget ldif file for offline mode.Example:TargetFile=<Migration_Xpress_download_directory>\\data\\output.ldifOffline modeSourceHostSourceDirectoryHostname or IP address of the source system.Example:SourceHost=mySourceHostOnline modeTargetHostTargetDirectoryHostname or IP address of the target system.Example:TargetHost=myTargetHostOnline modeSourcePortSourceDirectorySource user store port.Example:SourcePort=10389Online modeTargetPortTargetDirectoryTarget user store port.Example:TargetPort=19289Online modeSourceBindAccountSourceDirectorySource system Bind DN.Example:SourceBindAccount=uid=SuperAdmin,ou=People,ou=Employee,ou=NeteAuto,dc=security,dc=comOnline modeTargetBindAccountTargetDirectoryTarget system Bind DN.Example:TargetBindAccount=cn=dsaadmin,ou=im,ou=ca,o=comOnline modeSourcePasswordSourceDirectorySource system Bind DN password.Example:SourcePassword=test1Online modeTargetPasswordTargetDirectoryTarget system Bind DN password.Example:TargetPassword=test2Online modeSourceBaseDNSourceDirectoryBase DN on source to calculate RDN migration.Example:SourceBaseDN=dc=security,dc=comRequiredTargetBaseDNTargetDirectoryBase DN on target to calculate RDN migration.Example:TargetBaseDN=o=test,ou=im,ou=ca,o=comRequiredSourceFilterStringSourceDirectoryFilter for testing purposes.Example:SourceFilterString=(cn=automic_admin_assistance_permissions)OptionalSourceIMEnvironmentNameSourceUserSource Identity Manager environment name.Example:SourceIMEnvironmentName=envRequiredTargetIMEnvironmentNameTargetTarget Identity Manager environment name.Example:TargetIMEnvironmentName=identityEnvRequiredSourceIdentityPolicyAttributeSourceUserSource identity policy attribute (%IDENTITY_POLICY%).Example:SourceIdentityPolicyAttribute=streetRequiredTargetIdentityPolicyAttributeTargetUserTarget identity policy attribute (%IDENTITY_POLICY%).Example:TargetIdentityPolicyAttribute=imIdentityPoliciesRequiredSourceManagerDnAttributeSourceUserSource manager DN attribute (%MANAGER%).Example:SourceManagerDnAttribute=managerOptionalTargetManagerDnAttributeTargetUserTarget manager DN attribute (%MANAGER%).Example:TargetManagerDnAttribute=managerOptionalSourceManagerIdAttributeSourceUserSource Manager Attribute ID.Example:SourceManagerIdAttribute=imManagerIdOptionalTargetManagerIdAttributeTargetUserTarget manager Attribute ID (%MANAGER%).Example:TargetManagerIdAttribute=imManagerIdRequired if SourceManagerDnAttribute or SourceManagerIdAttribute exitSourceLoginIdAttributeSourceUserSource Login ID attribute (%LOGIN_ID%). If not provided, the source ID (SourceUserIdentifier property) will be used.Example:SourceLoginIdAttribute=xxxOptionalTargetLoginIdAttributeTargetUserTarget Login ID attribute (%LOGIN_ID%).Example:TargetLoginIdAttribute=imLoginIdRequiredSourceUserObjectClassSourceUserSource user object class.Example:SourceUserObjectClass=inetOrgPersonRequiredTargetUserObjectClassTargetUserTarget user object class.Example:TargetUserObjectClass=imUserRequiredSourceGroupObjectClassSourceGroupSource group object class.Example:SourceGroupObjectClass=groupOfUniqueNamesRequiredTargetGroupObjectClassTargetGroupTarget group object class.Example:TargetGroupObjectClass=imGroup,groupOfUniqueNamesRequiredSourceOUObjectClassSourceOUSource organization object class.Example:SourceOUObjectClass=organizationalUnitRequiredTargetOUObjectClassTargetOUTarget organization object class.Example:TargetOUObjectClass=organizationalUnit,topRequiredSourceUserIdentifierSourceUserSource user unique identifier (%USER_ID%)Example:SourceUserIdentifier=uidRequiredTargetUserIdentifierTargetUserTarget user unique identifier (%USER_ID%)Example:TargetUserIdentifier=uidRequiredSourceGroupIdentifierSourceGroupSource group unique identifier (%GROUP_NAME%)Example:SourceGroupIdentifier=cnRequiredTargetGroupIdentifierTargetGroupTarget group unique identifier (%GROUP_NAME%)Example:TargetGroupIdentifier=cnRequiredSourceUserGroupMembershipAttributeSourceGroupSource user group membership attribute (%GROUP_MEMBERSHIP%)Example:SourceUserGroupMembershipAttribute=uniqueMemberOptionalTargetUserGroupMembershipAttributeTargetGroupTarget user group membership attribute (%GROUP_MEMBERSHIP%)Example:TargetUserGroupMembershipAttribute=uniqueMemberOptionalSourceOwnerSourceGroupSource group admin (%GROUP_ADMIN%).Example:SourceOwner=ownerOptionalTargetOwnerTargetGroupTarget group admin (%GROUP_ADMIN%).Example:TargetOwner=ownerRequiredSourceUrlSourceGroupSource dynamic group membership (%DYNAMIC_GROUP_MEMBERSHIP%)Example:SourceUrl=imGroupDynamicQueryOptionalTargetUrlTargetGroupTarget dynamic group membership (%DYNAMIC_GROUP_MEMBERSHIP%)Example:TargetUrl=imGroupURLRequired if SourceUrl existsSourceUserContainer TargetUserContainerSource TargetUserSource and target user container.
- Virtual Appliance assumes that users are in the ou=people container. If this is the case in the source environment, both the source and target property configuration are optional.
- When source directory is flat (no containers), only target containers should be specified.Example:
- SourceUserContainer=
- TargetUserContainer=ou=people
- When source has containers with different names than the Virtual Appliance, both source and target should be specified.Example:
- SourceUserContainer=ou=user
- TargetUserContainer=ou=people
OptionalSourceGroupContainer TargetGroupContainerSource TargetGroupSource and target group containers.- Virtual Appliance assumes that groups are in the ou=groups. If this is the case in the source environment, both the source and target property configuration are optional.
- When source directory is flat (no containers), only target containers should be specified.Example:
- SourceGroupContainer=
- TargetGroupContainer=ou=groups
- When source has containers with different names than the Virtual Appliance, both source and target should be specified.Example:
- SourceGroupContainer=ou=grp
- TargetGroupContainer=ou=groups
OptionalExample of a User and Group Container:Example: user (userid) is in Services organizationSource is Flat (No Containers)Source with ContainersResultOrgLesscn=userid,o=sourcecn=userid,ou=users,o=sourceuid=userid,ou=people,ou=im,ou=ca,o=comOrgcn=userid,ou=services,o=sourcecn=userid,ou=user,ou=services,o=sourceuid=userid,ou=people,ou=services,ou=im,ou=ca,o=com - Run the user store migration tool. There are two ways to run the tool.
- Method 1:<Migration_Xpress_download_directory>/lib/java -cp migration-xpress-<version>.jar -Dloader.main=com.ca.tools.userstore.migration.StartConsole org.springframework.boot.loader.PropertiesLauncher -m <ONLINE | OFFLINE> -gpf <file> -umf <file> -gmf <file> [-omf file] [-ll DEBUG|INFO|WARN|ERROR]
- Method 2:Windows: <Migration_Xpress_download_directory>bin\mx_userstore.cmd -m <ONLINE | OFFLINE> -gpf <file> -umf <file> -gmf <file> [-omf file] [-ll DEBUG|INFO|WARN|ERROR] Linux: <Migration_Xpress_download_directory>./bin/mx_userstore.sh -m <ONLINE | OFFLINE> -gpf <file> -umf <file> -gmf <file> [-omf file] [-ll DEBUG|INFO|WARN|ERROR]Options:-m <MODE>ONLINE:Connects directly to the source and target user store.OFFLINE:Reads an LDIF source file and writes a target LDIF file to a given folder.-gpf <file>Represents the Global Properties File. The file contains the LDAP connection details (source and target LDAPs) or LDIF files location, and additional global properties.Location:<Migration_Xpress_download_directory>/conf/userstore.properties-umf <file>Represents the User Mapping File. The file contains the user attributes mapping from source to target environments.Location:Migration_Xpress_download_directory>/conf/userstore.user.map-gmf <file>Represents the Group Mapping File. The file contains the group attributes mapping from source to target environments.Location:<Migration_Xpress_download_directory>/conf/userstore.group.map[-omffile]Represents the Organization Mapping File. The file contains the organization attributes mapping from source to target environments.Location:<Migration_Xpress_download_directory>/conf/userstore.org.map[-llLOGLEVEL]Represents the log levels:
- DEBUG
- INFO
- WARN
- ERROR
Notes:- Before running the tool, ensure that the attributes that exist in both the Global Properties File (gpf) and mapping files (umf, gmf, omf) are removed from the mapping files to avoid data corruption errors.
- After running the tool, ensure that you review all errors. The errors might indicate that a target object was not created due to mapping incompatibility. If you need to re-run the migration tool, note that target user and group objects will be overwritten, and not modified. Organization will not be recreated.
- On completion of migration, all users, groups and organizations must be represented in the target system user store.
Known Issues
- Identity Manager Management Console Certificate issue:If the source and/or target servers are protected with SSL, a proper certificate must be imported from the Identity Manager Management Console and applied on the JVM where the Migration application (JAR) is running. Since the certificate is issued per the hostname (of the Identity Manager system), the connection to the source and target Identity Manager systems (from the Migration setup page) must use the same hostname (and not IP). Otherwise, the following error might occur: javax.net.ssl.SSLPeerUnverifiedException: Certificate for <10.144.13.56> doesn't match any of the subject alternative names: []
- The following errors may occur during migration.LDAP error code 17 - Undefined Attribute Type: Check that the attribute mapping file points to valid target attributes. If custom attributes have been added, ensure that the DSAs have been restarted and the attributes names are visible by LDAP tools.LDAP error code 65 - LDAP object class violation: Check that the user migration process is not writing incorrect values (Example: a manager ID into a manager DN attribute), and that mandatory attributes exist.LDAP error code 68 - Already exist: The object (User, Group, Organization) already exists in the target environment. Existing objects will not be overwritten.