Skip to main content

Setup for Migration

Download the required software​

If you are using an Entrust Identity Enterprise 13.0 installation, ensure you have Patch 452872 or newer installed. All migration capabilities are built-in, and you do not require any additional software. After you have installed the patch, skip to Migrating User Data.

If you are using an Entrust IdentityGuard 12.0 installation, upgrade to the latest Patch. Limited migration capabilities are built-in, but for progressive migration you must download the Entrust IdentityGuard to Entrust Identity as a Service Migration Tool 3.0 software package, available through the Entrust TrustedCare portal. You require a user name and password to authenticate to this portal.

If you are using an Entrust IdentityGuard 10.2.x to 11.0 installation, no migration capabilities are built-in. You must download the Migration Tool 3.0 software package.

If using Entrust Identity Self-Service, upgrade it to the latest Patch available that is compatible with your installed version of Entrust Identity Enterprise (formerly known as Entrust IdentityGuard).

To download the Migration Tool software package​

Downloading Migration Tool 3.0 and (optionally) the Mobile Identity Provider Migration Filter 2.0 is not necessary if running the latest Patch of Entrust Identity Enterprise 13.0 and, if you use it, the latest Patch of Entrust Identity Self-Service 13.0.

  1. Navigate to the products page, select Identity > Identity Enterprise > Server (Consumer & Enterprise).
  2. Under Related Products, select Identity to IDaaS Migration Tool 3.0.
  3. Download the Migration Tool package required for your operating system:
Package nameDescription
IG_Migration_Tool_3_Linux.tarFor 64-bit Linux operating systems that use the embedded Tomcat web application server.
IG_Migration_Tool_3.zipFor 64-bit Windows operating systems.
IG_Migration_Tool_3_Solaris.tarFor Solaris operating systems that use the embedded Tomcat web application server.
  1. If your users use mobile soft tokens with push authentication and transaction verification, also download the following package (listed on the IdentityGuard to Entrust Identity as a Service Migration Tool product page in Trusted Care):
    • Mobile Identity Provider Migration Filter 2.0
      (IGSSM_MobileSoftTokenMigrationFilter_20.zip)
      This software facilitates registration of the migrated soft tokens with the new identity provider URL associated with your Entrust Identity as a Service account.

To upgrade 32-bit systems for Migration Tool 3.0 compatibility​

If you are running a 64-bit system, skip to Set up the Migration Tool.

Migration Tool 3.0 does not support 32-bit systems. If you are running a 32-bit Linux or Windows system, follow the steps below to install a 64-bit Entrust IdentityGuard installation based on a full backup created from your 32-bit primary installation. Once that is done, run Migration Tool 3.0 from your new 64-bit Entrust IdentityGuard installation.

  1. Update to the latest patch of your Entrust IdentityGuard installation.

  2. Create a full backup of your current 32-bit primary Entrust IdentityGuard installation.

    note

    For step-by-step procedures, see "Planning a backup strategy," "Backing up file-based repositories," and "Backing up your configuration" in the Installation Guide associated with your installed release of Entrust IdentityGuard.

    note

    This procedure requires a full backup of your current installation.

  3. Install an equivalent release of Entrust IdentityGuard on a 64-bit platform. This new installation must be of the same release as your current up-to-date 32-bit system, with the latest patch applied.

    Step-by-step procedures can be found in the Installation Guide corresponding to your Entrust IdentityGuard installation:

    • If using Entrust IdentityGuard 11.0 or later, see the chapters "Preparing to install Entrust IdentityGuard" and "Installing Entrust IdentityGuard".
    • If using Entrust IdentityGuard 10.2.x, see the chapters "Preparing for Installation," "Installing Entrust IdentityGuard on Windows," and "Installing Entrust IdentityGuard on Unix or Linux".

  4. Configure your new 64-bit installation of Entrust IdentityGuard with the full backup file of your old 32-bit installation by using the restore option.

    Step-by-step procedures can be found in the Installation Guide corresponding to your Entrust IdentityGuard installation:

    • If using Entrust IdentityGuard 11.0 or later, see "Restoring Entrust IdentityGuard from a backup" in the chapter "Backing up and restoring Entrust IdentityGuard".
    • If using Entrust IdentityGuard 10.2.x, see "Restoring Entrust IdentityGuard from a backup" in the chapter "Backing up and restoring the server".

  5. The new 64-bit installation is now considered your primary installation. Run Migration Tool 3.0 from your new 64-bit Entrust IdentityGuard installation. For setup procedures, see Set up the Migration Tool.

