Skip to content

Commit e66693f

Browse files
authored
secretservice: allow headless credential access (#2474)
An unlocked Secret Service collection does not require a desktop session. The DISPLAY/WAYLAND_DISPLAY check rejects legitimate SSH and terminal sessions even when their keyring is already available. Use actual bus connectivity and Secret Service initialization as the availability checks rather than treating the presence of a display as proof. Native error details and actionable guidance help users distinguish an absent service from a locked collection or a cancelled prompt. Provider-owned prompting remains unchanged. Headless users still need to provision their session bus and unlock collections through their provider; this change does not introduce terminal prompting or start D-Bus explicitly. Rendered docs: - https://github.com/mjcheetham/git-credential-manager/blob/headless-linux/docs/secretservice-headless.md
2 parents 89c821a + 0f15cc6 commit e66693f

11 files changed

Lines changed: 505 additions & 49 deletions

File tree

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ The following are links to user support documentation:
1111
- [Enterprise configuration][gcm-enterprise-config]
1212
- [Network and HTTP configuration][gcm-net-config]
1313
- [Credential stores][gcm-credstores]
14+
- [Secret Service in headless Linux sessions][gcm-secretservice-headless]
1415
- [Azure Repos OAuth tokens][gcm-azure-tokens]
1516
- [Azure Managed Identities and Service Principals][gcm-misp]
1617
- [Azure Workload Identity Federation Workflows][gcm-azure-wif]
@@ -47,6 +48,7 @@ These are links helpful for developers of Git Credential Manager:
4748
[gcm-misp]: azrepos-misp.md
4849
[gcm-net-config]: netconfig.md
4950
[gcm-oauth]: generic-oauth.md
51+
[gcm-secretservice-headless]: secretservice-headless.md
5052
[gcm-usage]: usage.md
5153
[gcm-ntlm-kerberos]: ntlm-kerberos.md
5254
[gcm-azure-wif]: azrepos-wif.md

‎docs/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -581,7 +581,7 @@ _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|-
581581
`wincredman`|Windows Credential Manager (not available over SSH).|Windows
582582
`dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath][credential-dpapistorepath]|Windows
583583
`keychain`|macOS Keychain.|macOS
584-
`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a graphical interface to unlock secret collections).|Linux
584+
`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a D-Bus session bus and a Secret Service provider; unlocking may require a graphical interface).|Linux
585585
`gpg`|Use GPG to store encrypted files that are compatible with the [pass][pass] (requires GPG and `pass` to initialize the store).|macOS, Linux
586586
`cache`|Git's built-in [credential cache][credential-cache].|macOS, Linux
587587
`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`][credential-plaintextstorepath].|Windows, macOS, Linux

‎docs/credstores.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ using the Keychain Access application.
105105

106106
**Available on:** _Linux_
107107

108-
**:warning: Requires a graphical user interface session.**
108+
**:warning: Requires a D-Bus session bus and a Secret Service provider.**
109109

110110
```shell
111111
export GCM_CREDENTIAL_STORE=secretservice
@@ -117,8 +117,26 @@ This credential store uses the `libsecret` library to interact with the Secret
117117
Service. It stores credentials securely in 'collections', which can be viewed by
118118
tools such as `secret-tool` and `seahorse`.
119119

