18 The Polkit authentication framework #

When a user starts a graphical session in a fully-featured desktop environment, an authentication agent is typically started automatically, running in the background. You will only notice it when an authentication prompt appears in response to an application requesting authorization for a certain action. Using Polkit in text mode or via SSH is not easily possible, therefore this document focuses on its use in a graphical session context.

Polkit's configuration consists of actions and authorization rules:

Polkit provides a number of utilities for specific tasks (see also their respective man pages for further details):

When no dedicated Polkit JavaScript rules exist for a given action, the outcome depends on the implicit authorizations settings that are defined for each action in a Polkit policy file. There are three authorization categories: allow_active, allow_inactive, and allow_any. allow_active is applied to users in an active session. An active session is a local login on the text mode console or in a graphical user environment. The session becomes inactive when you switch to another console, for example, in which case the category allow_inactive is relevant. allow_any is used for all other contexts, for example for remote users logged in via SSH or VNC. Each of these categories has one of the following authorization settings assigned:

The implicit authorization settings found in Polkit policy files described so far are from the upstream developers of the respective applications. We will call these settings the upstream defaults. These upstream defaults are not necessarily the same defaults that are used on SUSE systems. SUSE Linux Enterprise Server comes with a predefined set of privileges that override the upstream defaults. These settings come in three different flavors (profiles) of which only one can be active at any time:

To switch the active polkit profile, edit /etc/sysconfig/security and adjust the value of POLKIT_DEFAULT_PRIVS to one of easy, standard, or restrictive. Then run the command set_polkit_default_privs as root.

Do not modify the profile settings in the files listed above. To define your own custom Polkit settings, use /etc/polkit-default-privs.local. For details, refer to Section 18.4.3, “Modifying the SUSE default privileges”.

The list of available Polkit actions depends on the packages that you have installed on your system. For a quick overview, use pkaction to list all actions Polkit knows about.

For the purposes of this example we will show how the command gparted (“GNOME Partition Editor”) is integrated into Polkit.

The file /usr/share/polkit-1/actions/org.opensuse.policykit.gparted.policy has the following content:

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

  <action id="org-opensuse-polkit-gparted"> 2
    <message>Authentication is required to run the GParted Partition Editor</message>
    <icon_name>gparted</icon_name>
    <defaults> 3
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
     < allow_active>auth_admin</allow_active>
    </defaults>
    <annotate 4
      key="org.freedesktop.policykit.exec.path">/usr/sbin/gparted</annotate>
    <annotate 4
      key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
  </action>

</policyconfig>

To add your own policy, create a .policy file with the structure above, add the appropriate action name into the id attribute, and define the desired override implicit authorization settings.

Note: Deprecated name PolicyKit

The Polkit authorization framework was formerly named PolicyKit. In some places, like in the XML document preamble above, this old name still appears.

Authorization rules overrule the implicit authorization settings. To add your own rules, store your files under /etc/polkit-1/rules.d/.

The files in this directory usually start with a two-digit number, a dash, a descriptive name, and end with .rules. Functions inside these files are executed in the lexicographical order of the filenames in the directory. For example, 00-foo.rules is ordered (and hence executed) before 60-bar.rules or even 90-default-privs.rules.

Inside the rule file, the script typically checks for the action ID to be authorized. For example, if you want to allow the command gparted to be executed by any member of the admin group, check for the action ID org.opensuse.policykit.gparted:

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

Find the description of all classes and methods of the functions in the Polkit API at http://www.freedesktop.org/software/polkit/docs/latest/ref-api.html.

As described in Section 18.2.2, “SUSE default privileges”, SUSE ships different override profiles for the Polkit implicit authorization settings defined by the upstream developers. Custom privileges can be defined in /etc/polkit-default-privs.local. Privileges defined here will always take precedence over the predefined profile settings. To add a custom privilege setting, do the following:

Refer to man polkit-default-privs for the full documentation of the SUSE Polkit default privileges.