Configure Endpoint Clients

A newly enrolled endpoint does not need to know about password policies or settings; it must know only the list ID and the web service URI from which it should download its password secret and policies. Disconnected clients can be Windows, Mac, or Linux systems.

The endpoint client software is provided in two formats: a Windows service and a Python script. The Python script functions on both Windows and non-Windows systems. Both forms of the client software are available as downloads from the web application.

Endpoints using the Windows service must have .NET framework 4.5.2 or later installed. Endpoints using the Python script must have anything in the Python 2.x family from 2.6.x and up. For Privileged Identity 7.3.0 and newer, you may use Python 2.6.x and up or Python 3.x.

Download Installer Files

1. In the web application, select Passwords > Disconnected Accounts.
2. On the target list or endpoint, click the Downloads button.

3. Download the settings file and the client software - either the Windows service or the Python script. You must download the settings.json file to the directory where you will run the client software installer.

Configure the Settings File

The settings file includes the web service URI and the list ID. It also contains information about offline account elevation. If you need to change any of these settings, such as if the web service is installed to a different location, modify settings.json using a text editor.

{
    "ServiceURI": "HTTP://SERVER.EXAMPLE.LOCAL:80/ERPMWEBSERVICE/OfflineUpdateWebService.svc/",
    "TenantGUID": "ca388a55-8f26-87c8-8b54-720556d5ac74",
    "EnableOfflineElevation": true,
    "OfflineElevationWindow": 0,
    "OfflineForceLogout": false
}

By default, the endpoint updates the Windows or Mac administrator account or the Linux root account. If you want to manage an account other than the default, add the value LocalAccountName to the settings file:

{
    "LocalAccountName": "jsmith",
    "ServiceURI": "HTTP://SERVER.EXAMPLE.LOCAL:80/ERPMWEBSERVICE/OfflineUpdateWebService.svc/",
    "TenantGUID": "ca388a55-8f26-87c8-8b54-720556d5ac74",
    "EnableOfflineElevation": true,
    "OfflineElevationWindow": 0,
    "OfflineForceLogout": false
}

If you download the settings.json file for a specific machine, it will contain additional fields about endpoint machine identification, password policy settings, and the shared secret. If you download settings.json from the parent list, these additional fields are added the first time the client connects to the web service.

Endpoint Settings and Local Secret Storage

After installation, the Python script stores its local settings in a settings.json file, while the Windows service stores its settings in the registry under HKLM\Software\Wow6432Node\Lieberman\OfflineUpdateService.

When the endpoint client runs, its status is saved in its local settings. These settings contain the last run time, the machine ID, the client software version, the result code of the last operation, and a status message. If the endpoint can reach the web service, this information is uploaded to the server and is visible in the logs.

The local settings also contain the OfflineSecret. If an endpoint machine does not have a stored secret, or if the secret has expired, the endpoint will obtain a new secret from the web service. The secret is generated on the server using a strong PRNG and is represented as a 32-character string. This secret is saved on the server and associated with the machine ID. It is then downloaded to the endpoint and saved in the local settings.

Because OfflineSecret is the only sensitive value that is locally stored, it is important to protect it. For Windows endpoints, this means running the service as LocalSystem and using ProtectedData to write the encrypted value of the secret to the registry. For Python endpoints, it means making the settings.json file accessible only to root for read, write, and execute (rwx).

Install and Run the Windows Service

1. Log into the endpoint machine as an administrator.
2. Locate REDOfflineAccountsSetup.exe. Make sure that settings.json is in the same folder. Run the installer.

3. Verify and/or correct the following information, supplied from settings.json:
   • Web service URI
   • List ID
   • Local account
4. Click Next.

    

   If you need to update the web service URI or the list ID later, you can reinstall the client or edit ImagePath in the registry at HKEY_LOCAL_MACHINE\SYSTEM\ControlSet\Services\LiebsoftLocalUpdates. Then restart the service.

5. Choose if you want to create a desktop shortcut, then click Next.

6. Click Install.

