Skip to main content

Directory Connector desktop app

The Directory Connector desktop app is a standalone desktop application that can be used to group associations from a selection of directory services and to sync users and groups.

Directory Connector is also available as a CLI tool. The desktop application and CLI share a database and configurations. You can use both, however simultaneous use is not recommended.

Download Directory Connector desktop app

Download and install the Directory Connector desktop app on:

Installing Directory Connector desktop app on Linux (with GUI)

Note

Bravura Security verified the following steps on a RHEL9 system. Perform all the steps below as a user with admin privileges.

  1. Download the dc.zip file from https://github.com/Bravura-Security/bravura-safe_directory-connector/releases/tag/2022-06.

    The download contains files for the Bravura Safe Command Line Interface (CLI) and the Directory Connector desktop application (for Linux).

  2. Extract the .zip file into a directory named dc.

  3. Transfer the dc directory to the Linux server (e.g., using WinSCP). The location of this directory should not matter as long as it is accessible by an administrator.

    For example: /home/<user>/dc

  4. In the dc directory, confirm that the following files are available:

    • Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    • bsafedc

  5. Make the files executable using the following commands:

    chmod +x Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    chmod +x bsafedc

  6. Install dependencies for the Directory Connector desktop app using the following command:

    sudo dnf install gtk3 mesa-libGL xorg-x11-server-Xvfb

  7. Navigate to the dc folder:

    cd dc

  8. Run the desktop app using the following command:

    ./Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    The Directory Connector desktop application window appears:

    safe_dc_desktop_launched

Installing Directory Connector desktop app on Linux (headless)

Note

Bravura Security verified the following steps on a RHEL9 headless system. Perform all the steps below as a user with admin privileges.

  1. Download the dc.zip file from https://github.com/Bravura-Security/bravura-safe_directory-connector/releases/tag/2022-06.

    The download contains files for the Bravura Safe Command Line Interface (CLI) and the Directory Connector desktop application (for Linux).

  2. Extract the .zip file into a directory named dc.

  3. Transfer the dc directory to the Linux server (e.g., using WinSCP). The location of this directory should not matter as long as it is accessible by an administrator.

    For example: /home/<user>/dc

  4. In the dc directory, confirm that the following files are available:

    • Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    • bsafedc

  5. Make the files executable using the following commands:

    chmod +x Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    chmod +x bsafedc

  6. Install dependencies for the Directory Connector desktop app using the following command:

    sudo dnf install gtk3 mesa-libGL xorg-x11-server-Xvfb

  7. (If you are using a headless Linux system) On a Windows server, download an X11 display server for Microsoft Windows operating systems. We used Xming in the example below.

    Xming enables Windows users to forward graphical applications from remote Linux/UNIX systems.

    If you have a Linux system with a UI, then an X11 display server for Windows is not required.

  8. Install any additional dependencies for the X11 display server.

  9. On a Windows server, use PuTTY to SSH into the Linux system:

    1. Launch PuTTY.

    2. In the Category panel at left, expand Connection > SSH and select X11.

      safe_dc_putty_x11_settings

    3. Check the box for Enable X11 forwarding.

    4. Set X display location to localhost:0.

    5. In the Category panel at left, select Session.

      safe_dc_putty_host_settings

    6. Enter the appropriate:

      Host Name (or IP address) - the location of your Directory Connector

      Port - same

      Saved Sessions - desired name

    7. Click Save to save the session for future use.

    8. Click Open.

  10. In the PuTTY session (logged in to the Linux system), navigate into the dc folder:

    cd dc

    Note

    The X11 display server is running in the background. It is required to display the Directory Connector desktop application GUI.

  11. Run the desktop app using the following command:

    ./Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

    The Directory Connector desktop application window appears:

    safe_dc_run_app_image

    Note

    To run the app image from another Linux system and display the Directory Connector desktop app GUI, use the following commands:

    ssh -X <server IP>

    cd dc

    ./Bravura-Safe-Connector-2022.6.1-x86_64.AppImage