Set up the Migration Tool​

If you are using an Entrust Identity Enterprise 13.0 installation, skip this chapter.

If you are using an Entrust IdentityGuard 12.0 installation and want to do progressive migration, you must set up Migration Tool 3.0.

If you are using an Entrust IdentityGuard 10.2.x or 11.0 installation, you must set up Migration Tool 3.0.

Installing and launching this tool deploys a special version of the Entrust Identity Enterprise Master User Shell with the following limited set of commands required to export data to a file that is later imported into Entrust Identity as a Service:

  • system get
  • system authexport
  • system authexportbyalias
  • user set
  • login
  • logout
  • exit

Set up the Migration Tool on Linux or Solaris​

Migration Tool 3.0 does not have an installer. The following procedure describes how to add the software required for migration to your existing Entrust IdentityGuard installation.

Migration Tool 3.0 does not support 32-bit Linux systems. For details on how to proceed if using a 32-bit Linux system, see To upgrade 32-bit systems for Migration Tool 3.0 compatibility.

  1. Authenticate to Linux or Solaris using the account that will own the Migration tool 3.0 installation. This account cannot be root. It is recommended to use the same account that owns the IdentityGuard installation.

  2. Create a directory anywhere on the computer that hosts your primary Entrust Identity Enterprise server to extract the software.

  3. Extract the contents of the software package you downloaded to the directory you created, using the following commands:

    • tar xvf <package>
      • where <package> is the name of the package you downloaded, either:
        • IG_Migration_Tool_3_Linux.tar
        • IG_Migration_Tool_3_Solaris.tar
    • cd IG_Migration_Tool_3
    • unzip identityguardmigration.zip
    note

    The steps below will not work if using a 32-bit Linux system. Before continuing, you must follow the procedures detailed in To upgrade 32-bit systems for Migration Tool 3.0 compatibility.

  4. Migration Tool 3.0 requires a specific version of Java 8, so the IG_Migration_Tool_3 directory provides a JRE 8 package.

    In the directory where you extracted the tool, enter the following commands to unpack the appropriate Java hierarchy:

    • If using Linux:
      zcat OpenJDK8U-8u345b01-x64_linux_hotspot.tar.gz | tar xvf -
    • If using Solaris:
      gzcat OpenJDK8U-8u345b01-sparcv9_solaris_hotspot.tar.gz | tar xvf -

  5. Only complete this step if using Solaris 10. To enable strong cryptography algorithms for protecting the exported migration file, replace the java.security file. To do so, complete the following steps:

    a. In the jdk8u345-b01/jre/lib/security location, rename the java.security file to old_java.security.

    b. Copy javatk.java.security from the package to jdk8u345-b01/jre/lib/security, then rename it to java.security.

    Solaris 10 only: If the following error message appears after attempting to perform a system authexport or a system authexportbyalias command, it indicates that javatk.java.security was not properly copied to jdk8u345-b01/jre/lib/security after backing up the original java.security file.

    [5201046] Error in Entrust Identity as a Service migration data export.
    java.security.InvalidKeyException: Invalid key for AES
    java.security.InvalidAlgorithmParameterException: Key length must be between 128 and 128 bits

  6. Source the environment settings using the following command:

    . /opt/entrust/identityguard<version>/env_settings.sh

    note

    Do not run the Migration Tool as root.

  7. To run Migration Tool 3.0, navigate to the directory where you unpacked the software and run the script that is appropriate for your Entrust IdentityGuard installation. Use ./authexport_ig.sh

    note

    If your Entrust IdentityGuard system uses tokens, you might see an error about loading a token vendor. This can occur if Migration Tool 3.0 cannot load the existing token library from your installation. If this occurs, open the authexport_ig.sh file and uncomment the line that sets the library path, LD_LIBRARY_PATH, so it uses the token library provided by Migration Tool 3.0.