7. You can choose to start the LiebsoftLocalUpdates service after install.
8. Click Finish.

When the local service starts, it creates a status.json file in the same directory as that service. This file contains the machine ID, the last update time, the version, the status code, and the status message. This information is pushed to the web service and is available for view in the web app. The local service is set to run automatically on startup, so machines that are turned off will resynchronize immediately once turned on and once the web service is available.

If the web service is unavailable when you first configure the local service, the local service starts but does not randomize any passwords. It continues to poll the web service every 60 minutes until it successfully contacts the web service and downloads its client settings. If the client has had at least one successful connection to the web service, then in the future, the local service will randomize passwords even when the web service is unavailable.

Manage Client Logging

The local service log file is located under the installation directory. The default is C:\Program Files (x86)\Lieberman\Offline Accounts\Logs.

The endpoint software attempts to connect to the web service to update the server with log messages as actions occur. If the web service is unavailable while the endpoint client is running, the log information is not sent to the server. Logs that are successfully sent are accessible through the web app either at the list or machine level.

To control logging, open the registry to HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Lieberman\OfflineUpdateService. Modify LoggingThreshold to:

• 0: Trace. Warning: This log includes the password being set.
• 1: Verbose. Logs errors, successes, and detailed messages.
• 2: Logs success and failure messages.
• 3: Logs error messages only.

Launch the Local Password Client

Open the Offline Accounts software. This requires admin rights on the host system.

If the local service has not connected to the web service at least once, several fields in the console will be blank.

The local password client displays information about the host machine, password changes, password policies, and the local service.

• Service URI: The URI of the web service.
• Machine ID: The unique ID used to distinguish this endpoint.
• Machine DNS name: This endpoint's DNS name.
• Machine IP address: This endpoint's IP address.
• Machine MAC address: This endpoint's MAC address.
• Local account name: The account managed by the disconnected account software.
• Machine type: The details of this endpoint's OS version.
• Secret set time: The time when the client secret was last set.
• Next secret update: The time when the client secret is scheduled to update.
• Password set time: The time when the service last set the password.
• Next password update: The time when the service will update the password.
• Password changes: The number of times the service has reset the password.
• Password Policy: The password requirements as defined on the web service.

  For more information about password policies, please see Manage Password Policies for Disconnected Accounts.

• Local service status: The current state of the local service.
• Client version: The software version number.
• Stop Service: Stop the local service.
• Start Service: Start the local service.
• Update secret: Connect to the web service to force an update of the shared secret.
• Test Connection to Web Service: Check the connection to the web service.

Run Client Commands

The client application has several command line arguments that can be run to help with diagnostics. Run the following commands from an administrative command prompt:

• LocalPasswordClient.exe WriteStatus - Returns the most recent status of the local service.
• LocalPasswordClient.exe TestSetPassword NewPassword - Runs the code the local service uses to set the password for a local account. This command can be used to diagnose problems if the service fails to update the password. Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.
• LocalPasswordClient.exe IterationTest - Calculates and times 10,000 derived password generations. This can help determine if the password length or character set overloads the system when deriving passwords. Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.
• LocalPasswordClient.exe Secret - Returns the currently stored secret. Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.
• LocalPasswordClient.exe GeneratePassword Secret 10 14 1 1 1 0 - Generates a password derived from the provided secret and with the provided settings. Input arguments are, in order:
  • Secret: (string) 32-character string.
  • Iteration Count: (int) The number of iterations of derived passwords to calculate.
  • Length: (int) The derived password length.
  • Numbers: (int) Allow numbers in the derived password.
  • Symbols: (int) Allow symbols in the derived password.
  • Lowercase: (int) Allow lowercase letters in the derived password.
  • Simple Hash: (int) Use simple hash password generation. If set to 1, the length, numbers, symbols, and lowercase settings are ignored, though they still must be provided.

  Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.

• LocalPasswordClient.exe PasswordTest - Returns the current derived password based on the stored settings. Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.
• LocalPasswordClient.exe Password - Returns the current derived password and secret based on the stored settings. Make sure you run this command in the same context as the local service (LocalSystem) to replicate the service behavior.

