Syncing users and groups with a directory

bitwarden supports syncing users and/or groups from outside directories through the use of the bitwarden Directory Connector tool.

The following directories are supported:

  • Active Directory
  • Azure Active Directory
  • G Suite (Google)
  • Any other LDAP-based directory

Note

Directory sync is only available to enterprise organizations.

bitwarden Directory Connector Tool

The bitwarden Directory Connector is a windows-based console application (CLI) that allows you to keep your bitwarden organization and user directory in sync. Directory Connector can be run on-demand manually as well as automatically in the background on an configured interval through the use of the included windows service. The tool provides a console-based UI in addition to a full array of command line arguments.

You can install and run Directory Connector on the server that hosts your directory, an administrator’s machine, or any other windows-based device than can access the directory.

Table of Contents

Install

  1. Download the latest version of the Directory Connector installer (.msi) from our GitHub releases page.
    Download Directory Connector Installer
  2. Launch the setup wizard by running (double-clicking) the downloaded .msi installer.
  3. Step through the wizard and complete the installation.
  4. After the setup wizard has successfully completed, you should find a shortcut on your desktop for Directory Connector with the bitwarden logo . The full path to the application can be found at {install_folder}/Console.exe.

Log in to your bitwarden organization account

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 1 (Log in to bitwarden) from the main menu.
  3. Enter your bitwarden login credentials.
  4. If your bitwarden account belongs to more than one organization you will be prompted to select an organization.

Optionally, from the command line:

Console.exe login -e -p [-t] [-o]
Description Argument Example Value Required
Email -e [email protected] y
Password -p mypassword123 y
2FA Token -t 381119 n
Organization Id -o acadad98-b666-498d-b89f-f220f21e453f n

You can also log out with the following command:

Console.exe logout

Configure the directory connection

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 3 (Configure directory connection) from the main menu.
  3. Select the type of directory server you are configuring.
  4. Step through and set each configuration setting for the directory server type that you selected in step 3. The settings are different for each type of directory. You can read more about setting up each type of directory connection in the following articles:

Optionally, from the command line:

Console.exe configdir -t [azure: -i -s -te] [gsuite: -f -u [-d] [-c]] [ad/ldap: -a -path [-port] [-cu] [-u] [-p]]
Description Argument Example Value Required Notes
Type -t 1 y AD = 0, Azure = 1, Other = 2, GSuite = 3

Azure

Description Argument Example Value Required
Application Id -i 0f82b419-c5b3-4b63-8afc-67d240da85a6 y
Secret Key -s c2VjcmV0X2tleQ== y
Tenant -te mycompany.onmicrosoft.com y

G Suite

Description Argument Example Value Required
Secret File -f client_secret.json y
Admin User -u [email protected] y
Domain -d company.com y
Customer Id -c 39204722352 n

Active Directory / Other LDAP

Description Argument Example Value Required
Address -a company.local y
Port -port 389 n
Root Path -path DC=company,DC=local y
Current User -cu n/a n
Username -u [email protected] n
Password -p mypassword n

Note

Any sensitive information such as secret keys and server passwords are encrypted and stored locally in the settings file.

Configure sync options

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 4 (Configure sync) from the main menu.
  3. Step through and set each sync configuration setting. Some settings are dependent on the type of directory connection you are using.

Optionally, from the command line:

Console.exe configsync [-g] [-u] [-i] [-uf] [-gf] [-rd] [ad/ldap: [-go] [-gp] [-gn] [-uo] [-up] [-ue] [-m] [-ps] [-ep] [-es] [-c] [-r]]
Description Argument Example Value Required Notes
Sync Groups -g n/a n  
Sync Users -u n/a n  
Sync Interval -i 5 n Value is in minutes.
User Filter -uf (&(objectClass=user)) n Value syntax is different for each directory type.
Group Filter -gf (&(objectClass=group)) n Value syntax is different for each directory type.
Remove Disabled -rd n/a n  

Note

The syntax for user and group filters is different for each type of directory. Learn more about how user and group filters work in the following article:

Active Directory / Other LDAP

Description Argument Example Value Required
Group Object Class -go group y
User Object Class -uo user y
Group Path -gp CN=Groups n
User Path -up CN=Users n
Group Name Attribute -gn name n
User Email Attribute -ue mail n
Member Attribute -m member n
Use Email Prefix/Suffix -ps n/a n
Email Prefix Attribute -ep sAMAccountName n
Email Suffix -es @company.com n
Creation Date Attribute -c whenCreated n
Revision Date Attribute -r whenChanged n

Manually simulate a sync

You can simulate a directory sync in order to check that all of your configuration settings are setup and working as expected. A sync simulation will query the directory server and print the results to the screen. The results that you see printed to the screen will be what is uploaded and synced to your bitwarden organization whenever a real sync is invoked.

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 5 (Simulate directory sync) from the main menu.
  3. Review the results that are printed in the console window for accuracy.

Optionally, from the command line:

Console.exe sim [-f]
Description Argument Example Value Required Notes
Force -f n/a n Forces a full sync.

Perform a sync

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 6 (Sync directory) from the main menu.

Optionally, from the command line:

Console.exe sync [-f]
Description Argument Example Value Required Notes
Force -f n/a n Forces a full sync.

Manage the background service

The background service allows sync operations to run in the background based on the interval set in your sync configuration.

  1. Launch the Directory Connector console by double clicking the shortcut.
  2. Select option 7 (Control background service) from the main menu.
  3. Select the option you wish to perform: Start, Stop, or Check Status.

Optionally, from the command line:

Console.exe service [-start] [-stop]
Description Argument Example Value Required
Start -start n/a n
Stop -stop n/a n

Note

The application must be run in administrator mode to be able to manage the background service.

Alternatively, you can also manage the background service from the windows service manager window.

  1. Open the windows start menu.
  2. Search for “Services” and select the Services application.
    • If you do not find the “Services” application by searching, you can also open it from the “Run” window by typing services.msc.

Tip

You can configure the bitwarden Directory Connector to run automatically each time the machine starts. Use the windows service manager to set the bitwarden Directory Connector service to “Startup type: Automatic”.

Changing configurations manually

All configuration data is saved to a .json configuration file stored on the local computer. No configuration data in synced to bitwarden servers. You can find the configuration file in it’s default location at C:/ProgramData/bitwarden/Directory Connector/settings.json. Any changes that you make directory to the configuration file will require you to restart the application (if it is currently running).

Note

Some configuration data that is stored in the settings file, such as LDAP server credentials, is encrypted. Therefore, you cannot edit these values directly in this file. Any encrypted data must be edited through the application normally.

Source code

As with everything here at bitwarden, the Directory Connector is open source and hosted on GitHub at https://github.com/bitwarden/directory-connector.

Was this helpful?

Rate this article:

Email Us

Want to talk to a human?

Send Us An Email