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.mdpull/354/head
fred_the_tech_writer
5 years ago
committed by
GitHub
17 changed files with 1080 additions and 682 deletions
@ -1,86 +1,174 @@
@@ -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: |
||||
|
||||
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 %} |
||||
|
||||
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 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. |
||||
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 %} |
||||
|
||||
Test your configuration by running a sync test. You should see your Azure Active Directory groups and/or users printed to the screen. |
||||
{% 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. |
||||
|
||||
@ -0,0 +1,19 @@
@@ -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. |
||||
@ -0,0 +1,168 @@
@@ -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. |
||||
@ -0,0 +1,97 @@
@@ -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. |
||||
@ -0,0 +1,64 @@
@@ -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 %} |
||||
@ -1,289 +1,61 @@
@@ -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 %} |
||||
|
||||
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. |
||||
|
||||
Directory Connector supports sync from the following sources: |
||||
|
||||
- [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 %}) |
||||
|
||||
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. |
||||
## Directory Connector Applications |
||||
|
||||
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 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 %} |
||||
{% image directory-connector/app.png Directory Connector Desktop App %} |
||||
|
||||
## Download and Install |
||||
### Download Directory Connector |
||||
|
||||
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: |
||||
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). |
||||
|
||||
@ -1,92 +1,179 @@
@@ -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 & Services** → **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 & Services** → **Credentials**. |
||||
3. Select the **Create Credentials** button, and select **Service account** from the dropdown. |
||||
4. Fill in the **Service account details** section, and select the **Create** button. |
||||
5. In the **Grant this service account access to project** section, select **Project → Owner** from the **Role** dropdown and select the **Continue** button. |
||||
6. Select the **Done** button. |
||||
|
||||
### 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 & Admin** → **Service Accounts**. |
||||
3. Select the created service account. |
||||
4. On the Service Account Details page, select the **Add Key** button and select **Create new key** from the dropdown. |
||||
5. Select the Key type: **JSON** and select the **Create** button to download a JSON-formatted key to your local machine. |
||||
6. Back on the details 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** → **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 & Services** → **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 |
||||
|
||||
## Enable the Admin SDK API for Your Project |
||||
|
||||
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 & Services** → **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 %} |
||||
|
||||
## Create & Configure a Service Account |
||||
|
||||
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 & Services** → **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 %} |
||||
|
||||
## Configure G Suite Security |
||||
|
||||
1. Go to <https://admin.google.com> |
||||
2. Open the navigation menu and navigate to **Security** → **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 %} |
||||
|
||||
## Configure Directory Connector |
||||
|
||||
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. |
||||
|
||||
Congrats! You are done configuring G Suite with the Bitwarden Directory Connector. |
||||
|
||||
## Testing |
||||
|
||||
Test your configuration by running a sync test. You should see your G Suite groups and/or users printed to the screen. |
||||
Complete the following steps to configure the setting 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, confiture 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 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).| |
||||
|
||||
### Specify Sync Filters |
||||
|
||||
Use comma-separated lists to include or exclude from a sync based on User Email or Group: |
||||
|
||||
#### User Filters |
||||
|
||||
The following filtering syntaxes should be used in the **User Filter** field: |
||||
|
||||
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"}. |
||||
|
||||
##### 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:joe@example.com,bill@example,tom@example.com |
||||
``` |
||||
|
||||
##### Concatenate with `query` |
||||
|
||||
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. |
||||
|
||||
@ -1,41 +1,135 @@
@@ -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** → **API** → **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** → **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. |
||||
|
||||
@ -1,45 +1,107 @@
@@ -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** → **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. |
||||
|
||||
@ -0,0 +1,71 @@
@@ -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 |
||||
} |
||||
|
After Width: | Height: | Size: 69 KiB |
|
After Width: | Height: | Size: 32 KiB |
|
After Width: | Height: | Size: 61 KiB |
|
After Width: | Height: | Size: 67 KiB |
|
After Width: | Height: | Size: 49 KiB |
Loading…
Reference in new issue