= KeePassXC – Browser Plugin
include::.sharedheader[]
:imagesdir: ../images

// tag::content[]
== Browser Integration
The KeePassXC-Browser extension is installed within your web browser so that you can automatically pull usernames and passwords from KeePassXC and fill 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

NOTE: On Linux, Flatpak and Snap based browsers are generally not supported. Ubuntu's Firefox Snap is currently the only known exception. 

=== 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 fill 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 Integration Report
You can see a cross-section of all browser-related settings applied to entries within a database through the Browser Statistics report. To access, 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.

TIP: You can delete remembered site settings from the report by right clicking the entry you want to reset and selecting "Delete plugin data from entry".

.Browser Integration Report
image::browser_statistics.png[]

=== Additional Fill-In Fields
Sometimes login pages have additional fields you would like to fill (e.g., account number). Use the following instructions to add them:

1. Edit the entry you want to add fields to. Go to the advanced tab and add the attributes you need. Each attribute *must start with* `KPH:` followed by a space, but otherwise the name does not matter. If multiple KPH attributes are defined, they are used in alphabetical order (i.e., the order shown in KeePassXC).
2. Within the browser, navigate to the page you want to use the additional fields on. Select the "Choose Custom Login Fields" button from the extension popup window. Choose Username, Password and String Field(s). Confirm the selections.
3. Refresh the web page. The new KPH attribute(s) should be filled to the extra fields.

.String Fields Selection in Browser
image:browser_integration_additional_attribute.png[]

=== Clearing Remembered Sites
Entries that you have chosen to remember allow/deny rules are stored in their respect custom data fields. You can clear all of these remembered settings at once through the database settings. Follow these steps:

1. Go to *Database* → *Database Settings* or click the database settings icon in the toolbar.
2. Go to the *Browser Integration* tab, then click on the *Forget all site-specific settings on entries* button. 
3. Confirm this action in the popup dialog. This cannot be undone once the database is saved. 
+
.Clear Remembered Sites
image::browser_integration_clear_sites.png[,100%]

=== 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)*.

Additional URLs also supports wildcards (with KeePassXC 2.7.10 and later). You can use URLs like:
----
https://*.example.com
https://example.com/*/path
https://sub.*.example.com/path/*
----

.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 (see https://learn.microsoft.com/en-us/deployedge/microsoft-edge-policies#native-messaging[Microsoft Edge Native Messaging Policies] for more information.):
+
----
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"
----

==== Managed Microsoft Edge on macOS
1. Deploy *org.keepassxc.keepassxc_browser_edge.json* to `/Library/Microsoft/Edge/NativeMessagingHosts`.

2. You may need to configure Edge to allowlist the extension and native messaging host. See https://learn.microsoft.com/en-us/deployedge/microsoft-edge-policies#native-messaging[Microsoft Edge Native Messaging Policies] for more information.
// end::advanced[]
// end::content[]
