User Store Migration

User Store Migration.
144
Follow this section to migrate the User Store from a source to the target system.
  1. Log in to the Migration Xpress user interface using the same credentials that you had supplied while launching the Migration Xpress utility.
  2. In the
    Introduction
    tab, click
    GO TO SETUP.
  3. In the
    Setup
    tab, 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.
    • Select
      Force Refresh
      to 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.
  4. In the
    Mapping
    tab, perform the following tasks:
    1. In the
      INTRODUCTION
      tab, click
      START.
    2. In the
      ROLES & TASKS
      tab, select the environment elements (roles and tasks) for migration.
      1. In the
        ENVIRONMENT ELEMENTS
        panel, select the roles and tasks that you wish to migrate from source to the target environment and click
        ADD SELECTED.
        Note that in the
        SELECTED ELEMENTS
        panel, all the selected roles and tasks appear. To remove any selected element, click
        REMOVE SELECTED.
      2. Click the
        Download
        button 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, TASK
        Note:
        The
        environment.selection.map
        file is used during the environment migration.
    3. In the
      USER, GROUP
      and
      ORG
      tabs, map the source User Store attributes (user, group and organization) to the target environments.
      1. You can map attributes using
        Suggested
        and/or
        Manual
        options.
        • 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, click
          APPROVE ALL.
          Notes:
          • All the attributes that do not have suggested mapping should be manually mapped.
          • You can choose that the tool suggests mapping for
            All
            or just the
            Mandatory
            (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 consider
            All
            or just the
            Mandatory
            (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, click
            SELECT ALL
            and click
            DELETE.
          • 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, click
            SELECT ALL
            and click
            DUPLICATE
            .
      2. Click the
        Download
        button 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
      3. Extract the zip files. The extracted files contain the following attribute mapping files:
        User
        Group
        Org
        environment.userAttrMapping.map
        environment.groupAttrMapping.map
        environment.orgAttrMapping.map
        im_user_aux.dxc
        im_group_aux.dxc
        im_organization_aux.dxc
        userstore.user.map
        userstore.group.map
        userstore.org.map
        userStoreUpgradeUser.xml
        userStoreUpgradeGroup.xml
        userStoreUpgradeOrg.xml
        Differences 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:
        • It
          will not
          be
          included in
          im_user_aux.dxc,
          as both are x500 attributes.
        • It
          will not
          be
          included in
          userStoreUpgradeUser.xml,
          as there is no change in the User Store.
        • It
          will be
          included in
          userstore.user.map,
          as the User Store migration will need to transfer the data to the new attribute name.
        • It
          will not be
          included in the
          environment.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.
        • The
          environment.user/group/orgAttrMapping.map
          file 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.
    4. Update the target user store.
      1. Prerequisite:
        To perform the target user store update operations, you must switch user to dsa: su -dsa
      2. User:
        1. Copy the custom user attributes from the downloaded source
          im_user_aux.dxc
          file. For example, copy the following custom user attributes:
          #objectClass configuration schema set object-
          class
          im-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 };
        2. Append the copied custom user attributes to the target
          /opt/CA/Directory/dxserver/config/schema/im_user_aux.dxc
          file on all the user store DSA nodes.
        3. Change the
          may-contain
          declaration from
          imUserType
          to
          all-attributes.
        4. Following is an example of the target dxc file after appending the custom attributes and changing the
          may-contain
          declaration to
          all-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-
          class
          im-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 };
      3. Group:
        1. Copy the custom group attributes from the downloaded source
          im_group_aux.dxc
          file. 
        2. Paste the custom group attributes in the target
          /opt/CA/Directory/dxserver/config/schema/im_group.dxc
          file on all the user store DSA nodes. You must paste the custom group attributes after the
          Attribute Type Definitions
          section and before
          Object Class Definitions
          section.
        3. Change the
          may-contain
          declaration from
          imUserType
          to
          all-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-
          class
          im-UG-oc:1 = { name = imGroup subclass-of groupOfUniqueNames kind = auxiliary may-contain all-attributes };
      4. Restart the target user store and router DSAs on all user store DSA nodes.
    5. Update the user store directory XML by following these steps:
      1. In the target machine, open the Identity Manager Management Console.
      2. Click
        Directories.
      3. Select the User Store.
      4. Click
        Export
        to export the user directory XML.
      5. Open the downloaded source
        userStoreUpgradeUser.xml, userStoreUpgradeGroup.xml and userStoreUpgradeOrg.xml
        files. 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>
      6. Click
        Update
        to import the file.
      7. Restart Identity Manager environment.
    6. Update the
      <Migration_Xpress_download_directory>/conf/
      userstore.properties
      file with an appropriate value for each of the properties as explained below:
      Property
      System
      Object
      Description
      Required
      SourceFile
      Source
      Directory
      Source ldif file for offline mode.
      Example:
      SourceFile=<Migration_Xpress_download_directory>\\data\\input.ldif
      Offline mode
      TargetFile
      Target
      Directory
      Target ldif file for offline mode.
      Example:
      TargetFile=<Migration_Xpress_download_directory>\\data\\output.ldif
      Offline mode
      SourceHost
      Source
      Directory
      Hostname or IP address of the source system.
      Example:
      SourceHost=mySourceHost
      Online mode
      TargetHost
      Target
      Directory
      Hostname or IP address of the target system.
      Example:
      TargetHost=myTargetHost
      Online mode
      SourcePort
      Source
      Directory
      Source user store port.
      Example:
      SourcePort=10389
      Online mode
      TargetPort
      Target
      Directory
      Target user store port.
      Example:
      TargetPort=19289
      Online mode
      SourceBindAccount
      Source
      Directory
      Source system Bind DN.
      Example:
      SourceBindAccount=uid=SuperAdmin,ou=People,ou=Employee,ou=NeteAuto,dc=security,dc=com
      Online mode
      TargetBindAccount
      Target
      Directory
      Target system Bind DN.
      Example:
      TargetBindAccount=cn=dsaadmin,ou=im,ou=ca,o=com
      Online mode
      SourcePassword
      Source
      Directory
      Source system Bind DN password.
      Example:
      SourcePassword=test1
      Online mode
      TargetPassword
      Target
      Directory
      Target system Bind DN password.
      Example:
      TargetPassword=test2
      Online mode
      SourceBaseDN
      Source
      Directory
      Base DN on source to calculate RDN migration.
      Example:
      SourceBaseDN=dc=security,dc=com
      Required
      TargetBaseDN
      Target
      Directory
      Base DN on target to calculate RDN migration.
      Example:
      TargetBaseDN=o=test,ou=im,ou=ca,o=com
      Required
      SourceFilterString
      Source
      Directory
      Filter for testing purposes.
      Example:
      SourceFilterString=(cn=automic_admin_assistance_permissions)
      Optional
      SourceIMEnvironmentName
      Source
      User
      Source Identity Manager environment name.
      Example:
      SourceIMEnvironmentName=env
      Required
      TargetIMEnvironmentName
      Target
      Target Identity Manager environment name.
      Example:
      TargetIMEnvironmentName=identityEnv
      Required
      SourceIdentityPolicyAttribute
      Source
      User
      Source identity policy attribute (%IDENTITY_POLICY%).
      Example:
      SourceIdentityPolicyAttribute=street
      Required
      TargetIdentityPolicyAttribute
      Target
      User
      Target identity policy attribute (%IDENTITY_POLICY%).
      Example:
      TargetIdentityPolicyAttribute=imIdentityPolicies
      Required
      SourceManagerDnAttribute
      Source
      User
      Source manager DN attribute (%MANAGER%).
      Example:
      SourceManagerDnAttribute=manager
      Optional
      TargetManagerDnAttribute
      Target
      User
      Target manager DN attribute (%MANAGER%).
      Example:
      TargetManagerDnAttribute=manager
      Optional
      SourceManagerIdAttribute
      Source
      User
      Source Manager Attribute ID.
      Example:
      SourceManagerIdAttribute=imManagerId
      Optional
      TargetManagerIdAttribute
      Target
      User
      Target manager Attribute ID (%MANAGER%).
      Example:
      TargetManagerIdAttribute=imManagerId
      Required if SourceManagerDnAttribute or SourceManagerIdAttribute exit
      SourceLoginIdAttribute
      Source
      User
      Source Login ID attribute (%LOGIN_ID%). If not provided, the source ID (SourceUserIdentifier property) will be used.
      Example:
      SourceLoginIdAttribute=xxx
      Optional
      TargetLoginIdAttribute
      Target
      User
      Target Login ID attribute (%LOGIN_ID%).
      Example:
      TargetLoginIdAttribute=imLoginId
      Required
      SourceUserObjectClass
      Source
      User
      Source user object class.
      Example:
      SourceUserObjectClass=inetOrgPerson
      Required
      TargetUserObjectClass
      Target
      User
      Target user object class.
      Example:
      TargetUserObjectClass=imUser
      Required
      SourceGroupObjectClass
      Source
      Group
      Source group object class.
      Example:
      SourceGroupObjectClass=groupOfUniqueNames
      Required
      TargetGroupObjectClass
      Target
      Group
      Target group object class.
      Example:
      TargetGroupObjectClass=imGroup,groupOfUniqueNames
      Required
      SourceOUObjectClass
      Source
      OU
      Source organization object class.
      Example:
      SourceOUObjectClass=organizationalUnit
      Required
      TargetOUObjectClass
      Target
      OU
      Target organization object class.
      Example:
      TargetOUObjectClass=organizationalUnit,top
      Required
      SourceUserIdentifier
      Source
      User
      Source user unique identifier (%USER_ID%)
      Example:
      SourceUserIdentifier=uid
      Required
      TargetUserIdentifier
      Target
      User
      Target user unique identifier (%USER_ID%)
      Example:
      TargetUserIdentifier=uid
      Required
      SourceGroupIdentifier
      Source
      Group
      Source group unique identifier (%GROUP_NAME%)
      Example:
      SourceGroupIdentifier=cn
      Required
      TargetGroupIdentifier
      Target
      Group
      Target group unique identifier (%GROUP_NAME%)
      Example:
      TargetGroupIdentifier=cn
      Required
      SourceUserGroupMembershipAttribute
      Source
      Group
      Source user group membership attribute (%GROUP_MEMBERSHIP%)
      Example:
      SourceUserGroupMembershipAttribute=uniqueMember
      Optional
      TargetUserGroupMembershipAttribute
      Target
      Group
      Target user group membership attribute (%GROUP_MEMBERSHIP%)
      Example:
      TargetUserGroupMembershipAttribute=uniqueMember
      Optional
      SourceOwner
      Source
      Group
      Source group admin (%GROUP_ADMIN%).
      Example:
      SourceOwner=owner
      Optional
      TargetOwner
      Target
      Group
      Target group admin (%GROUP_ADMIN%).
      Example:
      TargetOwner=owner
      Required
      SourceUrl
      Source
      Group
      Source dynamic group membership (%DYNAMIC_GROUP_MEMBERSHIP%)
      Example:
      SourceUrl=imGroupDynamicQuery
      Optional
      TargetUrl
      Target
      Group
      Target dynamic group membership (%DYNAMIC_GROUP_MEMBERSHIP%)
      Example:
      TargetUrl=imGroupURL
      Required if SourceUrl exists
      SourceUserContainer TargetUserContainer
      Source Target
      User
      Source 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
      Optional
      SourceGroupContainer TargetGroupContainer
      Source Target
      Group
      Source 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
      Optional
      Example of a User and Group Container:
      Example: user (userid) is in Services organization
      Source is Flat (No Containers)
      Source with Containers
      Result
      OrgLess
      cn=userid,o=source
      cn=userid,ou=users,o=source
      uid=userid,ou=people,ou=im,ou=ca,o=com
      Org
      cn=userid,ou=services,o=source
      cn=userid,ou=user,ou=services,o=source
      uid=userid,ou=people,ou=services,ou=im,ou=ca,o=com
    7. 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
        [-omf
        file
        ]
        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
        [-ll
        LOGLEVEL
        ]
        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.
    8. On completion of migration, all users, groups and organizations must be represented in the target system user store.

Known Issues

  1. 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: [] 
  2. 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.