Installing Directory Connector desktop app on Windows

Note

Bravura Security verified these steps on Windows 2022. All steps should be performed as a user with admin privileges.

A minimum of 5GB RAM is recommended to run the Bravura Safe Directory Connector Desktop App on a Windows system.

Prerequisites

  1. Download Node.js version 16 from https://nodejs.org/en/download.

    Ensure the correct version is selected by clicking Windows Installer (.msi).

    safe_dc_desktop_download_nodejs

  2. Run the downloaded MSI installer using the default settings.

  3. Download the Source code (.zip) file from https://github.com/Bravura-Security/bravura-safe_directory-connector/releases/tag/2022-06.

  4. Right-click on the downloaded .zip file and select Extract All…

  5. Specify a directory to extract the files to (e.g. C:\temp) and click Extract.

    A directory should be created called bravura-safe_directory-connector12.2.

  6. Rename this directory to simplify it or leave it as-is.

Build and run the Directory Connector desktop app

  1. Launch a command-line window with elevated privileges and point to the Bravura Safe Directory Connector directory.

  2. Run the following commands:

    npm install

    npm run reset # Only necessary if you have previously run the CLI app

    npm run rebuild

    npm run electron

  3. If successful, you should see the Directory Connector desktop app window appear. This may take a few minutes depending on your system specifications.

    safe_dc_desktop_launched

    • Do not close the command-line window. Doing so will terminate the desktop app.

    • If nothing appears after 5 minutes, refer to the console output for any errors.

Notes

  • When you launch the app, you may see the developer tools appear. You can close this by clicking on the X at top right.

    safe_dc_desktop_launch_devtools

  • If you are switching between the Directory Connector desktop app and the CLI, ensure that you run npm run reset each time.

  • You may see errors relating to Git in the console. You may ignore this.

    safe_dc_desktop_git_errors

  • You may come across the following error, particularly when you have previously run the desktop app:

    [Main] (node:7668) electron: Failed to load URL: file:///C:/temp/directory-connector/build/index.html with error: ERR_FILE_NOT_FOUND

    Wait a few moments until the application completely loads. This may take a few minutes depending on your system specifications.

Run Directory Connector desktop app at startup

  1. In the Bravura Safe Directory Connector directory, create a batch file (e.g. “run_directory_connector.bat”) that contains the following:

    @echo off

    call npm install

    call npm run reset

    call npm run rebuild

    call npm run electron

  2. Open the Windows Task Scheduler.

  3. On the right, click Create Basic Task…

  4. Specify the name as Run Directory Connector and click Next.

  5. On the Task Trigger screen, choose When I log on and click Next.

  6. Click Next to accept Start a program as the Action.

  7. Locate the batch file you created by clicking Browse…

  8. Specify the path of the Bravura Safe Directory Connector directory in the Start in (optional) field.

    safe_dc_desktop_task_wizard

  9. Click Next.

  10. Click Finish to create the task.

    safe_dc_desktop_task_wizard2

  11. Locate the task and select it.

    safe_dc_desktop_task_scheduler

  12. Click Properties in the right panel.

  13. Select Run with highest privileges.

    safe_dc_desktop_properties

  14. Click OK.

  15. Click Run on the right.

  16. Wait until the Directory Connector Desktop app launches. If it does, the task is running properly and it should launch the next time you log in.

Build and run the Directory Connector CLI

  1. Launch a command-line window with elevated privileges and point to the Bravura Safe Directory Connector directory.

  2. Run the following commands:

    npm install

    npm run reset # Only necessary if you have previously run the desktop app

    npm run build:cli:watch

  3. Once compiled, you should see the following:

    safe_dc_desktop_compiled

  4. Open a separate command-line window, and launch the CLI by running the following command:

    node ./build-cli/bsafedc.js

