bitwarden/help
1
0
Fork 0
mirror of https://github.com/bitwarden/help synced 2025-12-06 00:03:30 +00:00
Code Issues Releases Wiki Activity

Bwdc updates (#353)

Browse Source 
* bwdc updates initial commit

* bwdc 2nd updates

* clean data.json

* link for sample data.json

* return filter article

* typo

* swap order

* data.json clarification

* typo

* fix cache note

* Update gsuite-directory.md
This commit is contained in:
fred_the_tech_writer
2021-01-12 15:39:46 -05:00
committed by GitHub
parent 02c208d49a
commit fd51697c90
17 changed files with 1068 additions and 670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
_articles/directory-connector/azure-active-directory.md
View File

@@ -1,86 +1,174 @@
---
layout: article
title: Configuring directory sync with Azure Active Directory
title: Sync with Azure AD
categories: [directory-connector]
featured: true
popular: false
hidden: false
tags: []
order: 08
---
This article will cover how to connect the Bitwarden Directory Connector application to your Azure Active Directory.
This article will help you get started using Directory Connector to sync users and groups from your Azure Active Directory to your Bitwarden Organization.
## Requirements
## Azure AD Setup
- Read through the following article: [Syncing users and groups with a directory]({% link _articles/directory-connector/directory-sync.md %})
- Install Bitwarden Directory Connector
- Using Directory Connector, log into your Bitwarden account and select your enterprise 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.
## Create a New Application Registration
### Create App Registration
1. Go to <https://portal.azure.com>
2. Select the **Azure Active Directory** resource
3. Navigate to **App registrations** and select **New registration**
{% image directory-connector/azure/new-application.png %}
4. **Name** your application "Bitwarden"
5. Click the **Create** button to create the application.
{% image directory-connector/azure/create-application.png %}
Complete the following steps to create an app registration for Directory Connector:
## Grant Application Permissions
1. From your Microsoft Azure portal, navigate to the **Azure Active Directory** resource.
2. From the left-hand navigation, select **App registrations**.
3. Select the **New registration** button and give your registration a Bitwarden-specific name (e.g. `bitwarden-dc`).
4. Select **Register**.
1. Select the **Bitwarden** application you created in the previous section.
2. Select **API Permissions**.
3. Select the **Add** button to create a new API permission set.
4. For step 1, **Select an API** for **Microsoft Graph**.
5. For step 2, **Select Permissions** for the following:
- Application Permissions:
- "Read all users' full profiles"
- "Read all groups"
- Delegated Permissions:
- "Read all groups"
- "Read all users' full profiles"
- "Read all users basic profiles"
6. Click the **Select** button and then **Done** to add the Microsoft Graph API permissions.
{% image directory-connector/azure/graph-permissions.png %}
7. Click the **Grant Permissions** button to grant the permissions to the application.
{% image directory-connector/azure/grant-permissions.png %}
### Grant App Permissions
## Create Application Secret Key
Complete the following steps to grant the created app registration the required permissions:
1. Go back to the **Bitwarden** application that you created.
2. Select **Certificates & Keys**.
3. Add a new **Password** key by entering a **Name** and **Duration**. We recommend selecting "Never Expires" for the duration.
4. Click **Save** to create a new secret key.
5. Copy the key's value to safe place. We will need to reference it later.
{% image directory-connector/azure/key.png %}
1. On the created Bitwarden application, select **API Permissions** from the left-hand navigation.
2. Select the **Add a permission** button.
3. When prompted to Select an API, select **Microsoft Graph**.
4. 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)
5. Set the following **Application Permissions**:
- User > User.Read.All (Read all users' full profiles)
- Group > Group.Read.All (Read all groups)
6. Back on the API Permissions page, select the **Grant admin consent for...** button.
## Get Your Application ID
### Create App Secret Key
1. Go back to the **Bitwarden** application that you created.
2. Copy the **Application (client) ID** to a safe place. We will need to reference it later.
{% image directory-connector/azure/application-id.png %}
Complete the following steps to create a secret key to be used by Directory Connector:
## Get Your Tenant Hostname
1. On the created Bitwarden application, select **Certificates & secrets** from the left-hand navigation.
2. Select the **New client secret** button and add a Bitwarden-specific description (e.g. `bitwarden-dc-secret`) and an expiration date. We recommend selecting **Never**.
3. Select **Save** once you're finished.
4. Copy the secret's **value** to a safe place for later use.
1. Select the **Directory and Subscription** filter in the top right corner of the Azure Portal.
2. Note the **Current directory** (ex. acmeinc.onmicrosoft.com). This is your **Tenant** hostname. Copy the **Tenant** hostname to a safe place. We will need to reference it later.
{% image directory-connector/azure/tenant.png %}
### Get App ID
## Configure Directory Connector
Complete the following steps to obtain the app ID to be used by Directory Connector:
1. Launch the Directory Connector desktop application.
2. Go to the **Settings** tab.
3. Select **Azure Active Directory** as the directory type.
6. Enter the **Tenant** hostname that you copied from the steps above (ex. company.onmicrosoft.com).
7. Enter the **Application ID** that you copied from the steps above.
8. Enter the Application **Secret** Key that you copied from the steps above.
1. On the created Bitwarden application, select **Overview** from the left-hand navigation.
2. Copy the **Application (client) ID** to a safe place for later use.
Congrats! You are done configuring Azure Active Directory with the Bitwarden Directory Connector.
### Get Tenant Hostname
## Testing
Complete the following steps to obtain the tenant hostname to be used by Directory Connector:
{% callout info %}
It can take up to 15 minutes for the granted permissions for your application to properly propagate. You may receive "Insufficient privileges to complete the operation" errors in the meantime.
1. From anywhere in the Azure portal, select the **Directory + subscription** filter button from the main navigation.
2. Copy the **Current directory:** value to a safe place for later use.
## Connect to your Directory
Complete the following steps to configure Directory Connector to use your Azure Active Directory. If you haven't already, take the proper [Azure AD Setup](#azure-ad-setup) steps before proceeding:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. From the **Type** dropdown, select **Azure Active Directory**.
The available fields in this section will change according to your selected Type.
4. Enter the collected [**Tenant** hostname](#get-tenant-hostname), [**Application Id**](#get-app-id), and [**Secret Key**](#create-app-secret-key).
5. In the **Account** section, select Organization to connect to your directory from the dropdown.
## Configure Sync Options
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
Test your configuration by running a sync test. You should see your Azure Active Directory groups and/or users printed to the screen.
Complete the following steps to configure the settings used when syncing using Directory Connector:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}}).
2. Navigate to the **Settings** tab.
3. 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.|
|Sync users|Check this box to sync users to your Organization.<br><br>Checking this box will allow you to specify **User Filters**.|
|User Filter|See [Specify Sync Filters](#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](#specify-sync-filters).|
### 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:
```
include:joe@example.com,bill@example.com,tom@example.com
```
```
exclude: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 Azure Active Directory 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](https://portal.azure.com){:target="\_blank"} or through the [Azure AD Powershell](https://docs.microsoft.com/en-us/powershell/module/azuread/get-azureadgroup?view=azureadps-2.0){:target="\_blank"}:
```
includeGroup:963b5acd-9540-446c-8e99-29d68fcba8eb,9d05a51c-f173-4087-9741-a7543b0fd3bc
```
```
excludeGroup:963b5acd-9540-446c-8e99-29d68fcba8eb,9d05a51c-f173-4087-9741-a7543b0fd3bc
```
#### 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:
```
include:Group A,Group B
```
```
exclude:Group A,Group B
```
##### Group by Administrative Unit (AU)
You can include or exclude groups from a sync based on their tagged [Azure Active Directory Administrative Units (AUs)](https://docs.microsoft.com/en-us/azure/active-directory/roles/administrative-units){:target="\_blank"} by using the `includeadministrativeunit` and `excludeadministrativeunit` keywords. `includeadministrativeunit` and `excludeadministrativeunit` use the name of the Administrative Unit:
```
includeadministrativeunit:bitwarden
```
```
excludeadministrativeunit:not-bitwarden
```
## Test a Sync
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](#configure-sync-options) and [Filters](#specify-sync-filters):
{% callout info %}
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.
{% endcallout %}
{% image /directory-connector/okta/dc-okta-test.png Test sync results %}
## Start Automatic Sync
Once [Sync Options](#configure-sync-options) and [Filters](#specify-sync-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 Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#configure-sync-options) and [Filters](#specify-sync-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.

19
_articles/directory-connector/clear-sync-cache.md Normal file
View File

@@ -0,0 +1,19 @@
---
layout: article
title: Clear Sync Cache
categories: [directory-connector]
featured: true
popular: false
tags: []
order: 06
---
Directory Connector keeps a local cache while syncing changes to your Bitwarden Organization. This cache allows Directory Connector to **only send the deltas between the two directories** (before / after).
If you encounter sync errors, or if a particular directory change is not being synced as expected, you should clear this cache. Clearing the cache will trigger a full sync to occur during the next sync operation.
To clear the local cache:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **More** tab.
3. In the **Other** section, select the **Clear Sync Cache** button.

168
_articles/directory-connector/directory-sync-cli.md Normal file
View File

@@ -0,0 +1,168 @@
---
layout: article
title: Directory Connector CLI
categories: [directory-connector]
featured: true
popular: false
tags: []
order: 03
---
The Directory Connector CLI is suited toward work in environments where a desktop GUI is unavailable, or if you want to programmatically script directory sync operations using tools provided by the operating system (cron job, scheduled task, etc.). The Directory Connector CLI can be used cross-platform on Windows, macOS, and Linux distributions.
## Getting Started
Complete the following steps to get started with the Bitwarden Directory Connector CLI:
1. Download the CLI from one of the following links:
- [{% icon fa-windows %} Windows CLI](https://vault.bitwarden.com/download/?app=connector&platform=windows&variant=cli-zip)
- [{% icon fa-apple %} macOS CLI](https://vault.bitwarden.com/download/?app=connector&platform=macos&variant=cli-zip)
- [{% icon fa-linux %} Linux CLI](https://vault.bitwarden.com/download/?app=connector&platform=linux&variant=cli-zip)
2. Extract the `.zip` and move the contents (`bwdc` and `keytar.node`) to `/usr/local/bin` or another directory in your `$PATH`. Please note, `keytar.node` **must** be in the same directory as the primary `bwdc` executable.
**Linux Only:** If not already installed, install `libsecret` with your package manager of choice:
```
apt-get install libsecret-1-0
brew install libsecret
```
**Windows Only:** Windows users can [add `bwdc.exe` to the current user's `PATH`](https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/){:target="_blank"}.
3. Verify that the `bwdc` command works in your terminal by running the following:
```
bwdc --help
```
4. Connect Directory Connector to your Directory using the `bwdc config <setting> <value>` command (see [command reference](#config)).
5. Configure Sync Options by editing your `data.json` file (to learn more, see [Directory Connector File Storage]({% link _articles/directory-connector/directory-sync-shared.md %})). Use the `bwdc data-file` command to obtain the absolute path of your `data.json` file.
Available **Sync Options** depend on the directory type in use, so refer to one of the following articles for a list of options available to you:
- [Sync with Active Directory or LDAP]({% link _articles/directory-connector/ldap-directory.md %})
- [Sync with Azure Active Directory]({% link _articles/directory-connector/azure-active-directory.md %})
- [Sync with G Suite (Google)]({% link _articles/directory-connector/gsuite-directory.md %})
- [Sync with Okta]({% link _articles/directory-connector/okta-directory.md %})
- [Sync with OneLogin]({% link _articles/directory-connector/onelogin-directory.md %})
5. Run the `bwdc test` command to check whether your configuration would sync the expected results.
6. Once your Directory and Sync Options are properly configured, and `bwdc test` yields the expected results, run the `bwdc sync` command to start a live sync operation.
## Commands Reference
### login
Use the `login` command to login to Directory Connector with your Bitwarden Account. You must be an Admin or Owner for your Organization to use Directory Connector (for more information, see [User Types and Access Controls]({% link _articles/organizations/user-types-access-control.md %})).
```
bwdc login [options] [email] [password]
```
Options include:
- `--method`: Use this options to specify the [Two-step Login method]({% link _articles/two-step-login/setup-two-step-login.md %}) to use.
- `0` = Authenticator App
- `1` = Email
- `3` = YubiKey
- `--code`: Use this option to specify the [Two-step Login]({% link _articles/two-step-login/setup-two-step-login.md %}) code for the specified `method`.
- `--sso`: Use this option to [Login with SSO]({% link _articles/login-with-sso/about-sso.md %}). Selecting this option will open the SSO Login Flow in your Web Browser. For more information, see [Access your Vault Using SSO]({% link _articles/login-with-sso/sso-access-your-vault.md %}).
For example:
```
bwdc login bwuser@gmail.com mystrongpassword --method 0 --code 204678
```
### logout
Use the `logout` command to logout of the Directory Connector CLI.
```
bwdc logout
```
### help
The Bitwarden Directory Connector CLI is self-documented with `--help` content and examples for every command. List all available commands using the global `--help` option:
```
bwdc --help
```
Use the `--help` option on any *specific* command to learn more about that command:
```
bwdc test --help
bwdc config --help
```
### test
The `test` command queries your directory and prints a JSON formatted array of groups and users that would be synced to your Bitwarden Organization whenever you run a real sync operation.
```
bwdc test
```
Use the `--last` option to test only the changes since the last successful sync.
```
bwdc test --last
```
### sync
The `sync` command runs a live sync operation and pushes data to your Bitwarden Organization.
```
bwdc sync
```
Synced users and groups will be immediately available in your Bitwarden organization. Newly added users will receive an email invite to your Organization.
### last-sync
The `last-sync` command returns an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} timestamp for the last sync operation that was performed for users or groups. You must specify either `users` or `groups` as an `<object>` to run the command against:
```
bwdc last-sync <object>
```
Returns an empty response if no sync has been performed for the given object.
### config
The `config` command allow you to specify your Directory settings:
```
bwdc config <setting> <value>
```
Options include:
- `server <server-url>`
- `directory <directory-type>`
- `ldap.password <password>`
- `azure.key <key>`
- `gsuite.key <key>`
- `okta.token <token>`
- `onelogin.secret <secret>`
`ldap.password`, `azure.key`, `gsuite.key`, `okta.token`, and `onelogin.secret` can **only** be modified from the CLI using `bwdc config`, or from the [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
### data-file
The `data-file` command returns an absolute path to the `data.json` configuration file used by the Directory Connector CLI:
```
bwdc data-file
```
Configuration settings can be modified for the Directory Connector CLI by editing the `data.json` configuration file directly in your favorite text editor.
### clear-cache
The `clear-cache` command allows you to clear cached data that the application stores while performing sync operations. For more information, see [Clear Sync Cache]({% link _articles/directory-connector/clear-sync-cache.md %}).
```
bwdc clear-cache
```
### update
The `update` command allows you to check if your Directory Connector CLI is up-to-date:
```
bwdc update
```
If a newer version is found, the command will return a URL to download a new version. **The Directory Connector CLI will not automatically update.** You will need to use this URL download the new version manually.
{% callout warning %}
If you using the CLI and Desktop App together, it is important to ensure their versions match whenever in use. Running two different versions may cause unexpected issues.
Check the version of the Directory Connector CLI using the `--version` global option.
{% endcallout %}
## Troubleshooting
If you receive an error message referring to the libsecret shared object `Error: libsecret-1.so.0: cannot open shared object file: No such file or directory`, you may need to install libsecret which is required to store things securely on the host.

97
_articles/directory-connector/directory-sync-desktop.md Normal file
View File

@@ -0,0 +1,97 @@
---
layout: article
title: Directory Connector Desktop App
categories: [directory-connector]
featured: true
popular: false
tags: []
order: 02
---
Download the latest version of the Directory Connector Desktop App from our [GitHub releases page](https://github.com/bitwarden/directory-connector/releases){:target="_blank"} or by using one of the following official links:
- [{% icon fa-windows %} Windows Installer (.exe)](https://vault.bitwarden.com/download/?app=connector&platform=windows)
- [{% icon fa-windows %} Windows Portable (.exe)](https://vault.bitwarden.com/download/?app=connector&platform=windows&variant=portable)
- [{% icon fa-apple %} macOS (.dmg)](https://vault.bitwarden.com/download/?app=connector&platform=macos)
- [{% icon fa-linux %} Linux (.AppImage)](https://vault.bitwarden.com/download/?app=connector&platform=linux)
## Setup
Directory Connector configuration will vary based on the directory type in use. Use one of the following articles for instruction:
- [Sync with Active Directory or LDAP]({% link _articles/directory-connector/ldap-directory.md %})
- [Sync with Azure Active Directory]({% link _articles/directory-connector/azure-active-directory.md %})
- [Sync with G Suite (Google)]({% link _articles/directory-connector/gsuite-directory.md %})
- [Sync with Okta]({% link _articles/directory-connector/okta-directory.md %})
- [Sync with OneLogin]({% link _articles/directory-connector/onelogin-directory.md %})
{% callout info %}
If you're using a self-hosted version of Bitwarden, you must change the Server URL used by the Directory Connector application:
1. Log out of Directory Connector.
2. On the Login screen, select the **Settings** button.
3. In the **Server URL** field, enter the domain name for your self-hosted instance with `https://`. For example, `https://bitwarden.example.com`.
4. Select the **Save** button.
{% endcallout %}
## Using Directory Connector
The following sections will walk you through typical actions taken with the Desktop App.
In all cases, log in with a Bitwarden user account that is an Admin or Owner for the relevant Organization(s). For more information, see [User Types and Access Control]({% link _articles/organizations/user-types-access-control.md %}).
### Connect to a Bitwarden Organization
Complete the following steps to specify which Bitwarden Organization to sync to:
1. Open the Directory Connector application.
2. Navigate to the **Settings** tab.
3. In the **Account** section, select your Organization from the dropdown.
### Configure Sync Options
Complete the following steps to configure options for your sync:
1. Open the Directory Connector application.
2. Navigate to the **Settings** tab.
3. In the **Sync** section, configure the available options as desired. Available **Sync Options** depend on the directory type in use, so refer to one of the following articles for a list of options available to you:
- [Sync with Active Directory or LDAP]({% link _articles/directory-connector/ldap-directory.md %})
- [Sync with Azure Active Directory]({% link _articles/directory-connector/azure-active-directory.md %})
- [Sync with G Suite (Google)]({% link _articles/directory-connector/gsuite-directory.md %})
- [Sync with Okta]({% link _articles/directory-connector/okta-directory.md %})
- [Sync with OneLogin]({% link _articles/directory-connector/onelogin-directory.md %})
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
### Perform a Sync Test
Perform a sync test to check that all configured settings are in-place and working as expected. Sync tests will query the directory server and print the results to the Directory Connector **Dashboard**.
1. Open the Directory Connector application.
2. Navigate to the **Dashboard** tab.
3. In the **Testing** section, select the **Test Now** button.
### Perform a Manual Sync
Complete the following steps to run a one-time manual sync between your directory and your Bitwarden Organization:
1. Open the Directory Connector application.
2. Navigate to the **Dashboard** tab.
3. In the **Sync** section, select the the **Sync Now** button.
Your synced users and groups will be immediately available in your Bitwarden Organization. Added users will receive an email invite to your Organization.
### Start Automatic Sync
Complete the following steps to start automatic sync polling with Directory Connector:
1. Open the Directory Connector application.
2. Navigate to the **Dashboard** tab.
3. In the **Sync** section, select the **Start Sync** button.
Directory Connector will begin polling your directory based on the **Interval** specified in your **Sync Options**.
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.

64
_articles/directory-connector/directory-sync-shared.md Normal file
View File

@@ -0,0 +1,64 @@
---
layout: article
title: Directory Connector File Storage
categories: [directory-connector]
featured: true
popular: false
tags: []
order: 04
---
The Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}) and [CLI]({% link _articles/directory-connector/directory-sync-cli.md %}) share the same database and configuration settings. You may install and use both applications, however **it is not recommended to use them simultaneously**.
{% callout success %}
Though not required, it may be helpful to use the Desktop Application first to setup and configure all of your settings before using the Directory Connector CLI.
{% endcallout %}
## Config File
The Directory Connector configuration file (`data.json`) contains objects you may directly edit in order to:
- Set the connection to your Directory
- Configure Sync Options
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]({% link _articles/directory-connector/directory-sync-desktop.md %}) or [CLI]({% link _articles/directory-connector/directory-sync-cli.md %}).
[{% icon fa-download %} Download a sample configuration file]({{site.baseurl}}/files/data.json)
{% callout warning %}
Avoid opening or modifying `data.json` while the Directory Connector Desktop Application or CLI executable is running.
{% endcallout %}
### Location
The location of `data.json` depends on which platform is in use:
- Windows : `%AppData%\Bitwarden Directory Connector`
- Portable: `.\bitwarden-connector-appdata`
- macOS: `~/Library/Application Support/Bitwarden Directory Connector`
- Linux: `~/.config/Bitwarden Directory Connector`
{% callout success %}
Using the Directory Connector [CLI]({% link _articles/directory-connector/directory-sync-cli.md %}), run the `data-file` command to discover the absolute path to the `data.json`.
{% endcallout %}
## Secret Storage
By default, the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}) and [CLI]({% link _articles/directory-connector/directory-sync-cli.md %}) both use a secure method for persisting sensitive data (such as your directory account password, API keys, etc).
On Linux systems this requires [GNOME Keyring](https://wiki.archlinux.org/index.php/GNOME/Keyring){:target="\_blank"} and [X11](https://en.wikipedia.org/wiki/X_Window_System){:target="\_blank"}, which are usually reserved for desktop environments. If you are using a headless Linux environment you may encounter errors such as:
```
Cannot autolaunch D-Bus without X11 $DISPLAY
```
### Secret Storage in Headless Environments
If a secure storage environment is not available, you can configure the Directory Connector CLI to use plaintext storage of secrets. To do so, set the following environment variable to override secure storage:
```
BITWARDENCLI_CONNECTOR_PLAINTEXT_SECRETS=true
```
With plaintext storage enabled, you can then configure all settings directly, in plaintext, from the `data.json` configuration file.
{% callout info %}
Plaintext storage of secrets is not compatible with the Directory Connector desktop application. You should only use the Directory Connector CLI with plaintext storage of secrets.
{% endcallout %}

288
_articles/directory-connector/directory-sync.md
View File

@@ -1,289 +1,61 @@
---
layout: article
title: Syncing users and groups with a directory
title: About Directory Connector
categories: [directory-connector]
featured: true
popular: false
tags: []
tags: [directory connector, directory sync, teams, enterprise]
order: 01
---
Bitwarden supports syncing users and/or groups from outside directories through the use of the **Bitwarden Directory Connector** application. The application will automatically provision and deprovision users, groups, and group associations from your configured user directory.
## What is Directory Connector?
The following directories are supported:
- Active Directory
- Any LDAP-based directory
- Azure Active Directory
- G Suite (Google)
- Okta
- OneLogin
The Bitwarden **Directory Connector** application syncs users and groups to a Bitwarden Organization from a selection of directory services. Directory Connector will automatically provision and de-provision users, groups, and group associations from the source directory.
{% callout info %}
Directory sync is only available to Teams and Enterprise organizations.
Directory Connector functionality is available to **Teams** and **Enterprise** organizations. To use Directory Connector, you must be an Organization Admin or Owner (for more information, see [User Types and Access Control]({% link _articles/organizations/user-types-access-control.md %})).
{% endcallout %}
## Bitwarden Directory Connector Application
{% image /directory-connector/dc-diagram.png %}
The Bitwarden Directory Connector is cross-platform desktop application 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. The Directory Connector application can be installed on Windows, macOS, and most Linux distributions.
A Directory Connector sync operation can be run on-demand or automatically on a configured interval. Directory Connector applications can be installed as an agent on the server that hosts your directory, an administrator's workstation, or any other desktop device that can access the source directory.
You can install and run Directory Connector as an agent on the server that hosts your directory, an administrator's workstation, or any other desktop device that can access the directory.
Directory Connector supports sync from the following sources:
{% image directory-connector/app.png %}
- [Active Directory]({% link _articles/directory-connector/ldap-directory.md%})
- [Any LDAP-based directory]({% link _articles/directory-connector/ldap-directory.md %})
- [Azure Active Directory]({% link _articles/directory-connector/azure-active-directory.md %})
- [G Suite]({% link _articles/directory-connector/gsuite-directory.md %})
- [Okta]({% link _articles/directory-connector/okta-directory.md %})
- [OneLogin]({% link _articles/directory-connector/onelogin-directory.md %})
## Download and Install
## Directory Connector Applications
You can download the latest version of the Bitwarden Directory Connector application from our [GitHub releases page](https://github.com/bitwarden/directory-connector/releases){:target="_blank"} or by using one of the official links below:
Directory Connector is available as a cross-platform [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}) and as a [Command Line Interface (CLI)]({% link _articles/directory-connector/directory-sync-cli.md %}). The Desktop App and CLI [share a database and configurations]({% link _articles/directory-connector/directory-sync-shared.md %}), so you may choose to use both, however simultaneous use is not recommended.
{% image directory-connector/app.png Directory Connector Desktop App %}
### Download Directory Connector
Use the following links to download Directory Connector:
#### Download the Desktop App
Download the latest version of the Directory Connector Desktop App from our [GitHub releases page](https://github.com/bitwarden/directory-connector/releases){:target="_blank"} or by using one of the following official links:
- [{% icon fa-windows %} Windows Installer (.exe)](https://vault.bitwarden.com/download/?app=connector&platform=windows)
- [{% icon fa-windows %} Windows Portable (.exe)](https://vault.bitwarden.com/download/?app=connector&platform=windows&variant=portable)
- [{% icon fa-apple %} macOS (.dmg)](https://vault.bitwarden.com/download/?app=connector&platform=macos)
- [{% icon fa-linux %} Linux (.AppImage)](https://vault.bitwarden.com/download/?app=connector&platform=linux)
The application will prompt you for automatic updates whenever newer versions become available.
#### Download the CLI Tool
Command-line Interface
Download the latest version of the Directory Connector CLI from one of the following links:
- [{% icon fa-windows %} Windows CLI (.exe)](https://vault.bitwarden.com/download/?app=connector&platform=windows&variant=cli-zip)
- [{% icon fa-apple %} macOS CLI](https://vault.bitwarden.com/download/?app=connector&platform=macos&variant=cli-zip)
- [{% icon fa-linux %} Linux CLI](https://vault.bitwarden.com/download/?app=connector&platform=linux&variant=cli-zip)
## Configure environment
By default the Directory Connector communicates with the Bitwarden public cloud servers. If you are using the public cloud version of Bitwarden, you can skip this step. If you are using a self-hosted deployment of Bitwarden you will want to change the configured environment endpoints of the Directory Connector to your own on-premises installation.
1. Run the Directory Connector application.
2. If you are already logged into the application, go to the **More** tab and **Log Out**.
3. On the main log in screen, select the **Settings** button.
4. Enter your installation's base URL and save. For example, `https://bitwarden.example.com`.
## Log in to your Bitwarden organization account
1. Run the Directory Connector application.
2. Log in with your Bitwarden user account that has Admin or Owner access to your organization.
3. Go to the **Settings** tab and select your organization from the **Account** section.
## Configure the directory connection
1. Run the Directory Connector application.
2. Go to the **Settings** tab.
3. Select the **Type** of directory server you are configuring from the **Directory** section.
4. 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:
- [Active Directory & Other LDAP-based Directories Setup]({% link _articles/directory-connector/ldap-directory.md %})
- [Azure Active Directory Setup]({% link _articles/directory-connector/azure-active-directory.md %})
- [G Suite (Google) Setup]({% link _articles/directory-connector/gsuite-directory.md %})
- [Okta Setup]({% link _articles/directory-connector/okta-directory.md %})
- [OneLogin Setup]({% link _articles/directory-connector/onelogin-directory.md %})
## Configure sync options
1. Run the Directory Connector application.
2. Go to the **Settings** tab.
3. Set each configuration setting from the **Sync** section. Some settings are dependent on the **Type** of directory you have configured.
{% callout info %}
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:
- [Configuring user and group sync filters]({% link _articles/directory-connector/user-group-filters.md %})
{% endcallout %}
## Test a sync
You can run a sync test in order to check that all of your configuration settings are setup and working as expected. A sync test 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 performed.
1. Run the Directory Connector application.
2. Go to the **Dashboard** tab.
3. Click the **Test Now** button from the **Testing** section.
## Perform a manual sync
1. Run the Directory Connector application.
2. Go to the **Dashboard** tab.
3. Click the **Sync Now** button from the **Sync** section.
Your synced users and groups will be immediately available in your Bitwarden organization. Synced users will receive an email invite to your organization.
## Sync automatically
1. Run the Directory Connector application.
2. Go to the **Dashboard** tab.
3. Click the **Start Sync** button from the **Sync** section.
The application will begin polling your directory based on the interval you specified in your sync settings. Be sure not to exit/close the application or automatic syncing intervals will stop. You can minimize the application or hide it to the system tray (under the **Window** application menu).
You can click the **Stop Sync** button to end the automatic syncing intervals.
## Clear sync cache
As the Directory Connector works at syncing changes up to your Bitwarden organization it keeps a local cache. This cache helps the Directory Connector only send the difference in directory changes (deltas) from the previous time that it performed a sync operation. If you encounter sync errors or a particular directory change is not correctly being synced, you may need to clear this cache. Clearing the cache will allow a full sync to occur during the next sync operation.
1. Run the Directory Connector application.
2. Go to the **More** tab.
3. Click the **Clear Sync Cache** button from the **Other** section.
## Command-line Interface
A command-line interface (CLI) tool is also available to connect to and sync your directory. The Bitwarden Directory Connector CLI is especially useful whenever you are working in environments where a desktop GUI is not available, or if you want to programmatically script directory sync operations using tools provided by the operating system (cron job, scheduled task, etc). The Bitwarden Directory Connector CLI can be used cross-platform on Windows, macOS, and Linux distributions.
### Quick Start
1. [Download and install](#download-and-install) the Directory Connector CLI for your platform.
2. Move `bwdc` to `/usr/local/bin` or another directory in your `$PATH`. Windows users can [add `bwdc.exe` to the current user's `PATH`](https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/){:target="_blank"}. **IMPORTANT:** Make sure that the included `keytar.node` dependency remains in the same directory as the main `bwdc` executable.
3. Verify the `bwdc` command works in your terminal.
bwdc --help
### Download and Install
See the [download and install](#download-and-install) section above for links to download the CLI executable for your platform.
{% callout info %}
When extracting the zip, make sure that the included `keytar.node` dependency remains in the same directory as the main `bwdc` executable.
Linux users must have `libsecret` installed, which is usually already available on most systems. Example:
apt-get install libsecret-1-0
{% endcallout %}
### Shared Data
The Directory Connector CLI shares the same database and configuration settings with the Directory Connector desktop application. You can install and use both applications together, however, you should avoid using them both at the same time.
Though not required, often times it may be helpful to use the Directory Connector desktop application first to setup and configure all of your settings before using the Directory Connector CLI.
The default location for the shared `data.json` database file depends on which platform you are using.
- Windows : `%AppData%\Bitwarden Directory Connector`
- Portable: `.\bitwarden-connector-appdata`
- macOS: `~/Library/Application Support/Bitwarden Directory Connector`
- Linux: `~/.config/Bitwarden Directory Connector`
The [`data-file` command](#data-file-command) can be used to discover the absolute path to the `data.json` database file on your system.
### Secret Storage
By default, the Directory Connector desktop application and CLI both use a secure method for persisting sensitive data such as your directory account password, API keys, etc. On Linux systems, this requires the GNOME keyring and X11 which are usually reserved for desktop environments. If you are using a headless Linux environment you may encounter errors such as:
> Cannot autolaunch D-Bus without X11 $DISPLAY
If a secure storage environment is not available, you can configure the Directory Connector CLI to use plaintext storage of secrets. Set the following environment variable to override secure storage:
BITWARDENCLI_CONNECTOR_PLAINTEXT_SECRETS=true
With plaintext storage enabled, you can then configure all settings directly, in plaintext, from the `data.json` database file.
{% callout info %}
Plaintext storage of secrets is not compatible with the Directory Connector desktop application. You should only use the Directory Connector CLI with plaintext storage of secrets.
{% endcallout %}
### Explore the CLI
The Bitwarden Directory Connector CLI is self-documented with `--help` content and examples for every command. You should start exploring the Directory Connector CLI by using the global `--help` option:
bwdc --help
This option will list all available commands that you can use with the Directory Connector CLI.
Additionally, you can use the `--help` option on a specific command to learn more about it:
bwdc test --help
bwdc config --help
### Test Command
The `test` command queries your directory and prints a JSON formatted array of groups and users that will be synced to your Bitwarden organization whenever you run a real sync operation.
bwdc test
### Sync Command
The `sync` command runs a live sync operation and pushes data to your Bitwarden organization.
bwdc sync
Your synced users and groups will be immediately available in your Bitwarden organization. Synced users will receive an email invite to your organization.
### Last Sync Command
The `last-sync` command returns an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} timestamp of the last time a sync operation has been performed for users or groups:
bwdc last-sync users
bwdc last-sync groups
### Config Command
The `config` command allow you to specify settings for the Directory Connector CLI to use.
bwdc config <setting> <value>
For example, if you are using a self hosted Bitwarden server you will need to change the endpoint that the Directory Connector CLI communicates with.
bwdc config server https://bitwarden.example.com
You can also use the `config` command to set parameters that require secure storage and cannot be modified directly in the `data.json` database file, such as passwords or access tokens.
bwdc config ldap.password <password>
bwdc config azure.key <key>
bwdc config gsuite.key <key>
bwdc config okta.token <token>
Additional configuration settings can be modified in the Bitwarden Directory Connector desktop application or by editing the `data.json` database file directly in your favorite text editor. [Read more about shared data](#shared-data).
{% callout info %}
You should avoid opening or modifying the `data.json` database file while the Directory Connector desktop application or CLI executable is running.
{% endcallout %}
### Data File Command
The `data-file` command returns an absolute path to the `data.json` database file used by the Directory Connector CLI.
bwdc data-file
Configuration settings can be modified for the Directory Connector CLI by editing the `data.json` database file directly in your favorite text editor. [Read more about shared data](#shared-data).
### Clear Cache Command
The `clear-cache` command allows you to clear cached data that the application stores while performing sync operations. [Read more about clearing sync cache](#clear-sync-cache).
bwdc clear-cache
### Update Command
The `update` command allows you to check if your Directory Connector CLI is up to date. The Directory Connector CLI will not automatically update. You must download new versions of the Directory Connector CLI manually.
bwdc update
A URL to download a new version of the CLI executable will be returned to you.
{% callout info %}
If you are also using the Directory Connector desktop application, it is important that you keep them both up to date and that their versions match. Running two different versions of the Directory Connector desktop application and Directory Connector CLI may cause unexpected issues.
{% endcallout %}
### Version Option
The `--version` option allows you to check which version the Directory Connector CLI you are currently using.
```
bwdc --version
```
### Troubleshooting
If you receive an error message referring to the libsecret shared object `Error: libsecret-1.so.0: cannot open shared object file: No such file or directory`, you may need to install libsecret which is required to store things securely on the host.
### Enums
**Two Step Login Methods**
| Name | Value |
|---------------|-------|
| Authenticator | 0 |
| Email | 1 |
| Yubikey | 3 |
{% callout info %}
Other two-step login methods such as FIDO U2F and Duo are not supported by the CLI.
{% endcallout %}
## 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>.
As with everything at Bitwarden, the Directory Connector is open source and hosted on GitHub at [github.com/bitwarden/directory-connector](https://github.com/bitwarden/directory-connector).

219
_articles/directory-connector/gsuite-directory.md
View File

@@ -1,92 +1,179 @@
---
layout: article
title: Configuring directory sync with G Suite (Google)
title: Sync with Google Workspace
categories: [directory-connector]
featured: true
popular: false
hidden: false
tags: []
order: 09
---
This article will cover how to connect the Bitwarden Directory Connector application to your G Suite directory.
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.
## Requirements
## Google Workspace Setup
- Read through the following article: [Syncing users and groups with a directory]({% link _articles/directory-connector/directory-sync.md %})
- Install Bitwarden Directory Connector
- Using Directory Connector, log into your Bitwarden account and select your enterprise 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.
## Create a Google Cloud Project
### Create a Cloud Project
{% callout info %}
If you already have a Google Cloud project available, you can skip this step and re-use it here.
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](#enable-admin-sdk):
1. In the [GCP Console](https://console.cloud.google.com/home){:target="\_blank"}, select the **Create Project** button.
2. Enter a Bitwarden-specific name for the project (e.g. `bitwarden-dc-project`) and select the **Create** button.
### Enable Admin SDK
Complete the following steps to enable the Admin SDK API, to which Directory Connector will make requests:
1. In the [GCP Console](https://console.cloud.google.com/home){:target="\_blank"}, select the created or pre-existing Project.
2. From the left-hand navigation, select **APIs &amp; Services** &rarr; **Library**.
3. In the search box, enter `Admin SDK` and open the **Admin SDK API** service.
4. Select the **Enable** button.
### Create Service Account
Complete the following steps to create a service account to use when making API calls:
1. In the [GCP Console](https://console.cloud.google.com/home){:target="\_blank"}, select the created or pre-existing Project.
2. From the left-hand navigation, select **APIs &amp; Services** &rarr; **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 &rarr; Owner** from the **Role** dropdown and select the **Continue** button.
6. Select the **Done** button.
### Obtain Service Account Credentials
Complete the following steps to obtain the appropriate permissions for the created service account:
1. In the [GCP Console](https://console.cloud.google.com/home){:target="\_blank"}, select the created or pre-existing Project.
2. From the left-hand navigation, select **IAM &amp; Admin** &rarr; **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 page of your service account, select the **Show Domain-wide Delegation** dropdown.
7. Check the **Enable Domain-wide Delegation** box.
8. Enter a **Product name for the consent screen**.
9. Select **Save**.
### Allow Read-access to Google Workspace
Complete the following steps to authorize the client to read your directory:
1. Open the [Google Admin Portal](https://admin.google.com/u/5/ac/home){:target="\_blank"}.
2. From the left-hand navigation, select **Security** &rarr; **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](https://console.cloud.google.com/home){:target="\_blank"} and navigate to **API &amp; Services** &rarr; **Credentials**.
6. In the OAuth scopes field, paste the following value to grant only read-access:
```
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.
## Connect to your Directory
Complete the following steps to configure Directory Connector to use your Google directory:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#obtain-service-account-credentials).
8. In the **Account** section, select Organization to connect to your directory from the dropdown.
## Configure Sync Options
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
1. Go to <https://console.cloud.google.com/home>
2. Click the **Create** project button
{% image directory-connector/gsuite/create-project.png %}
3. Enter a project name and click **Create**
{% image directory-connector/gsuite/new-project.png %}
4. Refresh the page and you should now see your project
Complete the following steps to configure the setting used when syncing using Directory Connector:
## Enable the Admin SDK API for Your Project
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. In the **Sync** section, confiture the following options as desired:
1. Go to <https://console.cloud.google.com>.
2. Make sure the appropriate project is selected. You should be on the **Dashboard** page for your project.
3. Open the navigation menu and navigate to **APIs &amp; Services** &rarr; **Library**.
4. Search for and select the **Admin SDK** service.
{% image directory-connector/gsuite/admin-sdk.png %}
5. Click the **Enable** button near the top.
{% image directory-connector/gsuite/admin-sdk-enable.png %}
|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.|
|Sync users|Check this box to sync users to your Organization.<br><br> Checking this box will allow you to specify a **User Filter**.|
|User Filter|See [Specify Sync Filters](#specify-sync-filters).|
|Sync groups|Check this box to sync groups to your Organization.<br><br>Checking this box will allow you to specify a **Group Filter**.|
|Group Filter|See [Specify Sync Filters](#specify-sync-filters).|
## Create & Configure a Service Account
### Specify Sync Filters
1. Go to <https://console.cloud.google.com>
2. Make sure the appropriate project is selected. You should be on the **Dashboard** page for your project.
3. Open the navigation menu and navigate to **APIs &amp; Services** &rarr; **Credentials**.
4. Click the **Create credentials** button and select **Service account key**.
{% image directory-connector/gsuite/create-credentials.png %}
5. Select **New service account** from the **Service account** dropdown menu.
6. Name the service account **Bitwarden Directory Connector**. For the role, select **Project** and then **Owner**. Ensure that **JSON** is the selected **Key type**. Upon clicking **Create**, a JSON file will be downloaded; this is important for later so keep a note of where you have downloaded it.
{% image directory-connector/gsuite/create-service-account.png %}
7. You should now see your newly created service account listed. Click on **Manage service accounts** (on the right-hand side).
{% image directory-connector/gsuite/click-manage-service-accounts.png %}
8. Select the options button next to your service account, and select **Edit**.
{% image directory-connector/gsuite/edit-service-account.png %}
9. Check the box "Enable G Suite Domain-wide Delegation", enter anything for "Product name for the consent screen" and click **Save**.
{% callout info %}"Enable G Suite Domain-wide Delegation" is only required on some older G Suite accounts. Newer G Suite accounts will automatically have domain-wide delegation enabled for all service accounts. If you do not see the "Enable G Suite Domain-wide Delegation" checkbox option available for your service account, you can assume it is already enabled.{% endcallout %}
{% image directory-connector/gsuite/tick-gsuite.png %}
1. Click **View Client ID** and you'll see the Client ID on screen. You will need the Client ID to configure security within G Suite. Highlight the Client ID and copy it to your clipboard.
{% image directory-connector/gsuite/view-client-id.png %}
{% image directory-connector/gsuite/copy-client-id.png %}
Use comma-separated lists to include or exclude from a sync based on User Email or Group:
## Configure G Suite Security
#### User Filters
1. Go to <https://admin.google.com>
2. Open the navigation menu and navigate to **Security** &rarr; **Settings**.
3. Select the **API reference** option and make sure **Enable API access** is checked.
{% image directory-connector/gsuite/enable-api-access.png %}
4. Back in the list of options, select the **Advanced settings** options and then the **Manage API client access** link.
{% image directory-connector/gsuite/manage-api-access.png %}
5. For **Client Name**, paste the **Client ID** of the service account that you created in the previous steps. For **API Scopes**, paste the following values to grant read-only access to users and groups:
<pre>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</pre>
6. Click the **Authorize** button to save.
{% image directory-connector/gsuite/authorize-client.png %}
7. You should now see your service account listed as an authorized client of G Suite.
{% image directory-connector/gsuite/authorized-client-list.png %}
The following filtering syntaxes should be used in the **User Filter** field:
## Configure Directory Connector
The Admin SDK API provides limited filtering capabilities for users with a `query` parameter. Learn more [here](https://developers.google.com/admin-sdk/directory/v1/guides/search-users){:target="\_blank"}.
1. Launch the Directory Connector desktop application.
2. Go to the **Settings** tab.
3. Select **G Suite Directory** as the directory type.
4. Enter the **Domain** of your G Suite account.
5. Enter the email address of an **Admin User** that has full access to the G Suite directory (such as your own).
6. If you have one, enter the **Customer Id** of your directory (most users won't need to enter a Customer Id).
7. Select the **JSON Key File** that was downloaded whenever you created your service account in the steps above. The **Client Email** and **Private Key** will be automatically extracted from this key file for you.
##### Include/Exclude Users by Email
Congrats! You are done configuring G Suite with the Bitwarden Directory Connector.
To include or exclude specific users from a sync based on email address:
```
include:joe@example.com,bill@example.com,tom@example.com
```
```
exclude:joe@example.com,bill@example,tom@example.com
```
## Testing
##### Concatenate with `query`
Test your configuration by running a sync test. You should see your G Suite groups and/or users printed to the screen.
To concatenate a user filter with the `query` parameter, use a pipe (`|`):
```
include:john@example.com,bill@example.com|orgName=Engineering orgTitle:Manager
```
```
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 (`|`):
```
|orgName=Engineering orgTitle:Manager
```
#### Group Filters
To include or exclude groups from a sync based on Group Name:
```
include:Group A,Group B
```
```
exclude:Group A,Group B
```
## Test a Sync
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](#configure-sync-options) and [Filters](#specify-sync-filters):
{% image /directory-connector/okta/dc-okta-test.png Test sync results %}
## Start Automatic Sync
Once [Sync Options](#configure-sync-options) and [Filters](#specify-sync-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 Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#configure-sync-options) and [Filters](#specify-sync-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.

157
_articles/directory-connector/ldap-directory.md
View File

@@ -1,15 +1,14 @@
---
layout: article
title: Configuring directory sync with Active Directory or other LDAP servers
title: Sync with Active Directory or LDAP
categories: [directory-connector]
featured: true
popular: false
tags: [active directory, ldap, ad]
order: 07
---
An LDAP directory is a collection of data about users and groups. LDAP (Lightweight Directory Access Protocol) is an Internet protocol that web applications can use to look up information about those users and groups from the LDAP server.
We provide built-in connectors for the most popular LDAP directory servers, such as:
This article will help you get started using Directory Connector to sync users and groups from your LDAP or Active Directory service to your Bitwarden Organization. Bitwarden provides built-in connectors for the most popular LDAP directory servers, including:
- Microsoft Active Directory
- Apache Directory Server (ApacheDS)
@@ -19,69 +18,119 @@ We provide built-in connectors for the most popular LDAP directory servers, such
- OpenDS
- OpenLDAP
- Sun Directory Server Enterprise Edition (DSEE)
- A generic LDAP directory server
- Any generic LDAP directory server
## Requirements
## Connect to your Server
- Read through the following article: [Syncing users and groups with a directory]({% link _articles/directory-connector/directory-sync.md %})
- Install Bitwarden Directory Connector
- Using Directory Connector, log into your Bitwarden account and select your enterprise organization
Complete the following steps to configure Directory Connector to use your LDAP or Active Directory:
## Connecting to the LDAP Server
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. From the **Type** dropdown, select **Active Directory / LDAP**.
1. Run the Directory Connector application.
2. Go to the **Settings** tab.
3. Select **Active Directory / LDAP** as the **Type** of directory server you are configuring.
The available fields in this section will change according to your selected Type.
4. Configure the following options:
The following directory configuration options can be set:
|Option|Description|Examples|
|------|-----------|--------|
|Server Hostname|Hostname of your directory server.|`ad.example.com`<br><br>`ldap.company.org`|
|Server Port|Port on which your directory server is listening.|`389` or `10389`|
|Root Path|Root path at which the Directory Connector should start all queries.|`cn=users,dc=ad,dc=example,dc=com`<br><br>`dc=ldap,dc=company,dc=org`|
|This server uses active directory|Check this box if the server is an Active Directory server.||
|This server pages search results|Check this box if the server paginates search results.<br><br>(*LDAP only*)||
|This server uses an encrypted connection|Checking this box will prompt you to select one of the following options:<br><br>**Use SSL** (LDAPS)<br>If your LDAPS server uses an untrusted certificate, you can configure certificate options on this screen.<br><br>**Use TLS** (STARTTLS)<br>If your LDAP server uses a self-signed certificated for STARTTLS, you can configure certification options on this screen.<br>||
|Username|The Distinguished Name of an administrative user that the application will use when connecting to the directory server.<br><br>For Active Directory, the user should be a member of the built-in administrators group.|`cn=admin,cn=users,dc=ad,dc=company,dc=com`<br><br>`company\admin`|
|Password|The password of the user specified above. The password is safely stored in the operating system's native credential manager.||
{% table %}
5. In the **Account** section, select Organization to connect to your directory from the dropdown.
| Property | Description | Examples |
|----------|-------------|----------|
| Server Hostname | The hostname of your directory server. | `ad.example.com` or `ldap.company.local` |
| Port | The port on which your directory server is listening. | 389 or 10389 |
| Root Path | The root path at which the Directory Connector should start all queries. | `cn=users,dc=ad,dc=company,dc=com` |
| SSL | If the server is using LDAP over SSL (LDAPS). | |
| TLS | If the server is using LDAP over TLS (STARTTLS). | |
| Active Directory | If the server is an Active Directory server. | |
| Username | The distinguished name of an administrative user that the application will use when connecting to the directory server. For Active Directory, the user should be a member of the built-in administrators group. | `cn=admin,cn=users,dc=ad,dc=company,dc=com` or `company\admin` (Active Directory) |
| Password | The password of the user specified above. The password is safely stored in the operating system's native credential manager. | |
## Configure Sync Options
{% endtable %}
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
## Configuring Sync Settings
1. Launch the Directory Connector desktop application
2. Go to the **Settings** tab.
3. Configure the appropriate **Sync** settings for your Active Directory or LDAP server.
Complete the following steps to configure the settings used when syncing using Directory Connector:
{% callout info %}
If you are using Active Directory, many of these settings are predetermined for you and are therefore are not shown.
{% endcallout %}
{% table %}
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. In the **Sync** section, configure the following options as disired:
| Property | Description | Examples |
|----------|-------------|----------|
| Interval | The interval, in minutes, that you wish to perform automatic sync checks. | 5 |
| Remove Disabled Users | When a user is disabled in the directory, should they also be removed from your Bitwarden organization? | |
| Overwrite Existing Users | Always perform a full sync and remove any users from your organization if they are not in the synced users set. | |
| Member Attribute | The attribute field to use when loading the group's members. | uniqueMember |
| Creation Date Attribute | The attribute field that specifies when an entry was created. | whenCreated |
| Revision Date Attribute | The attribute field that specifies when an entry was changed. | whenChanged |
| Use Email Prefix/Suffix | Email addresses are required by Bitwarden. If your directory users do not have email addresses they will be skipped. Alternatively, you can specify that users without an email address use a prefix attribute concatenated with a suffix to attempt to form a valid email address. | |
| Email Prefix Attribute | The attribute field to use when forming a user's email address from the prefix/suffix setting. | accountName |
| Email Suffix | The specified suffix to use when forming a user's email address from the prefix/suffix setting. | @example.com |
| Sync Users | Sync users to your organization. | |
| User Filter | A filter for limiting the users that are synced. Read more at [Configuring user and group sync filters]({% link _articles/directory-connector/user-group-filters.md %}). | (&(givenName=John)) |
| User Object Class | The name of the class used for the LDAP user object. | user |
| User Path | This value is used in addition to the root path when searching and loading users. If no value is supplied, the subtree search will start from the root path. | ou=Users |
| User Email Attribute | The attribute field to use when loading the user email address. | mail |
| Sync Groups | Sync groups to your organization. | |
| Group Filter | A filter for limiting the groups that are synced. Read more at [Configuring user and group sync filters]({% link _articles/directory-connector/user-group-filters.md %}). | (&!(name=Sales*)) |
| Group Object Class | The name of the class used for the LDAP group object. | groupOfUniqueNames |
| Group Path | This value is used in addition to the root path when searching and loading groups. If no value is supplied, the subtree search will start from the root path. | ou=Groups |
| Group Name Attribute | The attribute field to use when loading the group name. | name |
|Option|Description|
|------|-----------|
|Interval|Time between automatic sync check (in minutes).|
|Remove disabled users during sync|Check this box to remove users from the Bitwarden Organization that have been disabled in your Organization.|
|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.|
|Member Attribute|Name of the attribute used by the directory to define a group's membership (e.g. `uniqueMember`).|
|Creation Data Attribute|Name of the attribute used by the directory to specify when an entry was created (e.g. `whenCreated`).|
|Revision Date Attribute|Name of the attribute used by the directory to specify when an entry was last changed (e.g. `whenChanged`).|
|If a user has no email address, combine a username prefix with a suffix value to form an email|Check this box to form valid email options for users that do not have an email address. **Users without real or formed email addresses will be skipped by Directory Connector.**<br><br>Formed Email = **Email Prefix Attribute** + **Email Suffix**|
|Email Prefix Attribute|Attribute used to create a prefix for formed email addresses.|
|Email Suffix|A string (`@example.com`) used to create a suffix for formed email addresses.|
|Sync users|Check this box to sync users to your Organization.<br><br>Checking this box will allow you to specify a **User Filter**, **User Path**, **User Object Class**, and **User Email Attribute**.|
|User Filter|See [Specify Sync Filters](#specify-sync-filters).|
|User Path|Attribute used with the specified **Root Path** to search for users (e.g. `ou=users`). If no value is supplied, the subtree search will start from the root path.|
|User Object Class|Name of the class used for the LDAP user object (e.g. `user`).|
|User Email Attribute|Attribute to be used to load a user's stored email address.|
|Sync groups|Check this box to sync groups to your Organization.<br><br>Checking this box will allow you to specify a **Group Filter**, **Group Path**, **Group Object Class**, **Group Name Attribute**.|
|Group Filter|See [Specify Sync Filters](#specify-sync-filters).|
|Group Path|Attribute used with the specified **Root Path** to search for groups (e.g. `ou=groups`). If no value is supplied, the subtree search will start from the root path.|
|Group Object Class|Name of the class used for the LDAP group object (e.g. `groupOfUniqueNames`).|
|Group Name Attribute|Name of the attribute used by the directory to define the name of a group (e.g. `name`).|
{% endtable %}
### Specify Sync Filters
User and group filters can be in the form of any LDAP-compatible search filter.
Active Directory provides some advanced options and limitations for writing search filters, when compared to standard LDAP directions. Learn more about writing Active Directory search filters [here](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax?redirectedfrom=MSDN).
#### Samples
To filter a sync for all entries that have `objectClass=user` and `cn` (common name) that contains `Marketing`:
```
(&(objectClass-user)(cn=*Marketing*))
```
(**LDAP-only**) To filter a sync for all entries with an `ou` (organization unit) component of their `dn` (distinguished name) that is either `Miami` or `Orlando`:
```
(|(ou:dn:=Miami)(ou:dn:=Orlando))
```
(**LDAP-only**) To exclude entities that match an expression, for example all `ou=Chicago` entries *except* those that also match a `ou=Wrigleyville` attribute:
```
(&(ou:dn:=Chicago)(!(ou:dn:=Wrigleyville)))
```
(**AD Only**) To filter a sync for users in the `Heroes` group:
```
(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=Heroes,ou=users,dc=company,dc=com))
```
(**AD Only**) To filter a sync for users that are members of the `Heroes` group, either directory or via nesting:
```
(&(objectCategory=Person)(sAMAccountName=*)(memberOf:1.2.840.113556.1.4.1941:=cn=Heroes,ou=users,dc=company,dc=com))
```
## Test a Sync
To test whether Directory Connector will successfully connect to your Directory and return the desired users and groups, navigate to teh **Dashbaord** tab and select the **Test Now** button. If successful, users and groups will be printed to the Directory Connector window according the specified [Sync Options](#configure-sync-options) and [Filters](#specify-sync-filters):
{% image /directory-connector/okta/dc-okta-test.png Test sync results %}
## Start Automatic Sync
Once [Sync Options](#configure-sync-options) and [Filters](#specify-sync-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 Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#configure-sync-options) and [Filters](#specify-sync-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.

140
_articles/directory-connector/okta-directory.md
View File

@@ -1,41 +1,135 @@
---
layout: article
title: Configuring directory sync with Okta
title: Sync with Okta
categories: [directory-connector]
featured: true
popular: false
hidden: false
tags: []
order: 10
---
This article will cover how to connect the Bitwarden Directory Connector application to your Okta Directory.
This article will help you get starting using Directory Connector to sync users and groups from your Okta directory to your Bitwarden Organization.
## Requirements
## Create an Okta API Token
- Read through the following article: [Syncing users and groups with a directory]({% link _articles/directory-connector/directory-sync.md %})
- Install Bitwarden Directory Connector
- Using Directory Connector, log into your Bitwarden account and select your enterprise organization
Directory Connector requires knowledge of an Okta-generated token to connect to your directory. Complete the following steps to create and obtain an Okta API Token for use by Directory Connector:
## Create an API token
1. From your Okta Developer Console (`https://yourdomain-admin.okta.com`) navigate to **Security** &rarr; **API** &rarr; **Tokens**.
2. Select the **Create Token** button and give your token a Bitwarden-specific name (e.g. `bitwarden-dc`).
3. Copy the generated **Token Value** to the clipboard.
1. Log into your Okta Developer Console
2. Select **API** &rarr; **Tokens** from the navigation menu
{% image directory-connector/okta/api-tokens.png %}
3. Click the **Create Token** button and name the token something like "Bitwarden Connector", then click the **Create Token** button.
{% image directory-connector/okta/create-token.png %}
4. Note and copy your API token for use with the Directory Connector. Your token will not be shown again so you may want to save it somewhere so that you can easily access it when configuring your directory connection later.
{% image directory-connector/okta/copy-token.png %}
{% callout warning %}Your Token Value will not be shown again. Paste it somewhere safe to prevent it from being lost.{% endcallout %}
## Configure Directory Connector
## Connect to your Directory
1. Launch the Directory Connector desktop application
2. Go to the **Settings** tab.
3. Select **Okta** as the directory type.
4. Enter your Okta organization's URL (ex. https://mycompany.okta.com/).
5. Enter the API **Token** that you copied from the steps above.
Complete the following steps to configure Directory Connector to use your Okta Directory:
Congrats! You are done configuring Okta with the Bitwarden Directory Connector.
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. From the **Type** dropdown, select **Okta**.
## Testing
The available fields in this section will change according to your selected Type.
4. Enter your Okta Organization URL in the **Organization URL** field (e.g. `https://yourdomain.okta.com`).
5. Paste the API Token Value in the **Token** field.
6. In the **Account** section, select Organization to connect to your directory from the dropdown.
Test your configuration by running a sync test. You should see your Okta groups and/or users printed to the screen.
## Configure Sync Options
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
Complete the following steps to configure the settings used when syncing using Directory Connector:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. 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.|
|Sync users|Check this box to sync users to your Organization.<br><br>Checking this box will allow you to specify **User Filters**.|
|User Filter|See [Specify Sync Filters](#specify-sync-filters).|
|Sync Groups|Check this box to sync groups to your Organization.<br><br>Checking this box will allow you to specify **Group Filters**.|
|Group Filter|See [Specify Sync Filters](#specify-sync-filters).|
### Specify Sync Filters
Use comma-separated lists to include or exclude based on User Email or Group Name. Additionally, Okta APIs provided limited filtering capabilities for Users and Groups that may be used in Directory Connector Filter fields.
Consult Okta documentation for more information about using the `filter` parameter for [Users](https://developer.okta.com/docs/api/resources/users#list-users-with-a-filter){:target="\_blank"} and [Groups](https://developer.okta.com/docs/api/resources/groups#filters){:target="\_blank"}.
#### User Filters
##### Include/Exclude Users by Email
To include or exclude specific users based on email address:
```
include:joe@example.com,bill@example.com,tom@example.com
```
```
exclude:joe@example.com,bill@example.com,tom@example.com
```
##### Concatenate with `filter`
To concatenate a user filter with the `filter` parameter, use a pipe (`|`):
```
include:john@example.com,bill@example.com|profile.firstName eq "John"
```
```
exclude:john@example.com,bill@example.com|profile.firstName eq "John"
```
##### Use only `filter`
To use only the `filter` parameter, prefix the query with a pipe (`|`):
```
|profile.lastName eq "Smith"
```
#### Group Filters
##### Include/Exclude Groups
To include or exclude groups by name:
```
include:Group A,Group B
```
```
exclude:Group A,Group B
```
##### Concatenate with `filter`
To concatenate a group filter with the `filter` parameter, use a pipe (`|`):
```
include:Group A|type eq "APP_GROUP"
```
```
exclude:Group A|type eq "APP_GROUP"
```
##### Use only `filter`
To use only the `filter` parameter, prefix the query with a pipe (`|`):
```
|type eq "BUILT_IN"
```
## Test Connection
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](#configure-sync-options) and [Filters](#specify-sync-filters):
{% image /directory-connector/okta/dc-okta-test.png Test sync results%}
## Start Automatic Sync
Once [Sync Options](#configured-sync-options) and [Filters](#specify-sync-filters) are configured as desired, you can begin syncing. Complete the following steps to start automatic sync with Directory Connector:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#configured-sync-options) and [Filters](#specify-sync-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.

116
_articles/directory-connector/onelogin-directory.md
View File

@@ -1,45 +1,107 @@
---
layout: article
title: Configuring directory sync with OneLogin
title: Sync with OneLogin
categories: [directory-connector]
featured: true
popular: false
hidden: false
tags: []
order: 11
---
This article will cover how to connect the Bitwarden Directory Connector application to your OneLogin Directory.
This article will help you get started using Directory Connector to sync users and groups from your OneLogin directory to your Bitwarden Organization.
## Requirements
## Create API Credentials
- Read through the following article: [Syncing users and groups with a directory]({% link _articles/directory-connector/directory-sync.md %})
- Install Bitwarden Directory Connector
- Using the Directory Connector, log into your Bitwarden account and select your enterprise organization
Directory Connector requires knowledge of OneLogin-generated API Credentials to connect to your directory. Complete the following steps to create and obtain API credentials for use by Directory Connector:
## Creating API credentials
1. From your OneLogin Administration portal (`https://yourdomain.onelogin.com/admin`), select to **Developers** &rarr; **API Credentials** from the navigation menu.
2. Select the **New Credential** button and give your credential a Bitwarden-specific name (e.g. `bitwarden-dc`).
3. Select the **Read Users** radio button to give read permission for user fields, roles, and groups, and select **Save**.
4. Copy the generated **Client ID** and **Client Secret**. You may return to view these at any time.
1. Log into your OneLogin Adminsitration portal.
2. Select **Developers** → **API Credentials** from the navigation menu.
{% image directory-connector/onelogin/onelogin-step2.png %}
3. Click the **New Credential** button.
{% image directory-connector/onelogin/onelogin-step3.png %}
4. Name the credential something like “Bitwarden Connector”, then select "**Read users**". Save the new API credential.
{% image directory-connector/onelogin/onelogin-step4.png %}
5. Copy your **Client ID** and **Client Secret**. You can return to view these at any time.
{% image directory-connector/onelogin/onelogin-step5.png %}
## Connect to your Directory
## Configure Directory Connector
Complete the following steps to configure Directory Connector to use your OneLogin directory:
1. Launch the Directory Connector desktop application.
2. Go to the **Settings** tab.
3. Select **OneLogin** as the directory type.
4. Enter the **Client ID** and **Client Secret** copied from the previous steps.
5. Select the correct Region.
6. Configure sync options. It is recommended to use the **Overwrite existing organization users based on current sync settings** option with OneLogin.
{% callout success %}For minimal testing check "Sync users".{% endcallout %}
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. From the **Type** dropdown, select **OneLogin**.
Congrats! You are done configuring OneLogin with the Bitwarden Directory Connector.
The available fields in this section will change according to your selected Type.
4. Enter the **Client ID** and **Client Secret** [obtained from OneLogin](#create-api-credentials).
5. From the **Region** dropdown, select your region.
6. In the **Account** section, select Organization to connect to your directory from the dropdown.
## Testing
## Configure Sync Options
Test your configuration by running a sync test from the **Dashboard** of the Directory Connector. You should see your OneLogin groups and/or users printed to the screen.
{% callout success %}
When you're 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]({% link _articles/directory-connector/clear-sync-cache.md %}).
{% endcallout %}
Complete the following steps to configure the settings used when syncing using Directory Connector:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
2. Navigate to the **Settings** tab.
3. 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.<br><br>**Recommended for OneLogin directories.**|
|If a user has no email address, combine a username prefix with a suffix value to form an email|Check this box to form valid email options for users that do not have an email address. **Users without real or formed email addresses will be skipped by Directory Connector.**<br><br>Formed Email = `username` + **Email Suffix**|
|Email Suffix|A string (`@example.com`) used to create a suffix for formed email addresses.|
|Sync users|Check this box to sync users to your Organization.<br><br>Checking this box will allow you to specify **User Filters**.|
|User Filter|See [Specify Sync Filters](#specify-sync-filters).|
|Sync Groups|Check this box to sync groups to your Organization. Checking this box will allow you to specify **Group Filters**.<br><br>**Please be aware, Directory Connector uses OneLogin `role` values to create Bitwarden groups.**<br>|
|Group Filter|See [Specify Sync Filters](#specify-sync-filters).|
### Specify Sync Filters
Use comma-separated lists to include or exclude from a sync based on User Email or Group:
{% callout note %}
Directory Connector will create Bitwarden groups based on OneLogin Roles, not OneLogin Groups.
{% endcallout %}
#### User Filters
To include or exclude specific users from a sync based on email address:
```
include:joe@example.com,bill@example.com,tom@example.com
```
```
exclude:joe@example.com,bill@example.com,tom@example.com
```
#### Group Filters
To include or exclude groups from a sync based on OneLogin roles:
```
include:Role A,Role B
```
```
exclude:Role A,Role B
```
## Test a Sync
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](#configure-sync-options) and [Filters](#specify-sync-filters):
{% image /directory-connector/okta/dc-okta-test.png Test sync results %}
## Start Automatic Sync
Once [Sync Options](#configure-sync-options) and [Filters](#specify-sync-filters) are configured as desired, you can begin syncing. Complete the following steps to start automatic sync with Directory Connector:
1. Open the Directory Connector [Desktop Application]({% link _articles/directory-connector/directory-sync-desktop.md %}).
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](#configure-sync-options) and [Filters](#specify-sync-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.

195
_articles/directory-connector/user-group-filters.md
View File

@@ -1,197 +1,24 @@
---
layout: article
title: Configuring user and group sync filters
title: Sync Options and Filters
categories: [directory-connector]
featured: false
popular: false
hidden: false
tags: []
order: 05
---
You can configure the Bitwarden Directory Connector application to use filters to limit the users and/or groups that are processed for syncing to your Bitwarden organization.
When configuring the Directory Connector application, you can use a variety of Sync Options and Filters to customize your sync operation and limit the users and/or groups that are processed to your Bitwarden Organization.
The syntax for filtering is different for each directory server type and is covered in detail below.
Available Sync Options and Filter syntaxes are different for each directory server type. Refer to the **Configure Sync Options** and **Specify Sync Filters** sections of one of the following articles for help:
## Active Directory and Other LDAP Directories
- [Sync with Active Directory or LDAP]({% link _articles/directory-connector/ldap-directory.md %})
- [Sync with Azure Active Directory]({% link _articles/directory-connector/azure-active-directory.md %})
- [Sync with G Suite (Google)]({% link _articles/directory-connector/gsuite-directory.md %})
- [Sync with Okta]({% link _articles/directory-connector/okta-directory.md %})
- [Sync with OneLogin]({% link _articles/directory-connector/onelogin-directory.md %})
The group and user filters can be in the form of any LDAP compatible search filter. Additionally, Active Directory provides a few more advanced options as well as a few limitations when writing search filters as opposed to other more standard LDAP directories. You can read more about writing LDAP search filters here: <https://msdn.microsoft.com/en-us/library/windows/desktop/aa746475(v=vs.85).aspx>
### Examples
Search for all entries that have objectClass=user AND cn that contains the word 'Marketing'.
```
(&(objectClass=user)(cn=*Marketing*))
```
{% callout info %}
Active Directory does not implement extensible matching, the following examples won't work with it.
{% callout success%}
If you're using the Directory Connector CLI, see [Directory Connector File Storage]({% link _articles/directory-connector/directory-sync-shared.md %}) for help editing your `data.json` configuration file.
{% endcallout %}
Find entries with an OU component of their DN which is either 'Miami' or 'Orlando'.
```
(|(ou:dn:=Miami)(ou:dn:=Orlando))
```
To exclude entities which match an expression, use '!'. Find all Chicago entries except those with a Wrigleyville OU component.
```
(&(ou:dn:=Chicago)(!(ou:dn:=Wrigleyville)))
```
{% callout info %}
The following examples are written for Active Directory. In order to use them for something such as OpenLDAP the attributes will need to be changed.
{% endcallout %}
Users in the 'Heroes' group
```
(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=Heroes,ou=users,dc=company,dc=com))
```
Users that are a member of the 'Heroes' group, either directly or via nesting
```
(&(objectCategory=Person)(sAMAccountName=*)(memberOf:1.2.840.113556.1.4.1941:=cn=Heroes,ou=users,dc=company,dc=com))
```
## Azure Active Directory
The Microsoft Graph API does not provide a way to filter groups and users directly, however, you can use our custom filtering syntax that allows you to exclude or include a comma separated list of group names, user emails, or users based on their group membership.
### Examples
#### Groups
{% callout info %}
If you are filtering groups your user filter will only apply to users from the groups returned.
{% endcallout %}
```
include:Group A,Sales People,My Other Group
```
```
exclude:Group C,Developers,Some Other Group
```
#### Users
You can include/exclude users directly by using `include` or `exclude` keywords like below:
```
include:joe@example.com,bill@example.com,tom@example.com
```
```
exclude:joe@example.com
```
Alternatively, you can filter users based on their Azure AD group membership by using `includeGroup` or `excludeGroup` keywords. You must obtain the Azure AD group ID and include it with the keyword. You can get the group's ID in the [Azure Portal](https://portal.azure.com) or through [Azure AD PowerShell](https://docs.microsoft.com/en-us/powershell/module/azuread/get-azureadgroup?view=azureadps-2.0).
```
includeGroup:97b9ff2a-7d4f-463d-a925-efb1677fd40d,b389c339-8c13-4c1a-8ac1-4fde56d9f70f
```
```
excludeGroup:97b9ff2a-7d4f-463d-a925-efb1677fd40d
```
## G Suite
### Groups
The G Suite APIs do not provide a way to filter groups directly, however, you can use our custom filtering syntax that allows you to exclude or include a comma separated list of group names.
{% callout info %}
If you are filtering groups your user filter will only apply to users from the groups returned.
{% endcallout %}
#### Examples
```
include:Group A,Sales People,My Other Group
```
```
exclude:Group C,Developers,Some Other Group
```
### Users
We provide the same custom filtering syntax that allows you to exclude or include a comma separated list of user emails.
Additionally, the G Suite APIs provide limited filtering capabilities for users that are exposed to you. Read more about filtering with the `query` parameter here: <https://developers.google.com/admin-sdk/directory/v1/guides/search-users>
You can combine both of these filtering options by concatenating the two strings with a pipe (`|`);
#### Examples
Only the include/exclude filter:
```
include:joe@example.com,bill@example.com,tom@example.com
```
An include/exclude filter + a G Suite `query` search:
```
exclude:john@example.com,bill@example.com|orgName=Engineering orgTitle:Manager
```
Only the G Suite `query` search (notice the `|` prefix that is required):
```
|orgName=Engineering orgTitle:Manager
```
## Okta
We provide a custom filtering syntax that allows you to exclude or include a comma separated list of group names or user emails.
Additionally, the Okta APIs provide limited filtering capabilities for users and groups. Read more about filtering with the `filter` parameter here: <https://developer.okta.com/docs/api/resources/groups#filters> and <https://developer.okta.com/docs/api/resources/users#list-users-with-a-filter>
You can combine both of these filtering options by concatenating the two strings with a pipe (`|`);
### Examples
#### Groups
Only the include/exclude filter:
```
include:Group A,Group B
```
An include/exclude filter + an Okta `filter`:
```
exclude:Group A|type eq "APP_GROUP"
```
Only the Okta `filter` search (notice the `|` prefix that is required):
```
|type eq "BUILT_IN"
```
#### Users
Only the include/exclude filter:
```
include:joe@example.com,bill@example.com,tom@example.com
```
An include/exclude filter + an Okta `filter`:
```
exclude:john@example.com,bill@example.com|profile.firstName eq "John"
```
Only the Okta `filter` search (notice the `|` prefix that is required):
```
|profile.lastName eq "Smith"
```

71
files/data.json Normal file
View File

@@ -0,0 +1,71 @@
{
"installedVersion": "2.8.2",
"mainWindowSize": {
"width": 738,
"height": 551,
"isMaximized": false,
"displayBounds": {
"x": 1440,
"y": 0,
"width": 1920,
"height": 1080
},
"x": 2601,
"y": 23
},
"appId": "app-id-string",
"rememberEmail": true,
"rememberedEmail": "owner@bitwarden.com",
"directoryType": 0, <---Indicates which directoryConfig_x to use for sync
"directoryConfig_0": { <---Config for LDAP/AD
"ssl": false,
"startTls": false,
"sslAllowUnauthorized": false,
"port": 389,
"currentUser": false,
"ad": true,
"pagedSearch": true,
"password": "[STORED SECURELY]", <---Must be set from a BWDC Application
"rootPath": "dc=ldap,dc=company,dc=org",
"hostname": "ldap.company.org",
"username": "cn=bitwarden,cn=Users,dc=ldap,dc=company,dc=org"
},
"directoryConfig_2": {
"privateKey": null
},
"directoryConfig_1": { <---Config for Azure AD
"key": "[STORED SECURELY]", <---Must be set from a BWDC Application
"tenant": "bwdc@test.onmicrosoft.com",
"applicationId": "application-id-string"
},
"directoryConfig_3": { <---Config for Okta
"token": "[STORED SECURELY]", <---Must be set from a BWDC Application
"orgUrl": "https://bitwardentest.okta.com"
},
"directoryConfig_4": { <---Config for OneLogin
"region": "us",
"clientSecret": "[STORED SECURELY]", <---Must be set from a BWDC Application
"clientId": "client-id-string"
},
"syncConfig": { <---Sync Options
"users": true,
"groups": false,
"interval": 5,
"removeDisabled": false,
"overwriteExisting": false,
"useEmailPrefixSuffix": false,
"creationDateAttribute": "whenCreated",
"revisionDateAttribute": "whenChanged",
"emailPrefixAttribute": "sAMAccountName",
"memberAttribute": "member",
"userObjectClass": "person",
"groupObjectClass": "group",
"userEmailAttribute": "mail",
"groupNameAttribute": "name",
"groupPath": "",
"userPath": "",
"groupFilter": "",
"userFilter": "(ou=Test OU)"
},
"organizationId": "organization-id-string" <---Your Organization ID
}

BIN
images/directory-connector/dc-diagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 69 KiB

BIN
images/directory-connector/okta/dc-okta-copy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
images/directory-connector/okta/dc-okta-test.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
images/directory-connector/okta/dc-okta.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

BIN
images/directory-connector/onelogin/onelogin-api.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB