Configure Clients Centrally
When operating a self-hosted Bitwarden server in a business setting, administrators may want to centrally configure client application settings (particularly, Server URL) before deploying to users with an endpoint management platform. Settings are applied upon installation of the client application.
The process for doing so will be different for each client application:
To pre-configure environment URLs for Linux:
Create one of the following directory structures if they do not already exist on your system:
For Chrome,
/etc/opt/chrome/policies/managed/
For Chromium,
/etc/opt/chromium/policies/managed/
In the
managed
folder, create abitwarden.json
file with the following contents:{ "3rdparty": { "extensions": { "nngceckbapebfimnlniiiahkandclblb": { "environment": { "base": "https://my.bitwarden.server.com" } } } } }
Text Copied!The extension ID (
nngceckbapebfimnlniiiahkandclblb
) will vary depending on your installation method. You can find your extension ID by navigating to your browser's extension menu (for example,chrome://extensions
).
Most installations will only require the"base":
URL, however some unique setups may require you to enter URLs for each service independently:{ "3rdparty": { "extensions": { "nngceckbapebfimnlniiiahkandclblb": { "environment": { "base": "https://my.bitwarden.server.com", "webVault": "https://my.bitwarden.server.com", "api": "https://my.bitwarden.server.com", "identity": "https://my.bitwarden.server.com", "icons": "https://my.bitwarden.server.com", "notifications": "https://my.bitwarden.server.com", "events": "https://my.bitwarden.server.com" } } } } }
Text Copied!note
If you'll be using the Chrome or Chromium Web Store version of Bitwarden, you can follow these instructions to force install Bitwarden on end-user machines when you distribute managed policies. You can skip overlapping steps, like creating required directories.
As you will need to deploy these files to users' machines, we recommend making sure only admins can write files in the
/policies
directory.Using your preferred software distribution or MDM tool, deploy the following to users' machines:
The Chrome or Chromium-based browser
/etc/opt/{chrome or chromium}/policies/managed/bitwarden.json
tip
For more help, refer to Google's Chrome Browser Quick Start for Linux guide.
To pre-configure environment URLs for Windows:
Open the Windows Group Policy Manager and create a new Group Policy Object (GPO) or use an existing GPO scoped for your end-users.
Edit the GPO and navigate to User Configuration -> Preferences -> Windows Settings -> Registry.
Right-click Registry in the file tree and select New > Registry Item.
Create a new Registry Item with the following properties:
Action: Update
Hive:
HKEY_LOCAL_MACHINE
Key Path:
HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\<extension_id>\policy\environment
The<extension_id>
will vary depending on your installation method. You can find your extension ID by navigating to your browser's extension menu (for example,chrome://extensions
).Value name:
base
Value type:
REG_SZ
Value data: Your server's configured domain
Select OK once the item is configured.
Most installations will only require thebase
URL, however some unique setups may require you to enter URLs for each service independently. If your setup requires this, repeat Step 4 to create a new Registry Item for each of the following:Value name:
webVault
Value name:
api
Value name:
identity
Value name:
icons
Value name:
notifications
Value name:
events
note
You can also use a GPO to force-install the browser extension. Learn more.
To pre-configure environment URLs for macOS:
Create a new file
com.google.chrome.extensions.<extension_id>.plist
.
The<extension_id>
will vary depending on your installation method. You can find your extension ID by navigating to your browser's extension menu (for example,chrome://extensions
).In the created
.plist
file, add the following contents:<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>environment</key> <dict> <key>base</key> <string>https://my.bitwarden.server.com</string> </dict> </dict> </plist>
Text Copied!Most installations will only require the
base
<key>
and<string>
pair, however some unique setups may require you to enter URLs for each service independently:<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>environment</key> <dict> <key>base</key> <string>https://my.bitwarden.server.com</string> <key>webVault</key> <string>https://my.bitwarden.server.com</string> <key>api</key> <string>https://my.bitwarden.server.com></string> <key>identity</key> <string>https://my.bitwarden.server.com</string> <key>icons</key> <string>https://my.bitwarden.server.com</string> <key>notifications</key> <string>https://my.bitwarden.server.com</string> <key>events</key> <string>https://my.bitwarden.server.com</string> </dict> </dict> </plist>
Text Copied!Convert the
.plist
file to a.mobileconfig
configuration profile.note
If you'll be using the Chrome or Chromium Web Store version of Bitwarden, you can follow these instructions to force install Bitwarden on end-user machines by creating another configuration profile that can be distributed in the next step.
Using your preferred software distribution or MDM tool, install the following on users' machines:
The Chrome or Chromium-based browser
The
.mobileconfig
configuration profile
To pre-configure environment URLs for Linux:
Create a directory
/etc/firefox/policies
:mkdir -p /etc/firefox/policies
Text Copied!As you will need to deploy this directory and the files in it to users' machines, we recommend making sure old admins can write files in the
/policies
directory:chmod -R 755 /etc/firefox/policies
Text Copied!Create a
policies.json
file in/etc/firefox/policies
and add the following contents:{ "policies": { "3rdparty": { "Extensions": { "{446900e4-71c2-419f-a6a7-df9c091e268b}": { "environment": { "base": "https://my.bitwarden.server.com" } } } } } }
Text Copied!Most installations will only require the
"base":
URL, however some unique setups may require you to enter URLs for each service independently:{ "policies": { "3rdparty": { "Extensions": { "{446900e4-71c2-419f-a6a7-df9c091e268b}": { "environment": { "base": "https://my.bitwarden.server.com", "webVault": "https://my.bitwarden.server.com", "api": "https://my.bitwarden.server.com", "identity": "https://my.bitwarden.server.com", "icons": "https://my.bitwarden.server.com", "notifications": "https://my.bitwarden.server.com", "events": "https://my.bitwarden.server.com" } } } } } }
Text Copied!Using your preferred software distribution or MDM tool, deploy
/etc/firefox/policies/policies.json
to users' machines.
To pre-configure environment URLs for Windows:
Open the Windows Group Policy Manager and create a new Group Policy Object (GPO) or use an existing GPO scoped for your end-users.
Edit the GPO and navigate to User Configuration > Preferences > Windows Settings > Registry.
Right-click Registry in the file tree and select New > Registry Item.
Create a new Registry item with the following properties:
Action: Update
Hive:
HKEY_LOCAL_MACHINE
Key Path:
HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\{446900e4-71c2-419f-a6a7-df9c091e268b}\environment
Value name:
base
Value type:
REG_SZ
Value data: Your server's configured domain
Select OK once the item is configured.
Most installations will only require the base URL, however some unique setups may require you to enter URLs for each service independently. If you setup requires this, repeat Step 4 to create a new Registry item for each of the following:Value name:
webVault
Value name:
api
Value name:
identity
Value name:
icons
Value name:
notifications
Value name:
events
To pre-configure environment URLs for macOS:
Remove the quarantining attribute automatically applied to Firefox by running the following command:
xattr -r -d com.apple.quarantine /Applications/Firefox.app
Text Copied!Create a directory
/Applications/Firefox.app/Contents/Resources/distribution
.Create a file
policies.json
in thedistribution
folder and add the following contents:{ "policies": { "3rdparty": { "Extensions": { "{446900e4-71c2-419f-a6a7-df9c091e268b}": { "environment": { "base": "https://my.bitwarden.server.com" } } } } } }
Text Copied!Most installations will only require the
"base":
URL, however some unique setups may require you to enter URLs for each service independently:{ "policies": { "3rdparty": { "Extensions": { "{446900e4-71c2-419f-a6a7-df9c091e268b}": { "environment": { "base": "https://my.bitwarden.server.com", "webVault": "https://my.bitwarden.server.com", "api": "https://my.bitwarden.server.com", "identity": "https://my.bitwarden.server.com", "icons": "https://my.bitwarden.server.com", "notifications": "https://my.bitwarden.server.com", "events": "https://my.bitwarden.server.com" } } } } } }
Text Copied!Using your preferred software distribution or MDM tool, deploy
/etc/firefox/policies/policies.json
to users' machines.
To centrally configure the Desktop app for deployment, first complete the following steps on a single workstation:
Install the Desktop app. If you're using Windows, silently install Bitwarden as an administrator using
installer.exe /allusers /S
(see NSIS documentation).Navigate to the Desktop app's locally stored settings. This directory is different depending on your OS (e.g.
%AppData%\Bitwarden
on Windows,~/Library/Application Support/Bitwarden
on macOS). Find your directory.In the directory, open the
data.json
file.Edit
data.json
to configure the Desktop app as desired. In particular, create the following object to configure the app with your self-hosted Server URL:} "environmentUrls": { "base": "https://my.bitwarden.server.com", "api": null, "identity": null, "webVault": null, "icons": null, "notifications": null, "events": null, "enterprise": null } }
Text Copied!Once configured the way you want it, use your endpoint management solution of choice (like Jamf) to deploy the pre-configured Desktop app as a template.
Most Mobile Device Management (MDM) or Enterprise Mobility Management (EMM) solutions allow administrators to pre-configure applications before deployment in a standard fashion. To pre-configure Bitwarden Mobile apps to use your self-hosted Server URL, construct the following Application Configuration:
Configuration Key | Value Type | Configuration Value |
---|---|---|
| string | Your self-hosted Server URL, for example |