Notes

  • To run the CLI in the future, simply run the following command from the root Bravura Safe Directory Connector folder:

    node ./build-cli/bsafedc.js

Setting up the Directory Connector desktop app

If you are setting authentication values, such as keys or secrets, in the Directory Connector data.json file, you must use the directory connector desktop application to set these values. This is because authentication values of this type cannot be set in plain text using the CLI, they must use the encrypted version that the desktop application inputs for you.

To get started using the Directory Connector desktop app:

  1. Download and install the Directory Connector desktop app.

  2. Change the Server URL used by Directory Connector before logging in:

    1. On the login screen, click the Settings link.

    2. In the Server URL field, enter the domain name for your Bravura Safe with https://. For example, https://your.domain.safe.com.

    3. Click Save.

  3. Log in to Directory Connector using your Team API Key. If you do not have the API Key, reach out to a Team owner.

  4. On the Settings tab, connect to your directory and configure sync options. This procedure will vary based on the directory in use. Refer to one of the following topics for instruction:

    If you are re-configuring sync options, click the More tab and select the Clear Sync Cache button to prevent potential conflicts with prior sync operations. See Clear Sync Cache for more information.

  5. On the Settings tab, select your Team from the Team drop-down.

  6. Perform a Test Sync to check that your directory connection and sync options are successfully configured and working as expected:

    1. Open the Dashboard tab.

    2. Click the Test Now button.

    Sync testing will query the directory server and print the results to the dashboard. If the printed results match your expectations, you're ready to start syncing.

Sync with Directory Connector

Directory Connector can be used to run a one-time manual sync or automatic sync polling.

Bravura Safe Directory Connector sync cannot handle the following cases:

  • When users and/or groups are moved out of an OU, the users and/or groups are not removed from the Bravura Safe Team.

  • Deleted groups from an OU are not removed from the Bravura Safe Team, and group memberships remain.

In these cases, remove the users or groups manually from the Bravura Safe Team.

Automatic Sync

Automatic syncing will poll your directory based on the interval specified in your sync options as long as the application is open.

Note

If you exit or close the application, automatic sync polling will stop.

To start automatic sync polling with Directory Connector, open the Dashboard tab and click Start Sync.

Manual Sync

To run a one-time manual sync from your directory to your Team, open the Dashboard tab and click Sync Now.

Synced users will be invited to your Team, and groups will be immediately created.

Directory Connector File Storage

The Directory Connector desktop application and CLI share the same database and configuration settings. You can install and use both applications, however it is not recommended to use them simultaneously.

Using the desktop application first to setup and configure all of your settings can be helpful, before using the Directory Connector CLI.

Config file

The Directory Connector configuration file, data.json contains objects you may directly edit to:

  • Set the connection to your directory

  • Configure sync options

    Note

    It is not possible to setup the entirety of Directory Connector from data.json. Authentication values, like keys or secrets, must be set from either the desktop application or CLI.

    Warning

    Avoid opening or modifying data.json while the Directory Connector desktop application or CLI executable is running.

