= KeePassXC – Secret Service Integration
include::.sharedheader[]
:imagesdir: ../images

// tag::content[]
== Secret Service Integration
This feature allows KeePassXC to act as a Secret Service provider over DBus. It enables applications to store and retrieve secrets securely via the https://www.freedesktop.org/wiki/Specifications/secret-storage-spec/[Secret Storage specification]. While running, KeePassXC acts as a Secret Service server registered on DBus so clients like seahorse, python-secretstorage, secret-tool, or other implementations can connect and access the exposed database in KeePassXC.

=== Enabling the Integration
Only one secret service provider can be enabled at a time. You may have to disable other providers, such as GNOME Keyring or KWallet, to use KeePassXC as a secret service provider. You will see a notice when attempting to enable KeePassXC as the secret service provider if another is already running.

To replace most third party secret service providers with KeePassXC, run the following shell snippet:

```bash
mkdir -p "${XDG_DATA_HOME:-${HOME}/.local/share}/dbus-1/services"
cat > "${XDG_DATA_HOME:-${HOME}/.local/share}/dbus-1/services/org.freedesktop.secrets.service" <<EOF
[D-BUS Service]
Name=org.freedesktop.secrets
Exec=/usr/bin/keepassxc
EOF
```

NOTE: You may need to restart your session or log out and back in for the changes to take effect.

1. Open KeePassXC → **Tools → Settings → Secret Service Integration** → check **Enable KeePassXC Freedesktop.org Secret Service Integration**. Then press OK to save this setting and enable the integration. Go back into this settings screen to see currently open databases that you can unlock and edit their exposure to secret service.
+
.Secret Service Settings
image::secretservice_enable_settings.png[]

2. Either click the pencil icon in the previous settings screen, or go to **Database → Database Settings → Secret Service Integration**. Enable **Expose entries under this group**, and select the desired group. All entries within this group and all subgroups will be exposed to the service.
+
.Secret Service Database Settings
image::secretservice_database_settings.png[]

3. Use apps that integrate with secret service to start saving and using credentials within KeePassXC. If you enabled confirmation prior to access, you will see the following dialog:
+
.Secret Service Access Confirmation Dialog
image::secretservice_access_dialog.png[]

TIP: When applications use `secret-tool` and you have access confirmation enabled, then you will be prompted each time credentials are requested. This is due to `secret-tool` obtaining a new process id each time it is run.

=== Implementation Details

* The user can specify the database and group that is exposed to the service.
* Desktop notifications when a secret is retrieved and access confirmation dialogs.
* `FdoSecrets::Service` is the top level DBus service. There is one  `FdoSecrets::Collection` per opened database tab and each entry under the exposed database group has a corresponding `FdoSecrets::Item` DBus object.
* The following entry attributes are exposed to the secret service: Title, Username, Password, URL, Notes, TOTP, and non-protected Custom Attributes.
// end::content[]