psexec -s "C:\Program Files (x86)\Lieberman\Offline Accounts\LocalPasswordClient.exe" password

Current password:
jcr!Cl*{#;)^#l0~hr Z
Current secret:
kRqsrwwovoJqCgzt87Ji7mSNAqhKKAFy

For more information about PsExec, please see docs.microsoft.com/en-us/sysinternals/downloads/psexec.

For more information about the LocalSystem context, please see Endpoint Settings and Local Secret Storage.

Windows Client Settings

The Windows endpoint client can accept settings from multiple sources. You can specify settings through one or more of these input methods. Settings from multiple sources are applied in the following order:

• Settings passed on the command line to the local service at startup. These settings must be specified as part of the service configuration during installation.
• Settings passed as part of the OfflineUpdateService.exe.config file. This file is located in the same directory as the local service executable.
• Settings saved to HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Lieberman\OfflineUpdateService in the local registry. While settings stored in this key preserve the state of the disconnected service itself, you can overwrite or add to these settings either on startup or as it is running.

Install and Run the Python Script

1. Log into the endpoint machine as an administrator.
2. Locate the installer package. Make sure that settings.json is in the same folder.
3. If you downloaded the .tar or .zip version of the installer, extract the file.
4. You may move localUpdateServicePython.py and settings.json to another location. Make sure you keep the two files together, and make sure you make note of the path.

   For a Linux distribution, we recommend that you save the Python script and settings files to a path accessible only to root, such as /root/bin/REDOA or /bin/REDOA.

Run the Python Script

The script must be run as root or equivalent. Set up a cron job or contab job to schedule the script to run as often as needed. You can use crontab -e or sudo contab -e to edit the contab file as root. Add a line to the file to create the new job. For example, if you want the script to run every minute, the new line would look like this:

*/1 * * * * python /root/bin/REDOA/localUpdateServicePython.py > /root/bin/REDOA/cron.log

In the example above, the path to Python is set in the environment. If Python is not part of the path or if the system must use a different version of Python than the one specified in the path, you can use the full path to the Python distribution, such as /etc/python27/python.

If you don't provide a settings.json file to the execution directory, you can specify the list ID and web service URI as command line parameters to the Python script:

*/1 * * * * python /root/bin/REDOA/localUpdateServicePython.py 0 https://server.example.int/erpmwebservice/OfflineUpdateWebService.svc/ > /root/bin/REDOA/cron.log

If you specify command line arguments as input to the script, those settings are used instead of the settings specified in the settings.json file, even if the file is present.

The first part of the contab entry is the scheduling frequency. Next are the path to Python and the path to the installer. You may also include the list ID, the web service URI, the path to the cron file for logging job results, the service certificate file path, and the local account name.

The trailing slash on the web service URI is required.

Python Script Options

When executed from the command line, the Python script includes several command line arguments intended to help diagnose health and status of the endpoint. The command line arguments are single strings. You should pass only one argument at a time. For example:

$ python /root/bin/REDOA/localUpdateServicePython.py SecretAndPassword

Available commands:

• Version - Returns the endpoint client version.
• SecretAndPassword - Returns the currently stored secret, the number of times a password has been generated since the secret was created, and the current derived password.
• LastPassword - Returns the last password based on the recorded last password set time.
• Settings - Returns the current endpoint client settings.
• Reset - Clears all locally saved settings except the web service URI and list ID. This causes the endpoint client to get a new machine ID, to request a new secret, and to trigger an immediate password change the next time the script is run normally.

Client Logging

The service log is located in the same directory as the Python script and is named localupdateservicepython.log. The Python script includes flags that control the logging threshold (verbosity and log-to-console output) and the ability to clear the log file before each run.

The endpoint software attempts to connect to the web service to update the server with log messages as actions occur. If the web service is unavailable while the endpoint client is running, the log information is not sent to the server. Logs that are successfully sent are accessible through the web app either at the list or machine level.