Sync with Microsoft Entra ID
This article will help you get started using Directory Connector to sync users and groups from your Microsoft Entra ID Directory to your Bitwarden organization.
Complete the following processes from the Microsoft Azure Portal before configuring Directory Connector. Directory Connector will require information obtained from these processes to function properly.
Complete the following steps to create an app registration for Directory Connector:
From your Microsoft Azure portal, navigate to the Microsoft Entra ID directory.
From the left-hand navigation, select App registrations or enter App registrations into the search bar.
Select the New registration button and give your registration a Bitwarden-specific name (such as,
bitwarden-dc).Select Register.
Complete the following steps to grant the created app registration the required permissions:
On the created Bitwarden app, select API Permissions from the left-hand navigation.
Select the Add a permission button.
When prompted to select an API, select Microsoft Graph.
Set the following Delegated permissions:
User > User.ReadBasic.All (Read all users' basic profiles)
User > User.Read.All (Read all users' full profiles)
Group > Group.Read.All (Read all groups)
AdministrativeUnit > AdministrativeUnit.Read.All (Only required if you'll be syncing Administrative Units)
Set the following Application Permissions:
User > User.Read.All (Read all users' full profiles)
Group > Group.Read.All (Read all groups)
AdministrativeUnit > AdministrativeUnit.Read.All (Only required if you'll be syncing Administrative Units)
Back on the API Permissions page, select the Grant admin consent for... button.
Complete the following steps to create a secret key to be used by Directory Connector:
On the created Bitwarden app, select Certificates & secrets from the left-hand navigation.
Select the New client secret button and add a Bitwarden-specific description (such as,
bitwarden-dc-secret) and an expiration date. We recommend the longest expiration date period possible, and setting a reminder to update it when required.Select Save once you have finished.
Copy the secret's value to a safe place for later use.
Complete the following steps to obtain the app ID to be used by Directory Connector:
On the created Bitwarden app, select Overview from the left-hand navigation.
Copy the Application (client) ID to a safe place for later use.
Complete the following steps to obtain the tenant hostname to be used by Directory Connector:
From anywhere in the Azure portal, select the icon on the top right navigation bar.
Select the Directory + subscription filter button from the menu located on the left.
Copy the Current directory: value to a safe place for later use.
Complete the following steps to configure Directory Connector to use Microsoft Entra ID. If you haven't already, take the proper Microsoft Entra ID setup steps before proceeding:
Open the Directory Connector desktop app.
Navigate to the Settings tab.
From the Type dropdown, select Azure Active Directory.
The available fields in this section will change according to your selected type.
Enter the collected tenant hostname, application Id, and secret key.
tip
When you are finished configuring, navigate to the More tab and select the Clear Sync Cache button to prevent potential conflicts with prior sync operations. For more information, see Clear Sync Cache.
Complete the following steps to configure the settings used when syncing using Directory Connector:
Open the Directory Connector desktop app.
Navigate to the Settings tab.
In the Sync section, configure the following options as desired:
Option | Description |
|---|---|
Interval | Time between automatic sync checks (in minutes). |
Remove disabled users during sync | Check this box to remove users from the Bitwarden organization that have been disabled in your directory. |
Overwrite existing organization users based on current sync settings | Check this box to always perform a full sync and remove any users from the Bitwarden organization if they are not in the synced user set. |
More than 2000 users or groups are expected to sync. | Check this box if you expect to sync 2000+ users or groups. If you don't check this box, Directory Connector will limit a sync at 2000 users or groups. |
Sync users | Check this box to sync users to your organization. |
User filter | See Specify sync filters. |
Sync groups | Check this box to sync groups to your organization. Checking this box will allow you to specify Group Filters. |
Group filter | See Specify sync filters. |
Use comma-separated lists to include or exclude from a sync based on user email, group name, or group membership.
User filters
The following filtering syntaxes should be used in the User Filter field:
Include/Exclude users by email
To include or exclude specific users from a sync based on email address:
Bashinclude:joe@example.com,bill@example.com,tom@example.com
Bashexclude:jow@example.com,bill@example.com,tom@example.com
User by group membership
You can include or exclude users from a sync based on their Microsoft Entra ID group membership using the includeGroup and excludeGroup keywords. includeGroup and excludeGroup use Group Object ID, available from the Overview page of the group in the Azure Portal or through the Azure AD Powershell:
BashincludeGroup:963b5acd-9540-446c-8e99-29d68fcba8eb,9d05a51c-f173-4087-9741-a7543b0fd3bc
BashexcludeGroup:963b5acd-9540-446c-8e99-29d68fcba8eb,9d05a51c-f173-4087-9741-a7543b0fd3bc
Group filters
note
Nested groups can sync multiple group objects with a single referent in the Directory Connector. Do this by creating an administrative unit with all of your groups listed.
The following filtering syntaxes should be used in the Group Filter field:
Include/Exclude groups
To include or exclude groups from a sync based on group name:
Bashinclude:Group A,Group B
Bashexclude:Group A,Group B
Group by administrative unit (AU)
You can include or exclude groups from a sync based on their tagged Microsoft Entra ID Administrative Units by using the includeadministrativeunit and excludeadministrativeunit keywords. includeadministrativeunit and excludeadministrativeunit use the Object ID of the Administrative Unit:
Bashincludeadministrativeunit:7ckcq6e5-d733-4b96-be17-5bad81fe679d
Bashexcludeadministrativeunit:7ckcq6e5-d733-4b96-be17-5bad81fe679d
tip
Before testing or executing a sync, check that Directory Connector is connected to the right cloud server (e.g. US or EU) or self-hosted server. Learn how to do so with the desktop app or CLI.
To test whether Directory Connector will successfully connect to your directory and return the desired users and groups, navigate to the Dashboard tab and select the Test Now button. If successful, users and groups will be printed to the Directory Connector window according to specified sync options and filters.
It may take up to 15 minutes for permissions for your application to properly propagate. In the meantime, you may receive Insufficient privileges to complete the operation errors.
note
If you get the error message Resource <user id> does not exist or one of its queried reference-property objects are not present, you'll need to permanently delete or restore the user(s) with <user id>. Please note, this was fixed in a recent version of Directory Connector. Update your application if you're still experiencing this error.
Once sync options and filters are configured and tested, you can begin syncing. Complete the following steps to start automatic syncing with Directory Connector:
Open the Directory Connector desktop app.
Navigate to the Dashboard tab.
In the Sync section, select the Start Sync button.
You may alternatively select the Sync Now button to execute a one-time manual sync.
Directory Connector will begin polling your directory based on the configured sync options and filters.
If you exit or close the application, automatic sync will stop. To keep Directory Connector running in the background, minimize the application or hide it to the system tray.
note
If you're on the Teams Starter plan, you are limited to 10 members. Directory Connector will display an error and stop syncing if you try to sync more than 10 members.
This plan is no longer available for purchase. This error does not apply to Teams plans.
Suggest changes to this page
How can we improve this page for you?
For technical, billing, and product questions, please contact support