18 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. However, this kind of
privilege is fixed and cannot be granted 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.
18.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
.
18.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 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.
18.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 administered 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 certain users to use it even without authorization.
18.1.3 Polkit Utilities #
Polkit provides utilities for specific tasks (see also their respective man pages for further details):
pkaction
Get details about a defined action. See Section 18.3, “Querying privileges” for more information.
pkcheck
Checks whether a process is authorized for a specific Polkit action.
pkexec
Allows programs to be executed as a different user based on Polkit authorization settings. This is similar to
su
orsudo
.pkttyagent
Starts a textual authentication agent. This agent is used if a desktop environment does not have its own authentication agent.
18.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.
18.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
, requiring the administrator (root
) password.
18.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 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:
/etc/polkit-default-privs.easy
Authorization settings tailored towards single-user desktop systems where the administrator is also the active interactive user. It offers 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 certain 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 18.4.3, “Modifying the SUSE default privileges”.
18.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 18.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
pkaction
on SUSE Linux Enterprise Server
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.
18.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. However,
granting certain Polkit actions without authentication
can be a security hazard that may grant a regular user full root
privileges. Reduce Polkit authentication requirements when you are certain
that this does not violate the system security in your specific environment.
18.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 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>
Root XML element of the policy file. | |
Start of the definition of the only action in this policy. | |
Here the implicit authorization settings as described above are found. | |
The |
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.
The Polkit authorization framework was formerly named PolicyKit. In certain places, like the XML document preamble above, this old name still appears.
18.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 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 file names
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, 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 https://www.freedesktop.org/software/polkit/docs/latest/ref-api.html.
18.4.3 Modifying the SUSE default privileges #
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 always take precedence over the predefined profile settings.
To add a custom privilege setting, do the following:
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 receive the same value, you can also specify a single value:
<action-id> <auth_all>
For example:
org.freedesktop.color-manager.modify-profile auth_admin_keep
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.
18.5 Restoring the SUSE default privileges #
To restore the SUSE default authorization settings follow these steps:
Choose the desired profile as described in Section 18.2.2, “SUSE default privileges”
Remove any overrides from
/etc/polkit-default-privs.local
.Run
set_polkit_default_privs
to regenerate the default rules.