polkit

An authentication agent is used to make the user of a session prove that they really are the user (by authenticating as the user) or an administrative user (by authenticating as an administrator). The polkit package contains a textual authentication agent called 'pkttyagent', which is used as a general fallback.

If you are using a graphical environment, make sure that a graphical authentication agent is installed and autostarted on login.

Cinnamon, Deepin, GNOME, GNOME Flashback, KDE, LXDE, LXQt, MATE, theShell and Xfce have an authentication agent already. In other desktop environments, you have to choose one of the following implementations:

• lxqt-policykit, which provides /usr/bin/lxqt-policykit-agent
• lxsession or lxsession-gtk3, which provides
• , which provides
• , which provides /usr/bin/polkit-efl-authentication-agent-1
• , which provides
• , which provides /usr/lib/polkit-kde-authentication-agent-1
• , which provides
• or , which provides
• , minimalistic desktop independent agent which provides /usr/bin/polkit-dumb-agent

The actions available to you via polkit will depend on the packages you have installed. Some are used in multiple desktop environments (org.freedesktop.*), some are DE-specific (org.gnome.*) and some are specific to a single program (org.gnome.gparted.policy). The command lists all the actions defined in for quick reference.

To get an idea of what polkit can do, here are a few commonly used groups of actions:

• systemd-logind (org.freedesktop.login1.policy) actions regulated by polkit include powering off, rebooting, suspending and hibernating the system, including when other users may still be logged in.
• udisks (org.freedesktop.udisks2.policy) actions regulated by polkit include mounting file systems and unlocking encrypted devices.
• NetworkManager (org.freedesktop.NetworkManager.policy) actions regulated by polkit include turning on and off the network, wifi or mobile broadband.

Each action is defined in an <action> tag in a .policy file. The contains a single action and looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
<policyconfig>

  <action id="org.gnome.gparted">
    <message>Authentication is required to run the GParted Partition Editor</message>
    <icon_name>gparted</icon_name>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
    <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/gparted</annotate>
    <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
  </action>

</policyconfig>

The attribute id is the actual command sent to D-Bus, the message tag is the explanation to the user when authentication is required and the icon_name is sort of obvious.

The defaults tag is where the permissions or lack thereof are located. It contains three settings: allow_any, allow_inactive, and allow_active. Inactive sessions are generally remote sessions (SSH, VNC, etc.) whereas active sessions are logged directly into the machine on a TTY or an X display. allow_any is the setting encompassing both scenarios.

For each of these settings the following options are available:

• no: The user is not authorized to carry out the action. There is therefore no need for authentication.
• yes: The user is authorized to carry out the action without any authentication.
• auth_self: Authentication is required but the user need not be an administrative user.
• auth_admin: Authentication as an administrative user is required.
• auth_self_keep: The same as auth_self but, like sudo, the authorization lasts a few minutes.
• auth_admin_keep: The same as auth_admin but, like sudo, the authorization lasts a few minutes.

These are default setting and unless overruled in later configuration will be valid for all users.

As can be seen from the GParted action, users are required to authenticate as administrators in order to use GParted, regardless of whether the session is active or inactive.

Authorization rules that overrule the default settings are laid out in a set of directories as described above. For all purposes relating to personal configuration of a single system, only should be used.

The method is used for adding a function that may be called whenever an authorization check for action and subject is performed. Functions are called in the order they have been added until one of the functions returns a value. Hence, to add an authorization rule that is processed before other rules, put it in a file in with a name that sorts before other rules files, for example .

The layout of the .rules files is fairly self-explanatory:

/* Allow users in admin group to run GParted without authentication */
polkit.addRule(function(action, subject) {
    if (action.id == "org.gnome.gparted" &&
        subject.isInGroup("admin")) {
        return polkit.Result.YES;
    }
});

Inside the function, we check for the specified action ID (org.gnome.gparted) and for the user's group (admin), then return a value "yes".

The method is used for adding a function that may be called whenever administrator authentication is required. The function is used to specify what identities may be used for administrator authentication for the authorization check identified by action and subject. Functions added are called in the order they have been added until one of the functions returns a value.

The default configuration for administrator identities is contained in the file so any changes to that configuration should be made by copying the file to, say, and editing that file.

The only part to edit (once copied) is the return array of the function: as whom should a user authenticate when asked to authenticate as an administrative user? If they are a member of the group designated as admins, they only need enter their own password. If some other user, e.g. root, is the only admin identity, they would need to enter the root password. The format of the user identification is the same as the one used in designating authorities.

The Arch default is to make all members of the group wheel administrators. A rule like below will have polkit ask for the root password instead of the users password for Admin authentication.

The following rule logs detailed information about any requested access.

The following rule disables suspend and hibernate for all users.

/etc/polkit-1/rules.d/10-disable-suspend.rules

polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.login1.suspend" ||
        action.id == "org.freedesktop.login1.suspend-multiple-sessions" ||
        action.id == "org.freedesktop.login1.hibernate" ||
        action.id == "org.freedesktop.login1.hibernate-multiple-sessions")
    {
        return polkit.Result.NO;
    }
});

To achieve something similar to the sudo option and get authorized solely based on user/group identity, you can create custom rules in . This allows you to override password authentication either only for specific actions or globally. See for an example rule set.

Create the following file as root:

Replace by any group of your preference.

This will result in automatic authentication for any action requiring admin rights via Polkit. As such, be careful with the group you choose to give such rights to.

There is also which allows to keep the authorization for 5 minutes. However, the authorization is per process, hence if a new process asks for an authorization within 5 minutes the new process will ask for the password again anyway.

Create the following file as root:

The action.ids selected here are just (working) examples for GParted and Libvirt, but you can replace them by any other of your liking as long as they exist (custom made or supplied by a package), and so can you define any group instead of .

The operator is used to delimit actions (logical OR), and means logical AND and must be kept as the last operator.

File managers may ask for a password when trying to mount a storage device, or yield a Not authorized or similar error. See Udisks#Configuration for details.

By checking for certain values passed to the polkit policy check, you can give specific users or groups the ability to manage specific units. As an example, you might want regular users to start and stop wpa_supplicant: