Change Service Account Passwords

The password for the service account that's used to run the Universal Orchestrator service on the orchestrator server can be changed through standard operating system methods.

On a Linux server, this would be, for example, the command line passwd command executed for the service account running the orchestrator service (by default keyfactor-orchestrator). So, this command on a Linux server might be:

On a Windows server, if you've opted to run the Universal Orchestrator service as a custom service account rather than Network Service, the password would need to be changed in Active Directory or the local user store and in the Services MMC.

For both Windows and Linux servers, the password change for the service account that's used to make the connection to Keyfactor Command when Basic authentication is used follows this process:

1. Change the password for the service account in Active Directory.

2. On the Windows or Linux server, open a command window. For Windows, this should be a PowerShell window open using the “Run as Administrator” option. Change to the directory in which the orchestrator is installed and locate the change_secrets script. By default, this is:

   Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\change_secrets.ps1
   Linux: /opt/keyfactor/orchestrator/change_secrets.sh

3. For Linux only, use the chmod command to make the change_secrets.sh script file executable. The file ships in a non-executable state to avoid accidental execution. For example:

   sudo chmod +x change_secrets.sh

4. For Windows only, in the PowerShell window, run the following command to populate a variable with the password for the service account:

   $credKeyfactor = Get-Credential

   Enter the appropriate username and password when prompted (the service account that the orchestrator uses to connect to Keyfactor Command). Usernames should be given in DOMAIN\username format.

   Or, to avoid being prompted for credentials:

   $keyfactorUser = "DOMAIN\mykeyfactorconnectusername"
   $keyfactorPassword = "MySecurePassword"
   $secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
   $credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)
5. Run the password change script on the Universal Orchestrator server using the following parameters:
   -WebCredential (Windows)

   This is the credential object of the service account that the orchestrator uses to communicate with Keyfactor Command that you created as per Create Service Accounts for the Universal Orchestrator. It is provided as a PSCredential object.

   For Basic authentication password change operations, this parameter A parameter or argument is a value that is passed into a function in an application. is required.

   This parameter cannot be used in conjunction with the ClientSecret or ClientAuthPassword parameter.

   --username (Linux)

   The service account that the orchestrator uses to communicate with Keyfactor Command created as per Create Service Accounts for the Universal Orchestrator. It may be entered either as username@domain (e.g. svc_kyforch@keyexample.com) or DOMAIN\\username (e.g. KEYEXAMPLE\\svc_kyforch).

   For Basic authentication password change operations, this parameter is required.

   This parameter cannot be used in conjunction with the client-secret or client-auth-password parameter.

   --password (Linux)

   The password for the service account that the orchestrator uses to communicate with Keyfactor Command specified with the username parameter.

   Important:  The password for the service account the orchestrator uses to communicate with Keyfactor Command is stored in clear text in the orchestratorsecrets.json file in the configuration directory under the installation directory for the orchestrator. By default, this file is granted read/write permissions for the orchestrator service account running the service on the Linux machine (keyfactor-orchestrator by default) and no permissions for any other users. Access to this file should be strictly controlled.

   This parameter is required if the username parameter is specified.

   Tip:  If you prefer to avoid providing the password at the command line (and storing it in command history), use an input file instead as follows:

   1. Create a file that contains just your password. For example:
      vi my_password_file
   2. When using the password parameter, reference the file. For example:
      --password $(cat my_password_file)
   3. Delete the password file after the install is complete. For example:
      rm my_password_file
   -SecretsPath (Windows) or --secrets-path (Linux)

   The full path and file name of the or the orchestratorsecrets.json file that stores the secret information. This file is found in the configuration directory under the installation directory for the Universal Orchestrator, which is by default:

   Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json
   Linux: /opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json

   The location and file name for this file cannot be changed from the default. The parameter is provided to allow for installations in non-standard locations or multiple locations on the same server.

   This parameter is required.

Windows example using basic authentication:

$keyfactorUser = "KEYXAMPLE\svc_kyforch"
$keyfactorPassword = "MySecurePassword123!"
$secKeyfactorPassword = ConvertTo-SecureString $keyfactorPassword -AsPlainText -Force
$credKeyfactor = New-Object System.Management.Automation.PSCredential ($keyfactorUser, $secKeyfactorPassword)

.\change_secrets.ps1 -WebCredential $credKeyfactor -SecretsPath "C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json"