120-
A graphical user interface is required in order to show a secure prompt to
121-
request a secret collection be unlocked.
120+
A Secret Service provider, such as GNOME Keyring or KWallet, must be available
121+
on the user's D-Bus session bus. The provider handles prompts to create or
122+
unlock collections; these prompts may require a graphical user interface.
123+
124+
### Headless/SSH sessions
125+
126+
A graphical session is not required to access an already-unlocked collection.
127+
In a headless or SSH session, ensure GCM can access the same D-Bus session bus
128+
as the Secret Service provider, and unlock the collection using a mechanism
129+
supported by that provider before running GCM.
130+
131+
See [Secret Service in headless Linux sessions][secretservice-headless] for
132+
more information, including example setup instructions for Ubuntu and the GNOME
133+
Keyring provider.
134+
135+
> [!NOTE]
136+
> GCM cannot provision a D-Bus session or replace the provider's unlock
137+
> prompts with terminal or pinentry prompts. For environments without D-Bus,
138+
> consider the [GPG/`pass` credential store](#gpgpass-compatible-files) or
139+
> [Git's in-memory credential cache](#gits-built-in-credential-cache).
122140
123141
## GPG/[`pass`][passwordstore] compatible files
124142

@@ -290,3 +308,4 @@ enter your credentials every time you interact with a remote repository.
290308
[git-credential-cache-options]: https://git-scm.com/docs/git-credential-cache#_options
291309
[passwordstore]: https://www.passwordstore.org/
292310
[plaintext-files]: #plaintext-files
311+
[secretservice-headless]: secretservice-headless.md

‎docs/environment.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -752,7 +752,7 @@ _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|-
752752
`wincredman`|Windows Credential Manager (not available over SSH).|Windows
753753
`dpapi`|DPAPI protected files. Customize the DPAPI store location with [`GCM_DPAPI_STORE_PATH`][gcm-dpapi-store-path]|Windows
754754
`keychain`|macOS Keychain.|macOS
755-
`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a graphical interface to unlock secret collections).|Linux
755+
`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a D-Bus session bus and a Secret Service provider; unlocking may require a graphical interface).|Linux
756756
`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility][passwordstore] (requires GPG and `pass` to initialize the store).|macOS, Linux
757757
`cache`|Git's built-in [credential cache][git-credential-cache].|Windows, macOS, Linux
758758
`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`GCM_PLAINTEXT_STORE_PATH`][gcm-plaintext-store-path].|Windows, macOS, Linux

