Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Linux Enterprise Desktop Documentation / Security and Hardening Guide / Local security / The Polkit authentication framework
Applies to SUSE Linux Enterprise Desktop 15 SP4

19 The Polkit authentication framework

Polkit is an authentication framework used in graphical Linux desktop environments, for fine-grained management of access rights on the system. Traditionally, there is a strong separation of privileges on Linux between the root user as the fully-authorized administrator account, and all other accounts and groups on the system. These non-administrator accounts may have certain additional privileges, like accessing sound hardware through an audio group. This kind of privilege is fixed, however, and cannot be granted only in certain specific situations, or for a certain duration of time.

Instead of fully switching to the root user (using programs such as sudo) for gaining higher privileges, Polkit grants specific privileges to a user or group on an as-needed basis. This is controlled by configuration files that describe individual actions that need to be authorized in a dynamic context.

19.1 Conceptual overview

Polkit consists of multiple components. polkitd is a privileged central background service that performs authentication checks based on the existing Polkit configuration. Polkit-enabled applications forward specific authentication requests to the polkitd daemon. A Polkit authentication agent running in the unprivileged user context is responsible for displaying authentication requests on behalf of the polkitd daemon, and providing the credentials that have been entered interactively by the user.

A Polkit action represents a single activity that is subject to Polkit's authorization rules. For example, the intent to reboot the computer can be modeled as a single action in Polkit. Each action has a unique identifier, for the reboot example the action is called org.freedesktop.login1.reboot.

19.1.1 The authentication agent

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.

19.1.2 Configuration of Polkit

Polkit's configuration consists of actions and authorization rules:

Actions (file extension *.policy)

Actions are defined in XML files that are located in /usr/share/polkit-1/actions. Each file defines one or more actions for a certain application domain, and each action contains human-readable descriptions and its default authorization settings. Although a system administrator can write their own rules, these default policy files must not be edited directly.

Authorization rules (file extension *.rules)

Rules are written in the JavaScript programming language, and are located in two places: /usr/share/polkit-1/rules.d is used by system packages, and /etc/polkit-1/rules.d is for locally adminstered configurations. The rule files contain more complex logic on top of the default action authorization settings. For example, a rule file could overrule a restrictive action and allow some users to use it even without authorization.

19.1.3 Polkit Utilities

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

pkaction

Get details about a defined action. See Section 19.3, “Querying Privileges” for more information.

pkcheck

Checks whether a process is authorized for a specific Polkit action.

pkexec

Allows executing programs as a different user based on Polkit authorization settings. This is similar to su or sudo.

pkttyagent

Starts a textual authentication agent. This agent is used if a desktop environment does not have its own authentication agent.

19.2 Authorization types

Every time a Polkit enabled application carries out a privileged operation, Polkit is asked whether the user is entitled to do so. The answer can be yes, no, or authentication needed. In the latter case an authentication dialog is displayed for the user to enter the necessary credentials.

19.2.1 Implicit Authorizations

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:

no

The user is never granted authorization of the desired action.

yes

The user is always granted authorization without the need to enter any credentials.

auth_self

The user needs to enter their own password for the action to be authorized.

auth_self_keep

Like auth_self, but the authorization is cached for a certain duration, for example, if the same action is executed by the same application again, then it is not necessary to re-enter the password.

auth_admin

The user needs to enter the administrator (root) password for the action to be authorized.

auth_admin_keep

Similar to auth_self_keep, only requiring the administrator (root) password.

19.2.2 SUSE default privileges

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 Desktop 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:

/etc/polkit-default-privs.easy

Authorization settings tailored towards single-user desktop systems where the administrator is also the only active interactive user. It offers somewhat reduced security in favor of improved user experience.

/etc/polkit-default-privs.standard

Balanced settings suitable for most systems.

/etc/polkit-default-privs.restrictive

More conservative authorization settings that reduce possible attack surface at the expense of user experience in some areas.

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 19.4.3, “Modifying the SUSE default privileges”.

19.3 Querying Privileges

To query privileges, use the command pkaction included in Polkit.

Polkit comes with command-line tools for changing privileges and executing commands as another user (see Section 19.1.3, “Polkit Utilities” for a short overview). Each existing policy has a unique name with which it can be identified. List all available policies with the command pkaction. See man pkaction for more information.

To display the needed authorization for a given policy (for example, org.freedesktop.login1.reboot), use pkaction as follows:

> pkaction -v --action-id=org.freedesktop.login1.reboot
org.freedesktop.login1.reboot:
  description:       Reboot the system
  message:           Authentication is required to allow rebooting the system
  vendor:            The systemd Project
  vendor_url:        http://www.freedesktop.org/wiki/Software/systemd
  icon:
  implicit any:      auth_admin_keep
  implicit inactive: auth_admin_keep
  implicit active:   yes
Note
Note: Restrictions of pkaction on SUSE Linux Enterprise Desktop

pkaction only takes the upstream defaults into account. It is not aware of the SUSE default privileges that are overriding the upstream defaults. Therefore be careful about interpreting this output.

19.4 Modifying Polkit Configuration

Adjusting Polkit settings is useful when you want to deploy the same set of policies to different machines, for example to the computers of a specific team. Customization of Polkit authorization settings can also be used to harden security for specific actions, or to improve the user experience by reducing the amount of password prompts for frequently-used actions. Note, however, that granting certain Polkit actions without authentication can be a security hazard that may grant a regular user full root privileges. Only lower Polkit authentication requirements when you are certain it doesn't violate the system security in your specific environment.

19.4.1 Overriding Polkit policy files

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>

1

Root XML element of the policy file.

2

Start of the definition of the only action in this policy.

3

Here the implicit authorization settings as described above are found.

4

The annotate element contains additional information regarding how Polkit performs an action. In this case, it contains the path to the gparted executable and a setting that this program is allowed to access the graphical display. These annotations are necessary for the use of an action in conjunction with the Polkit tool pkexec.

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
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.

19.4.2 Adding JavaScript authorization rules

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.

19.4.3 Modifying the SUSE default privileges

As described in Section 19.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:

Procedure 19.1: Modifying default privileges
  1. Edit /etc/polkit-default-privs.local. To define a privilege, add a line for each action in the following format:

    <action-id>     <auth_any>:<auth_inactive>:<auth_active>

    Alternatively, if all three categories will receive the same value, you can also specify only a single value:

    <action-id>     <auth_all>

    For example:

    org.freedesktop.color-manager.modify-profile     auth_admin_keep
  2. Run this tool as root for the changes to take effect:

    # /sbin/set_polkit_default_privs

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

19.5 Restoring the SUSE default privileges

To restore the SUSE default authorization settings follow these steps:

Procedure 19.2: Restoring the SUSE Linux Enterprise Desktop defaults
  1. Choose the desired profile as described in Section 19.2.2, “SUSE default privileges”

  2. Remove any overrides from /etc/polkit-default-privs.local.

  3. Run set_polkit_default_privs to regenerate the default rules.