Saved secrets to 'C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json'
Restarting service KeyfactorOrchestrator-Default

Linux example using basic authentication:

vi password_file_new

sudo ./change_secrets.sh --username svc_kyforch@keyexample.com --password $(cat password_file_new) --secrets-path /opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json

Saving secrets to '/opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json'
Restarting service keyfactor-orchestrator-default

For both Windows and Linux servers, the secret change for the client that's used to make the connection to Keyfactor Command when token authentication is used follows this process:

1. Change the secret for the client in your identity provider (see Create Service Accounts for the Universal Orchestrator).

2. On the Windows or Linux server, open a command window. For Windows, this should be a PowerShell window open using the “Run as Administrator” option. Change to the directory in which the orchestrator is installed and locate the change_secrets script. By default, this is:

   Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\change_secrets.ps1
   Linux: /opt/keyfactor/orchestrator/change_secrets.sh

3. For Linux only, use the chmod command to make the change_secrets.sh script file executable. The file ships in a non-executable state to avoid accidental execution. For example:

   sudo chmod +x change_secrets.sh
4. Run the password change script on the Universal Orchestrator server using the following parameters:
   -ClientSecret (Windows)

   This is the secret of the identity provider client used to authenticate the session with Keyfactor Command (see Create Service Accounts for the Universal Orchestrator).

   For token authentication password change operations, this parameter is required.

   This parameter cannot be used in conjunction with the WebCredential or ClientAuthPassword parameter.

   --client-secret (Linux)

   This is the secret of the identity provider client used to authenticate the session with Keyfactor Command (see Create Service Accounts for the Universal Orchestrator).

   For token authentication password change operations, this parameter is required.

   This parameter cannot be used in conjunction with the username and password or client-auth-password parameters.

   Tip:  If you prefer to avoid providing the secret at the command line (and storing it in command history), use an input file instead as follows:

   1. Create a file that contains just your password. For example:
      vi my_secret_file
   2. When using the password parameter, reference the file. For example:
      --client-secret $(cat my_secret_file)
   3. Delete the password file after the install is complete. For example:
      rm my_secret_file
   -SecretsPath (Windows) or --secrets-path (Linux)

   The full path and file name of the or the orchestratorsecrets.json file that stores the secret information. This file is found in the configuration directory under the installation directory for the Universal Orchestrator, which is by default:

   Windows: C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json
   Linux: /opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json

   The location and file name for this file cannot be changed from the default. The parameter is provided to allow for installations in non-standard locations or multiple locations on the same server.

   This parameter is required.

Windows example using token authentication:

.\change_secrets.ps1 -ClientSecret "aLru2IvZYJh0kFmHa36xs2xTLSpxf4ya" -SecretsPath "C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json"

Saved secrets to 'C:\Program Files\Keyfactor\Keyfactor Orchestrator\configuration\orchestratorsecrets.json'
Restarting service KeyfactorOrchestrator-Default

Linux example using token authentication:

vi my_new_secret

sudo change_secrets.sh --client-secret $(cat my_new_secret) --secrets-path /opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json

Saving secrets to '/opt/keyfactor/orchestrator/configuration/orchestratorsecrets.json'
Restarting service keyfactor-orchestrator-default

rm my_new_secret

When you’re running the Universal Orchestrator in a container, the method for password changes is different and applies only to the Keyfactor Command connect service account. In this scenario, the approach is to tear down the container and stand up a new one. As long as the new container connects to Keyfactor Command with the same set of capabilities, the same service account username, and the same orchestrator name (either the container hostname The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). or the ORCHESTRATOR_NAME parameter), the orchestrator will continue to operate seamlessly and will not need re-approval.

To change the Keyfactor Command connect service account password for a container:

1. Change the service account’s Active Directory password or change the secret for the client in your identity provider (see Create Service Accounts for the Universal Orchestrator).

2. Use an appropriate command to tear down the current orchestrator container (being sure you know its configuration). For example:

   docker compose [-f myconfig.yaml] down

   Or:

   kubectl delete -f myconfig.yaml]
3. Stand up a new container referencing the same set of capabilities, the same service account username, and the same orchestrator name (either the container hostname or the ORCHESTRATOR_NAME parameter) if you want the orchestrator to continue seamlessly without requiring re-approval (see Install the Universal Orchestrator in a Linux Container).