‎docs/secretservice-headless.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Secret Service in headless Linux sessions
2+
3+
Git Credential Manager (GCM) can use Secret Service without a graphical
4+
desktop, provided a provider is available and the required keyrings are
5+
unlocked.
6+
7+
## How Secret Service fits together
8+
9+
Secret Service is a standard API for storing and retrieving secrets.
10+
A **provider** implements that API, stores the secrets, and controls access
11+
to them. Example providers include [GNOME Keyring][gnome-keyring],
12+
[KWallet][kwallet], and [oo7][oo7].
13+
14+
[D-Bus][dbus] carries messages between applications and the provider; it
15+
does not store the secrets itself. GCM's `secretservice` credential store
16+
uses the `libsecret` library to communicate with the provider over the user's
17+
D-Bus session bus.
18+
19+
```mermaid
20+
flowchart LR
21+
subgraph gcm["Git Credential Manager"]
22+
direction TB
23+
libsecret("libsecret")
24+
end
25+
libsecret <--> dbus[/"D-Bus<br/>session"/]
26+
apps("Other<br/>applications") <--> dbus
27+
dbus <--> provider("Secret Service<br/> provider")
28+
keyrings[("Secret<br/>Collections")] <--> provider
29+
```
30+
31+
For GCM to use this store, it needs:
32+
33+
- Access to a user/session bus.
34+
- A Secret Service provider running, or able to start on demand, on that bus.
35+
- A default collection for storing credentials, with the required collections
36+
unlocked. GNOME Keyring and oo7 call these **keyrings**; KWallet calls them
37+
**wallets**.
38+
39+
> [!NOTE]
40+
> On systems with [systemd][systemd], the user D-Bus session bus and installed
41+
> Secret Service providers are typically started automatically. Providers may be
42+
> started on demand through D-Bus activation when an application requests them.
43+
44+
## Unlocking without a desktop
45+
46+
Secret Service allows applications to request that a collection be unlocked,
47+
but the provider controls authentication and prompting. On a desktop, this
48+
often means a graphical password prompt. The standard API does not let GCM
49+
supply the collection's password or choose a terminal prompt such as pinentry.
50+
51+
In a headless session, the collection must already be unlocked, or the
52+
provider must offer a way to unlock it without a graphical prompt. Available
53+
options depend on the provider and may include command-line tools or login
54+
integration, such as PAM. Installing a terminal pinentry program alone does
55+
not make a provider's graphical prompts work headlessly.
56+
57+
**Starting the bus or provider is not the same as unlocking a collection.**
58+
An unlocked collection needs no further input. After a reboot or provider
59+
restart, it must be unlocked again, either through configured automatic
60+
unlocking or user interaction. Unattended workloads need a setup that does
61+
not depend on an interactive password prompt.
62+
63+
## Setup Guides
64+
65+
### Ubuntu Server + GNOME Keyring
66+
67+
These instructions use Ubuntu Server 24.04 to create a password-protected
68+
keyring and reuse it on future logins. Ubuntu's packages provide automatic service
69+
startup; no custom systemd configuration is needed.
70+
71+
Run these steps as the user who runs Git. Use `sudo` only where shown.
72+
73+
#### 1. Set up the keyring
74+
75+
##### Install the dependencies
76+
77+
```shell
78+
sudo apt-get update
79+
sudo apt-get install --no-install-recommends \
80+
dbus dbus-user-session gnome-keyring libsecret-tools
81+
```
82+
83+
##### Check the D-Bus session
84+
85+
```shell
86+
busctl --user list
87+
```
88+
89+
On a standard Ubuntu Server login, the user bus is already available.
90+
If the command lists services, continue in the same shell.
91+
92+
If no user bus is available, start a temporary session:
93+
94+
```shell
95+
dbus-run-session -- bash
96+
```
97+
98+
Run the remaining keyring setup commands inside this new shell.
99+
100+
##### Create an unlock command
101+
102+
Create this small helper so you do not have to repeat the password-handling
103+
commands each time. The helper **does not store your password**.
104+
105+
```shell
106+
mkdir -p "$HOME/.local/bin"
107+
cat > "$HOME/.local/bin/unlock-keyring" <<'EOF'
108+
#!/usr/bin/env bash
109+
set -euo pipefail
110+
set +x
111+
112+
if ! IFS= read -r -s -p 'Keyring password: ' password </dev/tty; then
113+
printf '\nCould not read the keyring password.\n' >&2
114+
exit 1
115+
fi
116+
printf '\n' >/dev/tty
117+
if [[ -z "$password" ]]; then
118+
printf 'Use a non-empty keyring password.\n' >&2
119+
exit 1
120+
fi
121+
122+
printf '%s' "$password" |
123+
gnome-keyring-daemon --daemonize --replace --unlock --components=secrets
124+
EOF
125+
chmod 700 "$HOME/.local/bin/unlock-keyring"
126+
```
127+
128+
Start the daemon and create or unlock the login keyring:
129+
130+
```shell
131+
~/.local/bin/unlock-keyring
132+
```
133+
134+
On first use, choose a non-empty keyring password. On later uses, enter
135+
that same password. This is the **keyring password**, not a Git access token.
136+
The encrypted keyring is saved in your home directory.
137+
138+
The command replaces any GNOME Keyring daemon it discovers, so it may
139+
interrupt other applications using that daemon.
140+
141+
##### Select the credential store
142+
143+
```shell
144+
git config --global credential.credentialStore secretservice
145+
```
146+
147+
GCM can now use the keyring. To check that it is unlocked:
148+
149+
```shell
150+
busctl --user get-property org.freedesktop.secrets \
151+
/org/freedesktop/secrets/collection/login \
152+
org.freedesktop.Secret.Collection Locked
153+
```
154+
155+
The expected output is `b false`.
156+
157+
#### 2. Use the keyring on future logins
158+
159+
On a standard Ubuntu Server login, the user bus starts automatically.
160+
Installing GNOME Keyring also installs its D-Bus activation configuration:
161+
the bus can start the provider when an application requests it.
162+
163+
You can see this with:
164+
165+
```shell
166+
busctl --user list | grep org.freedesktop.secrets
167+
```
168+
169+
An `(activatable)` entry means the provider can start on demand. A PID means
170+
it is already running. You do not need to enable additional systemd units
171+
or change `.bashrc` for this setup.
172+
173+
After a reboot, or whenever the keyring is locked, unlock it before using GCM:
174+
175+
```shell
176+
~/.local/bin/unlock-keyring
177+
```
178+
179+
Use the password you chose in part 1, then use Git normally. If the collection
180+
is already unlocked, no unlock command is needed.
181+
182+
If you used a temporary `dbus-run-session` shell, its bus ends when you leave
183+
that shell. Start another session as described in part 1 when needed.
184+
185+
## Troubleshooting
186+
187+
Read the complete error, including any native error printed after GCM's
188+
message. For example, `Failed to open the Secret Service session` can mean
189+
a collection could not be loaded, not just that the provider is missing.
190+
191+
Symptom|What to check
192+
-|-
193+
`No credential store has been selected`|Select the store with `git config --global credential.credentialStore secretservice`.
194+
`Failed to connect to the D-Bus session bus` or `Cannot autolaunch D-Bus without X11 $DISPLAY`|Run `busctl --user list` as the user who runs Git, without `sudo`. If no user bus is available, follow the [D-Bus session setup](#check-the-d-bus-session).
195+
`ServiceUnknown` or `NameHasNoOwner`|A required D-Bus service is unavailable. Check whether `org.freedesktop.secrets` is running or activatable in `busctl --user list`. If it is, the error may refer to another component, such as the provider's prompter; check the service named in the error.
196+
`No such secret collection at path: ...` or `Object does not exist` for a collection path|The collection may be missing or the provider's state may be inconsistent. Check the default collection as described below.
197+
`Cannot get secret of a locked object`, `Failed to unlock the secret item`, or a prompt that cannot open a display|Unlock the collection using the provider's headless unlocking method, then retry. Starting the provider or installing pinentry alone does not unlock it.
198+
`secret-tool lookup` returns no output and exits with `1`|No accessible matching secret was returned. This can mean either no matching entry or an unsuccessful unlock. Unlock the collection and retry with a known existing entry.
199+
`libsecret-1.so.0` cannot be loaded|Check that the libsecret runtime is installed for the architecture GCM is running on. On Ubuntu, the package is `libsecret-1-0`.
200+
201+
### Check the default collection
202+
203+
The default collection is an alias, not necessarily a collection named
204+
`login`. Ask the provider where it points:
205+
206+
```shell
207+
busctl --user call org.freedesktop.secrets \
208+
/org/freedesktop/secrets org.freedesktop.Secret.Service \
209+
ReadAlias s default
210+
```
211+
212+
An output of `o "/"` means no default collection is assigned. Use the
213+
provider's tools to create or select one. Otherwise, inspect the returned
214+
collection path rather than assuming it is the GNOME `login` keyring.
215+
216+
If the provider advertises a collection but cannot return its properties,
217+
restarting it may resolve inconsistent state. With GNOME Keyring, this can
218+
occur when independently started daemons create or unlock the keyring while
219+
another daemon serves D-Bus. The [unlock helper](#create-an-unlock-command)
220+
replaces the daemon it discovers, but may interrupt other applications.
221+
Do not delete keyring files to resolve a missing-object error.
222+
223+
[dbus]: https://www.freedesktop.org/wiki/Software/dbus/
224+
[gnome-keyring]: https://wiki.gnome.org/Projects/GnomeKeyring
225+
[kwallet]: https://invent.kde.org/frameworks/kwallet
226+
[oo7]: https://github.com/linux-credentials/oo7
227+
[systemd]: https://systemd.io/

0 commit comments

Comments
 (0)