polkit-agent-helper(8) — Chainguard OS Manuals

POLKIT-AGENT-HELPE(8)

polkit-agent-helper

POLKIT-AGENT-HELPE(8)

.SH "NAME" polkit-agent-helper - polkit authentication agent helper

.SH "SYNOPSIS"

.HP 528u

polkit-agent-helper-1

.SH "DESCRIPTION"

.PP polkit-agent-helper-1 is a privileged helper binary used internally by polkit authentication agents. It is not intended to be invoked directly by users or administrators. The helper is called by the authentication agent (via PolkitAgentSession) associated with the user session that initiated the authorization request. Its purpose is to verify the user's credentials through the system's authentication framework and relay authentication prompts between the agent and the authentication back-end.

.PP Multiple variants of this helper exist, one of which is selected at build time depending on the target platform's authentication infrastructure:

.PP PAM

Used on Linux systems with Pluggable Authentication Modules. This is the most common variant.

.RE
.PP BSD Auth

Used on OpenBSD systems with native BSD authentication.

.RE
.PP Shadow

Used on systems without PAM that rely on shadow password databases for credential verification.

.RE

.PP Regardless of the variant, the installed binary is always named polkit-agent-helper-1 and resides in /usr/lib/polkit-1/.

.PP See the polkit(8) man page for an overview of how authentication agents interact with the rest of the polkit architecture.

.SH "SANDBOXING"

.PP When the polkit-agent-helper.socket systemd socket unit is enabled (i.e. not masked or disabled), polkit-agent-helper-1 is socket-activated and runs as a systemd service (polkit-agent-helper@.service) started directly by systemd, removing the need for the SUID bit on the binary. This service operates in a tightly restricted sandbox. The service unit enables, among others, the following security directives: PrivateDevices=yes, ProtectHome=yes, PrivateNetwork=yes, PrivateTmp=yes, ProtectSystem=strict, and DevicePolicy=closed. See systemd.exec(5) for details on each directive.

.PP This sandboxing is intentional and significantly reduces the attack surface of the authentication helper. However, PAM modules that require access to hardware devices (e.g. USB security keys, TPM chips, fingerprint readers), user home directories (e.g. ~/.config key files), or other resources restricted by the sandbox will not function correctly under this configuration.

.PP The recommended approach is for PAM module creators to ship a systemd drop-in override file for the polkit-agent-helper@.service unit that relaxes only the specific directives their module requires. PAM module creators are in the best position to know what access their module needs, and maintaining the override alongside the module ensures it stays up to date as the module evolves.

.PP A drop-in override provided by the package vendor is a file placed in the directory /usr/lib/systemd/system/polkit-agent-helper@.service.d/. It should be prefixed with the owning module's name. It must have the extension .conf and contain only the directives to be overridden, prefixed with a [Service] section header. For example, a PAM module that needs access to TPM devices would install the following file:

# /usr/lib/systemd/system/polkit-agent-helper@.service.d/pinpam-tpm-access.conf
[Service]
DevicePolicy=auto
DeviceAllow=char-tpm rw
PrivateDevices=no

.PP Similarly, a module that needs to read files from the authenticating user's home directory would install:

# /usr/lib/systemd/system/polkit-agent-helper@.service.d/home-access.conf
[Service]
ProtectHome=read-only

.PP Only the directives that need to change should be included in the override; all other sandboxing remains in effect. Administrators may also place site-specific overrides in /etc/systemd/system/polkit-agent-helper@.service.d/, which take precedence over vendor-supplied drop-ins.

.PP Note that without such an override, affected PAM modules will fail silently or fall back to password authentication, which can be difficult to diagnose. If a PAM module works with sudo(8) or login services but not with polkit, the agent helper sandbox is the likely cause.

.SH "AUTHOR"

.PP Written by David Zeuthen, the polkit team and many kind contributors.

.SH "BUGS"

.PP Please send bug reports to either the distribution or the polkit-devel mailing list, see https://github.com/polkit-org/polkit#bugs-and-development.

June 2025

polkit