cmd-polkit

Introducion

cmd-polkit is a tool that allows to easily customize the UI used to authenticate on polkit.

screenshot custom authentication using cmd-polkit with rofi — Fig.1 - custom authentication using cmd-polkit with rofi

screenshot custom authentication using cmd-polkit with zenity — Fig.2 - custom authentication using cmd-polkit with zenity

How it works

It works by calling the defined command and communicate via stdin and stdout, the command receives the message from stdin and sends it by writing to stdout, each line represents a message, the format used for communication is JSON.

The next figure show a sequence diagram of an authentication process. The "command" agent is the application to execute using the --command, or -c argument.

sequence diagram of a single authentication process — Fig.3 - authentication process

Authentication handling mode

To run cmd-polkit, it is required to explicitly select the authentication handling mode: serial or parallel. This section explains each mode usage.

Serial

The serial mode, executed with --serial, or -s argument, all polkit authentication are handled one at a time.

The next figure show a sequence diagram of an multiple authentication processes using serial mode. You will note that even after requesting a second authentication the command will only run after finishing the first authentication process.

sequence diagram of mutliple authentication processes in serial mode — Fig.4 - authentication process in serial mode

This is good for running GUI propmt applications that cannot have mutliple instances at the same time, like rofi.

Parallel

The parallel mode, executed with --parallel, or -p argument, Polkit authentication processes are handled in parallel.

The next figure show a sequence diagram of an multiple authentication processes using serial mode. Each command can handle the process independently.

sequence diagram of mutliple authentication processes in parallel mode — Fig.5 - authentication process in parallel mode

This is good for running GUI propmt applications that can have mutliple instances.

It is up to the user to define which mode is compatible with the GUI application that he wishes to use without needing to create and maintain a daemon for authentication in serie.

Message schemas

Authentication request

When polkit request authentication, cmd-polkit will send a message to command stdin that respects the following schema:

{
  "action": "request password",
  "prompt": string 
  "message": string 
  "polkit action": null | {
    "id": string
    "description": string
    "message": string
    "vendor name": string
    "vendor url": string
    "icon name": string
  }
}

action is hardcoded to show "request password"
prompt tha password input label, in other words, the prompt message to show to the user, just before the password input
message is the the message to show to the user
polkit action represents the polkit action related to the application that requests the authentication. Respects PolkitActionDescription^[1] more about actions on the Polkit documentation^[2]
- id is the polkit action ID
- description A human readable description of the action, e.g. “Install unsigned software”.
- message A human readable message displayed to the user when asking for credentials when authentication is needed, similar but not always equal to root message.
- vendor name is the name of the project or vendor that is supplying the action.
- vendor url is the url of the project or vendor that is supplying the action.
- icon name is the icon representing the project or vendor that is supplying the actions.

To give an example when executing pkexec echo 1 in a terminal with cmd-polkit active, the message it is send to command is similar to the following code:

{"action":"request password","prompt":"Password: ","message":"Authentication is needed to run `/usr/bin/echo 1' as the super user","action description":{"id":"org.freedesktop.policykit.exec","description":"Run a program as another user","message":"Authentication is required to run a program as another user","vendor name":"The polkit project","vendor url":"http://www.freedesktop.org/wiki/Software/polkit/","icon name":""}}

Authentication response

After the authentication message request is sent, it will expect a response from command stdout that respects the folloing schema, it will use the password to authenticate to polkit:

{
  "action": "authenticate",
  "password": string 
}

Authentication result

After authentication attempt is made is made, a message will be sent to command to show the result:

{
  "action": "authorization response",
  "authorized": boolean 
}

If the authentication is successful, a SIGINT message is sent to command to finish it, otherwise, another authentication message request is sent to command.

Fingerprint authentication 🫆

It is possible to use fingerprint for authentication by taking advantage of polkit support for Pluggable Authentication Modules (PAM)^[3] and fprint^[4].

Fprint setup

First, you will need a fprint supported fingerprint scanner, this is important. There is a limited number of devices that is supported by fprint, recent scanners are most likely not supported. fprint has a list of supported devices on https://fprint.freedesktop.org/supported-devices.html.

Then you will need to configure fprint by following the instructions regarding the distro you are using.

Generally you should have it setup with "fprintd-enroll" command, pointed to a finger choosen as an argument of the executable.

I leave are some links for some distros I found while learning how to configure it on my machine

Linux Mint, last seen on 2025-06-26: https://forums.linuxmint.com/viewtopic.php?t=408129
Arch Linux, last seen on 2025-06-26: https://wiki.archlinux.org/title/Fprint

PAM setup

After setup with fprint you will need to setup PAM on polkit. The polkit PAM configuration is in /etc/pam.d/polkit-1 file

If /etc/pam.d/polkit-1 does not exist, you copy from /usr/lib/pam.d/polkit-1 first before configuring it (the path may vary depending on the distro).

Depending on each distro you can configure in 2 ways: by using pam_fprintd.so or pam_fprintd_grosshack.so:

pam_fprintd.so

By configuring with pam_fprintd.so polkit will prompt for a password first; if you respond with and empty password, polkit will then proceed to use fingerprint authentication.

To configure with pam_fprintd.so, add following 2 lines at the top of /etc/pam.d/polkit-1:

auth		sufficient  	pam_unix.so try_first_pass likeauth nullok
auth		sufficient  	pam_fprintd.so
...

pam_fprintd_grosshack.so

By configuring with pam_fprintd.so polkit will prompt for a password first and fingerprint at the same time. This is sometimes needed for graphical programs which do not allow blank password input, such as Gnome's built-in polkit agent. pam_fprintd_grosshack.so is normally in a separate package, so you may need to install it.

To configure with pam_fprintd_grosshack.so, ensure it is installed and add following 2 lines at the top of /etc/pam.d/polkit-1:

auth            sufficient      pam_fprintd_grosshack.so
auth            sufficient      pam_unix.so try_first_pass nullok
...

References

¹ https://www.freedesktop.org/software/polkit/docs/latest/PolkitActionDescription.html#polkit-action-description-get-annotation, last seen on 2024-06-16.

² https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html, last seen on 2024-06-16.

³ https://web.archive.org/web/20210506140423/http://www.linux-pam.org/Linux-PAM-html/sag-introduction.html, last seen on 2025-06-28.

⁴ https://fprint.freedesktop.org, last seen on 2025-06-28.