MikeFaith/authforge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
99cde28bd219d0055c941d24e536d000fadf18ff
authforge/gnome-integration
History
michael e638a2defd gnome-integration: add Users-panel .desktop overlay and README 
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.
2026-04-27 08:34:50 -07:00
..
io.dangerousthings.AuthForge.UsersPanel.desktop
gnome-integration: add Users-panel .desktop overlay and README
2026-04-27 08:34:50 -07:00
README.md
gnome-integration: add Users-panel .desktop overlay and README
2026-04-27 08:34:50 -07:00

README.md

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.