Sample data.json file
{
	"global": {
		"locale": "en",
		"theme": "system",
		"window": {
			"width": 1109,
			"height": 801,
			"isMaximized": false,
			"displayBounds": {
				"x": 0,
				"y": 0,
				"width": 1440,
				"height": 900
			},
			"x": 82,
			"y": 86
		},
		"stateVersion": 3,
		"environmentUrls": {
			"base": "https://safe.domain.com",
			"api": null,
			"identity": null,
			"webVault": null,
			"icons": null,
			"notifications": null,
			"events": null,
			"keyConnector": null
		},
		"installedVersion": "2022.06.01"
	},
	"authenticatedAccounts": [
		"77ec734c-217c-44de-8b85-ae7500d5ae5d"
	],
	"appId": "08027b95-1b1e-4a3e-b692-6e9f6f9f9792",
	"77ec734c-217c-44de-8b85-ae7500d5ae5d": {
		"data": {
			"ciphers": {},
			"folders": {},
			"sends": {},
			"collections": {},
   

			"policies": {},
			"passwordGenerationHistory": {}
		},
		"keys": {
			"cryptoSymmetricKey": {},
			"organizationKeys": {},
			"providerKeys": {},
			"privateKey": {},
			"apiKeyClientSecret": "[STORED SECURELY]"
		},
		"profile": {
			"userId": "77ec734c-217c-44de-8b85-ae7500d5ae5d",
			"apiKeyClientId": "organization.77ec734c-217c-44de-8b85-ae7500d5ae5d",
			"entityId": "77ec734c-217c-44de-8b85-ae7500d5ae5d"
		},
		"settings": {
			"biometricLocked": null,
			"environmentUrls": {
				"base": null,
				"api": null,
				"identity": null,
				"icons": null,
				"notifications": null,
				"events": null,
				"webVault": null,
				"keyConnector": null
			},
			"pinProtected": {
				"decrypted": null,
				"encrypted": null
			},
			"protectedPin": null,
			"settings": null,
			"vaultTimeoutAction": "lock"
		},
		"tokens": {
			"accessToken": "earer-access-token"
		},
		"directoryConfigurations": {
			"ldap": {
				"ssl": false,
				"startTls": false,
				"sslAllowUnauthorized": false,
				"port": 389,
				"currentUser": false,
				"ad": true,
				"pagedSearch": true,
				"hostname": "hostname",
				"username": "username",
				"password": "[STORED SECURELY]",
				"rootPath": "DC=domain,DC=com"
			},
			"gsuite": {
				"privateKey": null
			},
			"azure": {
				"key": "[STORED SECURELY]"
			},
			"okta": {
				"token": "[STORED SECURELY]"
			},
			"oneLogin": {
				"region": "us",
				"clientSecret": "[STORED SECURELY]"
			}
		},
		"directorySettings": {
			"directoryType": 0,
			"organizationId": "77ec734c-217c-44de-8b85-ae7500d5ae5d",
			"lastUserSync": null,
			"lastGroupSync": null,
			"lastSyncHash": null,
			"syncingDir": null,
			"sync": {
				"users": true,
				"groups": false,
				"interval": 5,
				"removeDisabled": false,
				"overwriteExisting": false,
				"largeImport": false,
				"useEmailPrefixSuffix": false,
				"creationDateAttribute": "whenCreated",
				"revisionDateAttribute": "whenChanged",
				"emailPrefixAttribute": "sAMAccountName",
				"memberAttribute": "member",
				"userObjectClass": "person",
				"groupObjectClass": "group",
				"userEmailAttribute": "mail",
				"groupNameAttribute": "name",
				"groupPath": "CN=Users",
				"userPath": "OU=BravuraSafe"
			},
			"userDelta": null,
			"groupDelta": null
		},
		"clientKeys": {}
	},
	"accountActivity": {
		"77ec734c-217c-44de-8b85-ae7500d5ae5d": 1651676057657
	},
	"activeUserId": "77ec734c-217c-44de-8b85-ae7500d5ae5d"
}
Location

The location of data.json depends on which platform is in use:

  • Windows: %AppData%\Bravura Safe Directory Connector

    • Portable: .\safe-connector-appdata

  • macOS: ~/Library/Application Support/Bravura Safe Directory Connector

  • Linux: ~/.config/Bravura Safe Directory Connector

Run the data-file command using the Directory Connector CLI to discover the absolute path to the data.json.

Secret storage

By default, the Directory Connector desktop application and CLI both use a secure method for persisting sensitive data; for example, your directory account password and API keys.

Secrets are always stored as encoded, the encoding is based on the aes-256-cbc algorithm, and a machine key ID; the secrets are tied to a specific machine only. The encoded secrets are stored in the BravuraSafe.json file located in the same folder as the data.json file.

In this section: