Migrating Jazz Team Server users to Liberty in AppScan Enterprise

To migrate Jazz Team users to use the Liberty authentication method, export a .csv file of users by using a command before you begin upgrading to v9.0.1 and higher. Then, you can follow one of the following two methods and register the same users in Liberty so that they can access AppScan Enterprise v9.0.1 and higher.

cd <install-dir>\Appscan Enterpise\JazzTeamServer\server\ repotools-jts.bat -exportUsers toFile=C:\users.csv repositoryURL=https://<hostname>:9443/jts

Note: User passwords are not exported in the .csv file.

Authenticating with Windows Local Account Users

The option to use this type of authentication is not explicitly displayed in the configuration wizard due to limited support for this option. The product administrator must follow several manual steps to set up this type of authentication.

Procedure

  1. During configuration, select Windows Authentication in the Authentication Mechanism screen of the configuration wizard, click Next, and complete the wizard.
  2. Create local Windows users on the computer that hosts the Enterprise Console. The administrator must have computer access to create local Windows users.
    Note:
    1. These local Windows user IDs and passwords are to be used to access AppScan Enterprise.
    2. In this case, password expiry is governed by Windows policies. Password management is handled by the AppScan Enterprise product administrator by manually changing the user's passwords on the computer that hosts the Enterprise Console.
    3. If you need to run the AppScan Enterprise configuration wizard again on the computer that hosts the Enterprise Console, the authentication option remains set as "Windows Authentication". No further tweaking is necessary to preserve the authentication method that is already set up.
    4. If you are migrating users from Jazz Team Server into this authentication method, there is a way to preserve each user's AppScan Enterprise user settings. A custom SQL script can be run to remap older user IDs to newer ones. Run this custom script with help from HCL.

Authenticating with Liberty Basic User Registry

The option to use this type of authentication is not explicitly displayed due to limited support for this option. A number of manual steps are required to set up this type of authentication.

About this task

After you follow this procedure, you must use the local user account to log in to AppScan Enterprise. You cannot use the service account.

Procedure

  1. During configuration, select Windows Authentication in the Authentication Mechanism screen of the configuration wizard, click Next, and complete the wizard.
  2. Stop the HCL AppScan Enterprise Server service. You can type "net stop HCL AppScan Enterprise Server" in a command prompt window, or follow these steps:
    1. Go to the Windows Service Management Console (Start > Run > services.msc).
    2. In the Services section, right-click HCL AppScan Enterprise Server and select Stop Services in the menu.
  3. Locate the server.xml file at <install-dir>\AppScan Enterprise\Liberty\usr\servers\<ase instance name>\server.xml and open it in an XML editor.
  4. Locate and remove the <feature>usr:WindowsRegistryFeature</feature> section.
  5. Add a basic user registry section to the server.xml file as follows:

    <basicRegistry id="basic">
    <user name="mlee" password="p@ssw0rd" />
    <user name="rkumar" password="pa$$w0rd" />
    <user name="gjones" password="{xor}Lz4sLCgwLTs=" />
    </basicRegistry>

    Note:
    1. You must use unique names for your users and groups.
    2. Remove all trailing and leading spaces from the user and group names.
    3. If user ID or password contains characters other than US-ASCII, make sure that the file is saved by using UTF-8 character encoding.
  6. Encode the password for each user by using the securityUtility encode command. The securityUtility command line tool is available in the <install-dir>\AppScan Enterprise\Liberty\bin directory.
  7. When you run the securityUtility encode command, you either supply the password to encode as an input from the command line. If no arguments are specified, the tool prompts you for the password. The tool then outputs the encoded value.
  8. Copy the value output by the tool, and use that value for the password.
    For example, to encode the password "GiveMeLiberty", run the following command: securityUtility encode GiveMeLiberty. You can encode the password using the “aes? encoding type. If there is a key.xml file located in the <install-dir>\AppScan Enterprise\Liberty\usr\shared\config directory, provide the encryption key specified in key.xml to securityUtility. For example, securityUtility encode --encoding=aes --key=<the_key_in_key.xml> GiveMeLiberty. If you do not have a key.xml, you do not need to specify the --key option.
  9. Restart the HCL AppScan Enterprise Server service. You can type "net start HCL AppScan Enterprise Server" in a command prompt window, or follow these steps:
    1. Go to the Windows Service Management Console (Start > Run > services.msc).
    2. In the Services section, right-click HCL AppScan Enterprise Server and select Start Services in the menu.
  10. If you install the Enterprise Console on more than one computer, you must repeat this process on every computer.
    Note: Liberty does not provide a mechanism for password expiry, and changing passwords periodically is a manual process that involves encryption steps as described next.

Running the configuration wizard after user migration

If you need to run the AppScan Enterprise configuration wizard again, follow these steps BEFORE you rerun the wizard so that you preserve this authentication method.

Procedure

  1. Copy server.xml to server.xml.backup.
  2. Remove the following section from server.xml:

    <basicRegistry id="basic">
    <user name="mlee" password="p@ssw0rd" />
    <user name="rkumar" password="pa$$w0rd" />
    <user name="gjones" password="{xor}Lz4sLCgwLTs=" />
    </basicRegistry>

  3. Add the <feature>usr:WindowsRegistryFeature</feature> section back in.
  4. Rerun the configuration wizard.
  5. Delete server.xml.
  6. Rename server.xml.backup to server.xml

Results

If the user IDs that are recorded in the Liberty basic user registry match the user IDs that were specified in Jazz Team Server, no further configuration is necessary, and the migration is complete. However, if the user IDs do not match after migration, you can run a custom SQL script to remap older user IDs to newer ones. Run this custom script with help from HCL.