Changing the Robots Agent service account

Changing the Windows domain account that runs the Robots Agent service is potentially disruptive to the configuration of your organization's Robots instance. To minimize disruption, copy the RSA key (encryption key) from the current service account to the new service account.

The RSA key is not the same thing as the registration keyfile (registration.key) used for registering a Robots Agent. The two keys are separate objects used at different stages of the registration and connection process.

An alternate method

An alternate method when changing the Robots Agent service account is to re-register the Robots Agent under the new service account. However, this method has drawbacks. It deletes all saved passwords in existing robot tasks, and for multi-agent installations, it requires that you re-register all agents, which is labor-intensive. Re-register the Robots Agent only if the RSA key on the Windows server is no longer available for some reason. For more information, see Manually registering an on-premise Robots Agent.

Before you start

Account permissions

Make sure that the new Robots Agent service account has the necessary account permissions. For more information, see On-premise Robots Agent security.

The recommended security configuration for Windows service accounts is to deny the ability to log on locally. In the instructions that follow, one option is to log on to the Robots Agent server using the existing and new service accounts. If you want to use this approach, you can temporarily give the accounts the right to log on locally and then revoke the right after you are finished.

Passwords

You need the password for the existing Robots Agent service account and for the new account.

Copy the Robots Agent RSA key to the new service account

To copy the RSA key between two Windows accounts on the Robots Agent server, you need to log on to each account as an administrator. Alternately, IT personnel can log on to the server as an administrator and impersonate the Robots Agent service accounts.

Retrieve the RSA key name from the Robots app

1. Sign in to Diligent One (www.highbond.com).
2. From the Launchpad home page, under Audit & Analytics, select the Robots app.
3. In the upper-right corner of the dashboard, click Settings.
4. In the left-hand pane, make sure Agent management is selected.
5. Click How to add additional agents.
6. Click to copy the RSA key name to the clipboard.
7. Paste the RSA key name into a text file for temporary storage.

Stop the Robots Agent service

1. Log on to the Windows server where the Robots Agent is located.

   Log on with an IT account, or with the Windows account that currently runs the Robots Agent service.

2. Open the Windows Services manager and stop the Robots Agent service.

Bundle the RSA key in a file

Use the EncryptionKeyCLI.exe utility to bundle the Robots Agent RSA key in a file.

1. Open the Windows command prompt as administrator.
2. If you are using an IT account, do the following:
   1. Run the following command to impersonate the current Robots Agent service account:

      runas /user:<domain>\<service_account> cmd

   2. Enter the password for the current service account.

      A second command prompt window opens, running under the current Robots Agent service account. Perform the remaining steps in this procedure in the second command prompt.

3. Run the following command to change to the Robots Agent installation directory:

   cd C:\Program Files (x86)\ACL Software\Robots Agent\agent

   Specify the appropriate path if the Robots Agent is not installed in the default directory.

4. Run the following command to bundle the Robots Agent RSA key in a zip file:

   EncryptionKeyCLI.exe export RSAKeyfile ACL_XXXXXXXX

   For ACL_XXXXXXXX , substitute the actual RSA key name that you copied from the Agent management screen in Robots.

   RSAKeyfile can be any file name, without spaces, that you want to specify. You can optionally specify a file path to an existing folder on the server. If the path contains any spaces, enclose the entire path and the file name in double quotation marks.

5. If required, enter Y to overwrite an existing file.

   Result The RSA key is bundled in a zip file and saved in the default location (C:\ProgramData\robots\RSAKeyfile.zip) or in the location that you specified.

   Note

   If you do not see the ProgramData folder it may be hidden. To make the folder visible, in Windows File Explorer select Hidden items in the C:\ root directory (View tab > Hidden items).

Copy the RSA key to the new service account

Use the EncryptionKeyCLI.exe utility to extract the RSA key from the zip file and import it to the Microsoft keystore for the new service account.

1. If you logged on to the server with an IT account, do the following:
   1. In the Windows command prompt for the IT account, run the following command to impersonate the new Robots Agent service account:

      runas /user:<domain>\<service_account> cmd

   2. Enter the password for the new service account.

      A third command prompt window opens, running under the new Robots Agent service account. Perform the remaining steps in this procedure in the third command prompt.

2. If you logged on to the server with the current Robots Agent service account, do the following:

   1. Log off from the server.

   2. Log on using the new Robots Agent service account.

3. Manually copy RSAKeyfile.zip from the location where you saved it to the Robots Agent installation directory.

   The default location for the saved zip file is: C:\ProgramData\robots\RSAKeyfile.zip

   The default Robots Agent installation directory is: C:\Program Files (x86)\ACL Software\Robots Agent\agent

4. Run the following command to change to the Robots Agent installation directory:

   cd C:\Program Files (x86)\ACL Software\Robots Agent\agent

   Specify the appropriate path if the Robots Agent is not installed in the default directory.

5. Run the following command to extract the Robots Agent RSA key from the zip file and import it to the Microsoft keystore:

   EncryptionKeyCLI.exe import RSAKeyfile

   If you did not use RSAKeyfile as the name of the zip file, substitute the name that you used.

Change the Robots Agent service to the new service account

1. In the Windows Services manager, right-click the Robots Agent service and select Properties.
2. In the Log On tab, click Browse.
3. In the Select User dialog box, in the Enter the object name to select field, enter the name of the new service account and click Check Names.

   The new service account should be prefilled in the field.

4. Click OK.
5. In the Log On tab, enter and confirm the password for the new service account and click OK.
6. In the Windows Services manager, restart (or start) the Robots Agent service.

Check the Robots Agent is running successfully under the new service account

Perform two checks to make sure the Robots Agent is running successfully under the new service account.

Check the application log

Check the application log file to confirm that the Robots Agent is successfully connected to the Robots app. Go to the end of the log file and look for an INFO|Connected entry with a date and time that aligns with your restart of the Robots Agent service.

The default location of the log file is: C:\acl\robots\logs\application.log

Check the Agent management screen in the Robots app

In the Robots app, go to the Agent management screen and press F5 to reload the page. If the Robots Agent appears with a status of Online, it is successfully running under the new service account.

Revoke temporary account rights

If you temporarily gave the Windows service accounts the right to log on locally, make sure that you now revoke the right.