e638a2defd
Adds the data file shipped by the optional authforge-gnome-integration package: a /usr/share/applications/.desktop overlay tagged with X-GNOME-Settings-Panel=user-accounts so gnome-control-center surfaces a "Configure security…" launcher inside each user's detail view. The README documents why a .desktop overlay was picked over a JS extension (cross-version stability, packaging simplicity) and how to verify the integration works in GNOME 46/47.
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# authforge-gnome-integration
|
|
|
|
Optional integration glue that surfaces the AuthForge GUI from inside
|
|
`gnome-control-center`'s **Users** panel, so administrators and end users can
|
|
reach FIDO2/U2F/TOTP enrollment from the same place they already manage
|
|
account password and login options.
|
|
|
|
## What this package ships
|
|
|
|
A single XDG `.desktop` file installed to
|
|
`/usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop`.
|
|
|
|
The file is tagged with `X-GNOME-Settings-Panel=user-accounts`, which is the
|
|
mechanism `gnome-control-center` (GNOME 46 / 47) uses to discover third-party
|
|
"helpers" for a specific settings panel. Entries with this key appear inside
|
|
the Users panel as an inline launcher rather than as a top-level app.
|
|
|
|
`NoDisplay=true` keeps the entry out of the normal application grid — the
|
|
full-fat AuthForge launcher (shipped by `authforge-gui`) already handles that
|
|
case. This overlay exists *only* to provide the in-Settings hook.
|
|
|
|
`OnlyShowIn=GNOME;` prevents KDE / Xfce / etc. from picking the entry up.
|
|
Those desktops have their own settings frameworks and their own integration
|
|
stories (out of scope for v1).
|
|
|
|
## Why a `.desktop` overlay and not a JS extension?
|
|
|
|
A GNOME Shell / `gnome-control-center` JS extension could in theory inject a
|
|
richer widget directly into the Users panel. We considered it and chose the
|
|
`.desktop` overlay instead because:
|
|
|
|
- **Cross-version stability.** The internal panel layout and JS API change
|
|
between GNOME releases (44 → 45 → 46 → 47 all moved things). A `.desktop`
|
|
hook is a stable freedesktop-spec mechanism that has worked unchanged for
|
|
years.
|
|
- **Packaging simplicity.** No GJS source, no shell-extension manifest, no
|
|
per-version compatibility matrix. Just a file in
|
|
`/usr/share/applications/`.
|
|
- **Lowest-risk.** A miswritten extension can crash the whole shell. A
|
|
miswritten `.desktop` file is a no-op.
|
|
|
|
JS-extension support is therefore **deferred** until upstream GNOME exposes
|
|
a stable cross-version "embed a third-party page in the Users panel" API. If
|
|
that ever lands we can ship it as a follow-up package; the `.desktop` overlay
|
|
will continue to work alongside it as a graceful-degradation fallback.
|
|
|
|
## Verifying the integration works
|
|
|
|
After installing `authforge-gnome-integration` (which depends on
|
|
`authforge-gui` and `gnome-control-center`):
|
|
|
|
1. Log out and back in (or `killall gnome-shell` on X11) to refresh the
|
|
desktop-file cache, *or* run
|
|
`update-desktop-database /usr/share/applications`.
|
|
2. Open **Settings** (`gnome-control-center`).
|
|
3. Navigate to **Users**.
|
|
4. Select a user account. The detail pane should now show a
|
|
**"Configure security…"** entry alongside the existing password / autologin
|
|
controls. Activating it launches the AuthForge GUI.
|
|
|
|
If the entry does not appear, sanity-check with:
|
|
|
|
```
|
|
desktop-file-validate /usr/share/applications/io.dangerousthings.AuthForge.UsersPanel.desktop
|
|
gtk-launch io.dangerousthings.AuthForge.UsersPanel
|
|
```
|
|
|
|
The first command must report no errors; the second must launch the GUI.
|
|
|
|
## Files
|
|
|
|
- `io.dangerousthings.AuthForge.UsersPanel.desktop` — the overlay entry,
|
|
installed to `/usr/share/applications/` by the deb.
|