Set up the Migration Tool on Windows​

Migration Tool 3.0 does not have an installer. The following procedure describes how to add the software required for migration to your existing Entrust IdentityGuard installation.

Migration Tool 3.0 does not support 32-bit Windows systems. For details on how to proceed if running a 32-bit Windows system, see To upgrade 32-bit systems for Migration Tool 3.0 compatibility.

To set up the required software to your existing Entrust IdentityGuard installation:​

  1. Log in to Windows as the user who owns the Entrust IdentityGuard installation and create a folder anywhere on the computer that hosts your primary Entrust IdentityGuard server. Extract the contents of IG_Migration_Tool_3.zip to that folder.

  2. Migration Tool 3.0 requires a specific version of Java 8, so the IG_Migration_Tool_3 directory provides a JRE 8 package. While you can install the 32-bit Java 8 JDK on a 64-bit Windows machine, the 64-bit version of the JDK is strongly recommended.

    Extract jre-64.zip.

    If you are using a 32-bit Windows system, see Set up the Migration Tool.

  3. Confirm that the folder where you extracted the software has the same layout as this example:

    C:\IG_Migration_Tool_3\bin
    C:\IG_Migration_Tool_3\lib
    C:\IG_Migration_Tool_3\token

    Confirm you also have the following:

    C:\IG_Migration_Tool_3\jdk8u345-b01

  4. Change directory into the bin directory and run the BAT file using:

    ./authexport_ig.bat

If handshake cipher issues occur when attempting to connect to a repository over TLS​

This section is only relevant if all of the following is true:

  • Handshake cipher issues occur when you attempt to connect to a repository (LDAP server or a database) over TLS.
  • You are running an Entrust IdentityGuard 12.0 system below patch 130569 OR an Entrust Identity Enterprise 13.0 system below patch 452872.

What does the handshake cipher issue look like?​

If the handshake cipher issue is present, Migration Tool 3.0 fails to run after attempted login and generates an error. The details of the error depend on the type of repository to which you are attempting to connect.

  • When connecting to Active Directory, the system displays the following error:

    [5202050] Error checking the repository. Ensure that the repository configuration is correct.
    [5202231] Failed to determine if the policy repository is set up; ensure the directory entry CN=ZYX exists and can be read.
    [5202248] Failed to get a connection to a search base.
    [5202500] Failed to connect to any of the connected URLs.
    [5202219] Could not connect to the directory.
    javax.naming.CommunicationException

  • When connecting to a database other than Active Directory, an error similar to the following appears:

    com.microsoft.sqlserver.jdbc.SQLServerException: The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "Unexpected rethrowing".
    javax.net.ssl.SSLException: Unexpected rethrowing
    java.io.IOException: SQL Server returned an incomplete response.
    The Connection has been closed.

Resolve the handshake cipher issue​

There are two options available to resolve the handshake cipher issues that occur when you attempt to connect to a repository over TLS. One solution is to upgrade to Entrust Identity Enterprise 13.0 Patch 452872 or higher. In this case, Migration Tool 3.0 is not required, as all of its features are built-in to the Entrust Identity Enterprise system.

If it is not possible to upgrade to Entrust Identity Enterprise 13.0 Patch 452872 or higher, use the following procedure to resolve the handshake cipher issues:

  1. Open the lib directory associated with Migration Tool 3.0.
  2. In the Migration Tool 3.0 lib directory, rename the file enttoolkit.jar to enttoolkit.jar.orig.
  3. Open the lib/etc directory associated with your Entrust IdentityGuard or Entrust Identity Enterprise installation.
  4. Copy the enttoolkit.jar file found in the Entrust IdentityGuard or Entrust Identity Enterprise lib/etc directory.
  5. Paste the enttoolkit.jar file copied in Step 4 into the Migration Tool 3.0 lib directory.

The fix is complete. The Migration Tool will run as expected, without any handshake cipher issues when trying to connect to a repository over TLS.