mirror of
https://github.com/keepassxreboot/keepassxc.git
synced 2024-10-01 01:26:01 -04:00
191 lines
10 KiB
Plaintext
191 lines
10 KiB
Plaintext
= KeePassXC – Browser Plugin
|
||
include::.sharedheader[]
|
||
:imagesdir: ../images
|
||
|
||
// tag::content[]
|
||
== Setup Browser Integration
|
||
The KeePassXC-Browser extension is installed within your web browser so that you can automatically pull usernames and passwords from KeePassXC and populate them directly into website fields. It is a very useful and secure extension that enhances your productivity while using KeePassXC. With this extension, you do not need to manually copy the data from your KeePassXC database and paste it into the website fields.
|
||
|
||
The KeePassXC-Browser extension is available on the following web browsers:
|
||
|
||
* Google Chrome, Vivaldi, and Brave
|
||
* Mozilla Firefox and Tor-Browser
|
||
* Microsoft Edge
|
||
* Chromium
|
||
|
||
=== Install the Browser Extension
|
||
You can download the KeePassXC-Browser extension from your web browser. To download the KeePassXC-Browser extension, perform the following steps:
|
||
|
||
1. Click the link corresponding to your browser:
|
||
* https://chromewebstore.google.com/detail/keepassxc-browser/oboonakemofpalcgghocfoadofidjkkk[Chrome, Chromium, Vivaldi, and Brave]
|
||
* https://addons.mozilla.org/en-US/firefox/addon/keepassxc-browser[Mozilla Firefox and Tor-Browser]
|
||
* https://microsoftedge.microsoft.com/addons/detail/keepassxcbrowser/pdffhmdngciaglkoonimfcmckehcpafo[Microsoft Edge]
|
||
|
||
2. Click the button to install/add the extension to the browser. Accept any confirmation dialogs.
|
||
|
||
TIP: For the most up-to-date troubleshooting advice on all platforms, please read our https://github.com/keepassxreboot/keepassxc-browser/wiki/Troubleshooting-guide[Troubleshooting Guide].
|
||
|
||
// tag::advanced[]
|
||
NOTE: When Microsoft Edge is installed as a managed application, system administrators are required to deploy a custom native messaging configuration. Instructions for this are found in the advanced section below.
|
||
// end::advanced[]
|
||
|
||
=== Configure KeePassXC-Browser
|
||
To start using KeePassXC-Browser, you must configure it so that it can communicate with the KeePassXC application on your desktop.
|
||
|
||
To configure KeePassXC-Browser, perform the following steps:
|
||
|
||
1. Open the KeePassXC application on your desktop and navigate to Tools > Settings.
|
||
|
||
2. Click the Browser Integration option on the left-hand side *(1)*. The following screen appears:
|
||
+
|
||
.Browser Settings
|
||
image::browser_settings.png[]
|
||
|
||
3. Click the _Enable browser integration_ checkbox *(2)*. Then select the browsers for which you have downloaded the KeePassXC-Browser extension *(3)* and click *OK*.
|
||
|
||
4. Ensure your database is unlocked, then open (or restart) your browser.
|
||
|
||
5. Click the KeePassXC-Browser extension icon *(A)* in your browser (see figure below). A pop-up window appears.
|
||
+
|
||
.Connect Extension to KeePassXC
|
||
image::browser_extension_connect.png[,80%]
|
||
|
||
6. Click the _Connect_ button *(B)* in the pop-up window to complete integrating the KeePassXC-Browser extension with your KeePassXC desktop application.
|
||
|
||
7. You are now prompted to enter a unique name to identify the connection between this browser and your database. Enter a unique name in the field (e.g., firefox-laptop) and click the _Save and allow access_ button.
|
||
+
|
||
.Extension Association Dialog
|
||
image::browser_extension_association.png[,80%]
|
||
|
||
WARNING: If you reuse a connection name in a database, the previous browser connection will be overwritten and prevent access.
|
||
|
||
=== Using the Browser Extension
|
||
The KeePassXC-Browser extension lets you automatically populate the entries from your KeePassXC database into the fields on websites you visit. To do so, perform the following steps:
|
||
|
||
1. Open your KeePassXC desktop application and unlock your database.
|
||
|
||
2. Open your web browser. The KeePassXC-Browser extension icon in your browser window will change based on its connection state. The figure below shows the different states.
|
||
+
|
||
*(A)* KeePassXC is not running or is disconnected. +
|
||
*(B)* KeePassXC is running, but KeePassXC Browser Extension is not connected to the current database. +
|
||
*\(C)* Connected to KeePassXC, but database is locked. +
|
||
*(D)* Connected to KeePassXC and ready to use. If the icon is shown with a number, it indicates the number of credentials found for the current site.
|
||
+
|
||
.Extension Icon States
|
||
image::browser_extension_icons.png[,70%]
|
||
|
||
3. If the KeePassXC desktop application is not connected with the KeePassXC-Browser extension, click the extension icon in your web browser and click _Reload_ from the pop-up window as shown in the following screen.
|
||
+
|
||
.Reload Extension Connection
|
||
image::browser_extension_reload.png[,80%]
|
||
|
||
4. Open the URL for which you want to use with your database. If you have previously created an entry in your database then the KeePassXC-Browser Confirm Access dialog may appear:
|
||
+
|
||
.Confirm Access Dialog
|
||
image::browser_confirm_access_dialog.png[,80%]
|
||
|
||
5. Ensure the credentials you want to use are checked, then click *(A)* Remember _(optional)_, then click _Allow Selected_ *(B)*.
|
||
|
||
6. In your website, the KeePassXC icon will appear in the username field of the login form *(A)*. Click the icon to populate the field with your stored credentials. If you have more than one credential for this website, a dropdown will appear to choose the one to use.
|
||
+
|
||
.Fill Credentials
|
||
image::browser_fill_credentials.png[,80%]
|
||
|
||
=== Generate Passwords
|
||
|
||
The KeePassXC-Browser Extension also lets you generate passwords directly in your browser.
|
||
This feature can be used for websites with existing credentials as well as for new websites.
|
||
You can then choose to update/add the credentials to your KeePassXC database directly from the Browser.
|
||
|
||
1. Ensure your database is unlocked and configured to use the Browser extension as shown above.
|
||
|
||
2. Right click on a password field and from the KeePassXC sub-menu choose _Show Password Generator_. The standard KeePassXC password generator will appear.
|
||
|
||
3. Configure the password generation options and click _Apply Password_ when done. The generated password will be filled into the previously selected field.
|
||
|
||
4. When you have successfully submitted the password on the website, a popup will appear asking you to either update an existing entry or add a new one.
|
||
|
||
// tag::advanced[]
|
||
=== Browser statistics
|
||
You can see a cross-section of all browser-related settings applied to entries within a database through the Browser Statistics report. To access these, use the _Database_ -> _Database reports..._ menu option then click on _Browser Statistics_ on the left-hand menu. From here you can see all entries with URLs applied to them, explicitly allowed and denied URLs, and any entries with custom browser settings.
|
||
|
||
.Browser statistics
|
||
image::browser_statistics.png[]
|
||
|
||
=== Advanced Usage
|
||
You can configure unique browser integration behavior for each entry. This allows you to add multiple URLs to an entry, hide an entry from the browser integration, and more. To access these settings, open an entry for editing then click on _Browser Integration_ option in the left-hand menu *(1)*.
|
||
|
||
After opening the settings you can add any number of additional URLs by clicking the _Add_ button *(2)* and typing the URL in the list to the left *(3)*.
|
||
|
||
.Entry browser settings
|
||
image::browser_entry_settings.png[]
|
||
|
||
To set options for all entries within a group, edit the group and go to the browser integration section *(1)*. Here you can explicitly disable access to all entries under a group hierarchy to the browser extension. You can set other useful options for groups of entries as well.
|
||
|
||
.Group browser settings
|
||
image::browser_group_settings.png[]
|
||
|
||
Database-wide operations are available in the database settings. To access these use the _Database_ -> _Database settings..._ menu option. Click on _Browser Integration_ on the left-hand menu. From here you can disconnect all browsers, convert legacy KeePass-HTTP settings, reset all entry-level settings, and refresh the database root group ID (useful when making copies of your database file).
|
||
|
||
.Database browser settings
|
||
image::browser_database_settings.png[]
|
||
|
||
Finally, advanced application-wide settings are available in the Browser Integration tab of the application settings.
|
||
|
||
WARNING: We do not recommend changing any of these settings as they may break the browser integration plugin.
|
||
|
||
.Advanced browser settings
|
||
image::browser_advanced_settings.png[]
|
||
|
||
=== Advanced Setup
|
||
|
||
==== Custom Browser option
|
||
|
||
It is possible to enable support for a custom browser (e.g. LibreWolf, WaterFox, Arc, beta and nightly browsers, etc.) using this feature.
|
||
This feature is only available for Linux and macOS.
|
||
|
||
.Custom browser configuration
|
||
image::browser_custom_browser_configuration.png[]
|
||
|
||
The native messaging script file needed for the custom browser depends on the browser type. For Firefox based browsers like Librefox the _Browser type_ must be _Firefox_. For Arc, Opera, etc. the type must be set to _Chromium_.
|
||
|
||
_Config location_ must have the exact path for the browser's _native-messaging-hosts_ folder. If you are unsure, refer to our https://github.com/keepassxreboot/keepassxc-browser/wiki/Troubleshooting-guide#1-after-enabling-browser-integration-and-support-for-your-browser[Troubleshooting Guide] for listing of the most common paths, and a few ways for finding a path when it's not known.
|
||
|
||
When a Custom Browser has been successfully set, KeePassXC will automatically write the needed native messaging script file to the folder.
|
||
|
||
If you wish to support multiple custom browsers, you can copy the native messaging script files manually to the _native-messaging-hosts_ folder from other browsers.
|
||
|
||
==== Managed Microsoft Edge on Windows
|
||
1. Deploy *org.keepassxc.keepassxc_browser_edge.json* to, for example, `C:\ProgramData\KeepassXC` on all managed platforms.
|
||
+
|
||
----
|
||
{
|
||
"allowed_origins": [
|
||
"chrome-extension://pdffhmdngciaglkoonimfcmckehcpafo/"
|
||
],
|
||
"description": "KeePassXC integration with native messaging support",
|
||
"name": "org.keepassxc.keepassxc_browser",
|
||
"path": "C:\\Program Files\\KeePassXC\\keepassxc-proxy.exe",
|
||
"type": "stdio"
|
||
}
|
||
----
|
||
|
||
2. Configure GPO options (registry result):
|
||
+
|
||
----
|
||
Windows Registry Editor Version 5.00
|
||
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\org.keepassxc.keepassxc_browser]
|
||
@="C:\ProgramData\KeepassXC\org.keepassxc.keepassxc_browser_edge.json"
|
||
|
||
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge]
|
||
"NativeMessagingUserLevelHosts"=dword:00000000
|
||
|
||
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallAllowlist]
|
||
"1"="pdffhmdngciaglkoonimfcmckehcpafo"
|
||
|
||
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\NativeMessagingAllowlist]
|
||
"1"="org.keepassxc.keepassxc_browser"
|
||
----
|
||
// end::advanced[]
|
||
// end::content[]
|