Sync with Google Workspace

This article will help you get started using Directory Connector to sync users and groups from your Google Workspace (formerly "G Suite") Directory to your Bitwarden organization.

To setup directory sync with Google Workspace (formerly "G Suite"), you will need access to the Google Workspace Admin Portal and Google Cloud Platform Console. Directory Connector will require information obtained from these processes to function properly.

Complete the following steps to create a Google Cloud project to use to connect Directory Connector to your directory. If you already have a Google Cloud project available, skip to Enable Admin SDK:

1. In the GCP Console, select the Create Project button.

2. Enter a Bitwarden-specific name for the project (for example, bitwarden-dc-project) and select the Create button.

Complete the following steps to enable the Admin SDK API, to which Directory Connector will make requests:

1. In the GCP Console, select the created or pre-existing project.

2. From the left-hand navigation, select APIs & Services → Library.

3. In the search box, enter Admin SDK and open the Admin SDK API service.

4. Select the Enable button.

Complete the following steps to create a service account to use when making API calls:

1. In the GCP Console, select the created or pre-existing project.

2. From the left-hand navigation, select APIs & Services → Credentials.

3. Select the Create Credentials button, and select Service account from the dropdown.

4. Fill in the Service account details section, and select the Create button.

5. In the Grant this service account access to project section, select Project → Owner from the Role dropdown and select the Continue button.

6. Select the Done button.

Complete the following steps to obtain the appropriate permissions for the created service account:

1. In the GCP Console, select the created or pre-existing project.

2. From the left-hand navigation, select IAM & Admin → Service Accounts.

3. Select the created service account.

4. On the Service Account Details page, select the Add Key button and select Create new key from the dropdown.

5. Select the Key type JSON and select the Create button to download a JSON-formatted key to your local machine.

6. Back on the details tab of your service account, select the Advanced settings drop-down.

7. Enter a Product name for the consent screen.

8. Select the Configure link in the text box with the text “An OAuth consent screen must be configured in order to create an OAuth client".

9. Choose a User Type of Internal and select Create.

10. Give your app a name, like “Bitwarden Directory Connector,” and at a minimum supply a User Support and Developer Contact email address. Select Save and Continue.

11. Select Add or remote scopes, and in the Manually add scopes section, paste the following:

    BashCopy
    https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly

    Select Add to table and then Update.

12. Click Save, Continue, and finally Back to Dashboard.

Complete the following steps to authorize the client to read your directory:

1. Open the Google Admin Portal.

2. From the left-hand navigation, select Security → API Controls.

3. Select the Manage Domain Wide Delegation button.

4. Select the Add new button.

5. In the Client ID field, paste the created Client ID.

   To retrieve the created Client ID, open the GCP Console and navigate to API & Services → Credentials.

6. In the OAuth scopes field, paste the following value to grant only read-access:

   BashCopy
   https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly

7. Select the Authorize button.

Complete the following steps to configure Directory Connector to use your Google directory:

1. Open the Directory Connector desktop app.

2. Navigate to the Settings tab.

3. From the Type dropdown, select G Suite (Google).

   The available fields in this section will change according to your selected type.

4. Enter the Domain of your Google account.

5. Enter the email address of an Admin User with full access to your Google directory.

6. If you have one, enter the Customer ID of your directory. Many users will not have or be required to enter a Customer ID.

7. Select the Choose File button and select the downloaded JSON key.

Complete the following steps to configure the setting used when syncing using Directory Connector:

1. Open the Directory Connector desktop app.

2. Navigate to the Settings tab.

3. In the Sync section, confiture the following options as desired:

Use comma-separated lists to include or exclude from a sync based on user email or group.

The Admin SDK API provides limited filtering capabilities for users and groups with a query parameter. To learn more:

• Search for users

• Search for groups

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:

BashCopy
include:joe@example.com,bill@example.com,tom@example.com

BashCopy
exclude:joe@example.com,bill@example,tom@example.com

Concatenate with query

To concatenate a user filter with the query parameter, use a pipe (|):

BashCopy
include:john@example.com,bill@example.com|orgName=Engineering orgTitle:Manager

BashCopy
exclude:john@example.com,bill@example.com|orgName=Engineering orgTitle:Manager

Use only query

To use only the query parameter, prefix the query with a pipe (|):

BashCopy
|orgName=Engineering orgTitle:Manager

Group filters

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:

BashCopy
include:Group A,Group B

BashCopy
exclude:Group A,Group B

Include groups with wildcard

BashCopy
|name:*marketing*

Wildcards * are supported on both sides of the search parameter. Additionally, the search is not case sensitive.

Concatenate with query

To concatenate a group filter with the query parameter, use a pipe (|):

BashCopy
include:name='Engineering'|email:admin*

BashCopy
exclude:name='Engineering'|email:admin*

Use only query

To use only the query parameter, prefix the query with a pipe (|):

BashCopy
|memberKey=user@company.com

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 the specified sync options and filters:

Once sync options and filters are configured and tested, you can begin syncing. Complete the following steps to start automatic syncing with Directory Connector:

1. Open the Directory Connector desktop app.

2. Navigate to the Dashboard tab.

3. 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.