Difference between revisions of "Polkit"

From ArchWiki
Jump to: navigation, search
(Workaround to mount by user without password)
(avoid singular they, rw)
 
(93 intermediate revisions by 30 users not shown)
Line 1: Line 1:
 
[[Category:Security]]
 
[[Category:Security]]
 
[[de:PolicyKit]]
 
[[de:PolicyKit]]
{{out of date|Now we have systemd and java in rule config}}
+
[[ja:Polkit]]
From [http://hal.freedesktop.org/docs/PolicyKit/introduction.html PolicyKit Library Reference Manual]:
+
[[zh-CN:Polkit]]
 +
{{Related articles start}}
 +
{{Related|Session}}
 +
{{Related|Sudo}}
 +
{{Related|Users and groups}}
 +
{{Related articles end}}
 +
From [http://www.freedesktop.org/wiki/Software/polkit/ polkit homepage]:
  
:''PolicyKit is an application-level toolkit for defining and handling the policy that allows unprivileged processes to speak to privileged processes: It is a framework for centralizing the decision making process with respect to granting access to privileged operations for unprivileged applications. PolicyKit is specifically targeting applications in rich desktop environments on multi-user UNIX-like operating systems. It does not imply or rely on any exotic kernel features.''
+
:''polkit is an application-level toolkit for defining and handling the policy that allows unprivileged processes to speak to privileged processes: It is a framework for centralizing the decision making process with respect to granting access to privileged operations for unprivileged applications.''
  
PolicyKit is used for controlling system-wide privileges. It provides an organized way for non-privileged processes to communicate with privileged ones. In contrast to systems such as sudo, it does not grant root permission to an entire process, but rather allows a finer level of control of centralized system policy.  
+
Polkit is used for controlling system-wide privileges. It provides an organized way for non-privileged processes to communicate with privileged ones. In contrast to systems such as sudo, it does not grant root permission to an entire process, but rather allows a finer level of control of centralized system policy.
  
PolicyKit works by delimiting distinct actions, e.g. running GParted, and delimiting users by group or by name, e.g. members of the wheel group. It then defines how -- if at all -- those users are allowed those actions, e.g. by identifying as members of the group by typing in their passwords.
+
Polkit works by delimiting distinct actions, e.g. running GParted, and delimiting users by group or by name, e.g. members of the wheel group. It then defines how if at all those users are allowed those actions, e.g. by identifying as members of the group by typing in their passwords.
  
==PolicyKit vs. polkit==
+
== Installation ==
In the development of PolicyKit, major changes were introduced around version 0.92. In order to make the distinction clear between the way the old and the new versions worked, the new ones are referred to as 'polkit' rather than PolicyKit. Searching for PolicyKit on the web will mostly point to outdated documentation and lead to confusion and frustration, e.g. [http://mdzlog.alcor.net/2010/06/27/navigating-the-policykit-maze/]. The main distinction between PolicyKit and polkit is the abandonment of single-file configuration in favour of directory-based configuration, i.e. there is no PolicyKit.conf.
+
  
==Structure==
+
Install the {{Pkg|polkit}} package.
PolicyKit definitions can be divided into three kinds:
+
* '''Actions''' are defined in XML .policy files located in {{ic|/usr/share/polkit-1/actions}}. Each action has a set of default permissions attached to it (e.g. you need to identify as an administrator to use the GParted action). The defaults can be overruled but editing the actions files is NOT the correct way (see [http://askubuntu.com/a/1399 askubuntu.com] for a bad example)
+
* '''Authorities''' are defined in INI-like .pkla files. They are found in two places: 3rd party packages can use {{ic|/var/lib/polkit-1}} (though few if any do) and {{ic|/etc/polkit-1}} is for local configuration. The .pkla files designate a subset of users, refer to one (or more) of the actions specified in the actions files and determine with what restrictions these actions can be taken by that/those user(s). As an example, an authority file could overrule the default requirement for all users to authenticate as an admin when using GParted, determining that some specific user doesn't need to. Or isn't allowed to use GParted at all.
+
* '''Admin identities''' are set in {{ic|/etc/polkit-1/localauthority.conf.d}} One of the basic points of using PolicyKit is determining whether or not a user needs to authenticate (possibly as an administrative user) or not in order to get permission to carry out the action. PolicyKit therefore has a specific configuration for deciding if the user trying to carry out an action is or is not an administrative user. Common definitions are 'only root user' or 'all members of wheel' (the Arch default).
+
  
===Actions===
+
=== Authentication agents ===
Each action is defined in an <action> tag in a .policy file. The {{ic|org.archlinux.pkexec.gparted.policy}} contains a single action and looks like this:
+
 
 +
An authentication agent is used to make the user of a session prove that the user of the session really is the user (by authenticating as the user) or an administrative user (by authenticating as an administrator). The {{Pkg|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 [[autostarting|autostarted]] on login.
 +
 
 +
[[Cinnamon]], [[Deepin Desktop Environment|Deepin]], [[GNOME]], [[GNOME Flashback]], [[KDE]], [[LXDE]], [[LXQt]], [[MATE]] and [[Xfce]] have an authentication agent already.
 +
In other desktop environments, you have to choose one of the following implementations:
 +
* {{Pkg|lxqt-policykit}}, which provides {{ic|/usr/bin/lxqt-policykit-agent}}
 +
* {{Pkg|lxsession}}, which provides {{ic|/usr/bin/lxpolkit}}
 +
* {{Pkg|mate-polkit}}, which provides {{ic|/usr/lib/mate-polkit/polkit-mate-authentication-agent-1}}
 +
* {{AUR|polkit-efl-git}}, which provides {{ic|/usr/bin/polkit-efl-authentication-agent-1}}
 +
* {{Pkg|polkit-gnome}}, which provides {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}}
 +
* {{Pkg|polkit-kde-agent}}, which provides {{ic|/usr/lib/polkit-kde/polkit-kde-authentication-agent-1}}
 +
* {{AUR|xfce-polkit-git}}, which provides {{ic|/usr/lib/xfce-polkit/xfce-polkit}}
 +
 
 +
== Configuration ==
 +
 
 +
{{Warning|Do not amend the default permission files of packages, as these may be be overwritten on package upgrades.}}
 +
 
 +
Polkit definitions can be divided into two kinds:
 +
* '''Actions''' are defined in XML {{ic|.policy}} files located in {{ic|/usr/share/polkit-1/actions}}. Each action has a set of default permissions attached to it (e.g. you need to identify as an administrator to use the GParted action). The defaults can be overruled but editing the actions files is NOT the correct way.
 +
*'''Authorization rules''' are defined in JavaScript {{ic|.rules}} files. They are found in two places: 3rd party packages can use {{ic|/usr/share/polkit-1/rules.d}} (though few if any do) and {{ic|/etc/polkit-1/rules.d}} is for local configuration.
 +
 
 +
Polkit operates on top of the existing permissions systems in Linux  – group membership, administrator status – it does not replace them. The .rules files designate a subset of users, refer to one (or more) of the actions specified in the actions files and determine with what restrictions these actions can be taken by that/those user(s). As an example, a rules file could overrule the default requirement for all users to authenticate as an admin when using GParted, determining that some specific user doesn't need to. Or isn't allowed to use GParted at all.
 +
 
 +
{{Note|This does not preclude running GParted by means which do not respect polkit, such as the command line. Therefore, polkit should be used to expand access to privileged services for unprivileged users, rather than try to curtail the rights of (semi-)privileged users. For security purposes, [[Sudo|sudoers]] is still the way to go.}}
 +
 
 +
=== Actions ===
 +
 
 +
{{Tip|To display Policykit actions in a graphical interface, install the {{AUR|polkit-explorer}} package.}}
 +
 
 +
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.archlinux.pkexec.gparted.policy)''. The command {{ic|pkaction}} lists all the actions defined in {{ic|/usr/share/polkit-1/actions}} for quick reference.
 +
 
 +
To get an idea of what polkit can do, here are a few commonly used groups of actions:
 +
* '''[[Systemd|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 {{ic|<action>}} tag in a .policy file. The {{ic|org.archlinux.pkexec.gparted.policy}} contains a single action and looks like this:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <!DOCTYPE policyconfig PUBLIC
 
  <!DOCTYPE policyconfig PUBLIC
 
   "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 
   "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
   "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
+
   <nowiki>"http://www.freedesktop.org/software/polkit/policyconfig-1.dtd"></nowiki>
 
  <policyconfig>
 
  <policyconfig>
 
   
 
   
Line 36: Line 75:
 
       <allow_active>auth_admin</allow_active>
 
       <allow_active>auth_admin</allow_active>
 
     </defaults>
 
     </defaults>
     <annotate key="org.freedesktop.policykit.exec.path">/usr/sbin/gparted</annotate>
+
     <annotate key="org.freedesktop.policykit.exec.path">/usr/bin/gparted</annotate>
 
     <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
 
     <annotate key="org.freedesktop.policykit.exec.allow_gui">true</annotate>
 
   </action>
 
   </action>
Line 42: Line 81:
 
  </policyconfig>
 
  </policyconfig>
  
The attribute '''id''' is the actual command sent to [[dbus]], the '''message''' tag is the explanation to the user when authentification is required and the '''icon_name''' is sort of obvious.  
+
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 default 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.  
+
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:
 
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 authentification.
+
* ''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 authentification.
+
* ''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_self'': Authentication is required but the user need not be an administrative user.
* '''auth_admin''': Authentication as an administrative user is require.
+
* ''auth_admin'': Authentication as an administrative user is require.
* '''auth_self_keep''': The same as auth_self but, like sudo, the authorization lasts a few minutes.
+
* ''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.
+
* ''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.
 
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.
 
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.
  
===Authorities===
+
=== Authorization rules ===
Authorizations 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 {{ic|/etc/polkit-1/localauthority/50-local.d}} should be used. The authority files are read in alphabetical/numerical order, where later files take precedence, so that one configuration file can be relied upon to overrule another, e.g.
+
10_allow_all_users_group_members_to_automount_without_authentification.pkla
+
15_but_not_jack.pkla
+
The layout of the .pkla files is fairly self-explanatory:
+
[Ban users jack and jill from using gparted]
+
Identity=unix-user:jack;unix-user:jill
+
Action=org.archlinux.pkexec.gparted
+
ResultAny=no
+
ResultInactive=no
+
ResultActive=no
+
An authorization needs to be preceded by a heading enclosed in square paratheses. The follows an identification with pairs of '''unix-user''' or '''unix-group''' and the name. Use semicolons to separate the pairs to include more than one user or group. The designating name of the action is the one from the action's id attribute in {{ic|/usr/share/polkit-1/actions}}. The three Result-settings mirror those from the action definition. Here we have overruled the default auth_admin setting and disallowed jack and jill from running gparted.
+
  
===Admin identities===
+
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 {{ic|/etc/polkit-1/rules.d}} should be used.  
Like the authorities files, configuration works by letting the last read file take precedence over earlier ones. The default configuration for admin identities is contained in the file {{ic|50-localauthority.conf}} so any changes to that configuration should be made by copying the file to, say, {{ic|60-localauthority.conf}} and editing that file.
+
{{hc|/etc/polkit-1/localauthority.conf.d/50-localauthority.conf|2=<nowiki>
+
# Configuration file for the PolicyKit Local Authority.
+
#
+
# DO NOT EDIT THIS FILE, it will be overwritten on update.
+
#
+
# See the pklocalauthority(8) man page for more information
+
# about configuring the Local Authority.
+
#
+
  
[Configuration]
+
The {{ic|addRule()}} 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 {{ic|/etc/polkit-1/rules.d}} with a name that sorts before other rules files, for example {{ic|00-early-checks.rules}}.
AdminIdentities=unix-group:wheel
+
</nowiki>}}
+
The only part to edit (once copied) is the right part of the equation: As whom should a user authenticate when asked to authenticate as an administrative user? If she herself is a member of the group designated as admins, she only need enter her own password. If some other user, e.g. root, is the only admin identity, she would need to enter in root's 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.
+
  
==Action groups==
+
The layout of the .rules files is fairly self-explanatory:
The actions available to you via PolicyKit 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.archlinux.pkexec.gparted.policy). The command{{ic|pkaction}} lists alle the actions defined in {{ic|/usr/share/polkit-1/actions}} for quick reference.
+
/* Allow users in admin group to run GParted without authentication */
 +
polkit.addRule(function(action, subject) {
 +
    if (action.id == "org.archlinux.pkexec.gparted" &&
 +
        subject.isInGroup("admin")) {
 +
        return polkit.Result.YES;
 +
    }
 +
});
  
To get an idea of what PolicyKit can do, here are a few commonly used groups of actions:
+
Inside the function, we check for the specified action ID ''(org.archlinux.pkexec.gparted)'' and for the user's group ''(admin)'', then return a value "yes".
* '''[[ConsoleKit]]''' (''org.freedesktop.consolekit.policy'') actions regulated by PolicyKit include shutting down and restarting, including when other users may still be logged in.
+
* '''[[Upower]]''' (''org.freedesktop.upower.policy'') actions regulated by PolicyKit include [[suspend_to_RAM|suspending]] and [[Pm-utils#Suspend.2FHibernate_as_regular_user|hibernating]].
+
* '''[[udisks|Udisks2]]''' (''org.freedesktop.udisks2.policy'') actions regulated by PolicyKit include mounting file systems and unclocking encrypted devices.
+
* '''[[NetworkManager]]''' (''org.freedesktop.NetworkManager.policy'') actions regulated by PolicyKit include turning on and off the network, wifi, or mobile broadband.
+
  
==Limitations==
+
=== Administrator identities ===
PolicyKit operates on top of the exisiting permissions systems in linux  -- group membership, administrator status -- it does not replace them. The example above prohibited the user jack from using the GParted action, but it does not preclude him running GParted by some means that do not respect PolicyKit, e.g. the command line. Therefore it's probably better to use PolicyKit to expand access to priviledged services for unpriviledged users, rather than to try using it to curtail the rights of (semi-)privileged users. For security purposes, the [[Sudo|sudoers file]] is still the way to go.
+
  
==Examples==
+
The {{ic|addAdminRule()}} 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.
  
===Suspend and hibernate===
+
The default configuration for administrator identities is contained in the file {{ic|50-default.rules}} so any changes to that configuration should be made by copying the file to, say, {{ic|40-default.rules}} and editing that file.
 +
{{hc|/etc/polkit-1/rules.d/50-default.rules|<nowiki>
 +
polkit.addAdminRule(function(action, subject) {
 +
    return ["unix-group:wheel"];
 +
});</nowiki>}}
  
To give the users in the group '''power''' the permission to suspend or hibernate using Upower, it is sufficient to create an authority file {{ic|/etc/polkit-1/localauthority/50-local.d/org.freedesktop.upower.pkla}} that allows group members the use of the two actions:
+
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 she herself is a member of the group designated as admins, she only need enter her own password. If some other user, e.g. root, is the only admin identity, she would need to enter in root's password. The format of the user identification is the same as the one used in designating authorities.
  
[Suspend/hibernate permissions]
+
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.
Identity=unix-group:power
+
Action=org.freedesktop.upower.hibernate;org.freedesktop.upower.suspend
+
ResultAny=yes
+
ResultInactive=yes
+
ResultActive=yes
+
  
Since the action groups change occasionally, it might be useful to check the documentation in {{ic|/usr/share/polkit-1/actions/org.freedesktop.upower.policy}} to make sure that the actions are correct.
+
{{hc|/etc/polkit-1/rules.d/49-rootpw_global.rules|
 +
/* Always authenticate Admins by prompting for the root
 +
* password, similar to the rootpw option in sudo
 +
*/
 +
polkit.addAdminRule(function(action, subject) {
 +
    return ["unix-user:root"];
 +
});
 +
}}
  
===Mounting USB drives===
+
== Examples ==
  
To grant users in the '''storage''' group the permission to mount/unmount/eject disks via Udisks2, the following lines can be written into a file {{ic|/etc/polkit-1/localauthority/50-local.d/org.freedesktop.udisks2.pkla}}:
+
=== Disable suspend and hibernate ===
  
[Storage Permissions]
+
The following rule disables suspend and hibernate for all users.
Identity=unix-group:storage
+
{{hc|/etc/polkit-1/rules.d/10-disable-suspend.rules|<nowiki>
Action=org.freedesktop.udisks2.filesystem-mount;org.freedesktop.udisks2.modify-device
+
polkit.addRule(function(action, subject) {
ResultAny=yes
+
    if (action.id == "org.freedesktop.login1.suspend" ||
ResultInactive=yes
+
        action.id == "org.freedesktop.login1.suspend-multiple-sessions" ||
ResultActive=yes
+
        action.id == "org.freedesktop.login1.hibernate" ||
 +
        action.id == "org.freedesktop.login1.hibernate-multiple-sessions")
 +
    {
 +
        return polkit.Result.NO;
 +
    }
 +
});</nowiki>}}
  
===Workaround to mount filesytems by user in group storage without password===
+
=== Bypass password prompt ===
the following lines can be written into a file {{ic|/etc/polkit-1/rules.d/10-udisks2.rules}}:
+
  
// Allow udisks2 to mount devices without authentication
+
To achieve something similar to the [[sudo]] {{ic|NOPASSWD}} option and get authorized solely based on [[Users_and_groups|user/group]] identity, you can create custom rules in {{ic|/etc/polkit-1/rules.d/}}. This allows you to override password authentication either [[#For_specific_actions|only for specific actions]] or [[#Globally|globally]]. See [https://gist.github.com/4013294/ccacedd69d54de7f2fd5881b546d5192d6a2bddb] for an example rule set.
// for users in the "storage" group.
+
 
  polkit.addRule(function(action, subject) {
+
==== Globally ====
  if ((action.id == "org.freedesktop.udisks2.filesystem-mount-system" ||
+
 
      action.id == "org.freedesktop.udisks2.filesystem-mount") &&subject.isInGroup("storage")) {
+
Create the following file as root:
 +
{{hc|/etc/polkit-1/rules.d/49-nopasswd_global.rules|
 +
/* Allow members of the wheel group to execute any actions
 +
* without password authentication, similar to "sudo NOPASSWD:"
 +
  */
 +
polkit.addRule(function(action, subject) {
 +
    if (subject.isInGroup("wheel")) {
 
         return polkit.Result.YES;
 
         return polkit.Result.YES;
 
     }
 
     }
});
+
});
  polkit.addRule(function(action, subject) {
+
}}
     if ((action.id == "org.freedesktop.udisks.filesystem-mount-system-internal") &&
+
 
subject.isInGroup("storage")) {
+
Replace {{ic|wheel}} 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.
 +
 
 +
==== For specific actions ====
 +
 
 +
Create the following file as root:
 +
{{hc|/etc/polkit-1/rules.d/49-nopasswd_limited.rules|<nowiki>
 +
/* Allow members of the wheel group to execute the defined actions
 +
  * without password authentication, similar to "sudo NOPASSWD:"
 +
*/
 +
polkit.addRule(function(action, subject) {
 +
     if ((action.id == "org.archlinux.pkexec.gparted" ||
 +
action.id == "org.libvirt.unix.manage") &&
 +
        subject.isInGroup("wheel"))
 +
    {
 
         return polkit.Result.YES;
 
         return polkit.Result.YES;
    }
+
    }
});
+
});
 +
</nowiki>}}
  
==Documentation==
+
The {{ic|action.id}}s 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 {{ic|wheel}}.
  
For a more thorough introduction and more advanced features, including globbing, see the man pages of polkit and pklocalauthority:
+
The {{ic|<nowiki>||</nowiki>}} operator is used to delimit actions (logical OR), and {{ic|&&}} means logical AND and must be kept as the last operator.
man polkit
+
 
 +
==== Udisks ====
 +
 
 +
[[File manager]]s 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.
 +
 
 +
=== Allow management of individual systemd units by regular users ===
 +
 
 +
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]]:
 +
 
 +
{{hc|/etc/polkit-1/rules.d/10-wifimanagement.rules|<nowiki>
 +
polkit.addRule(function(action, subject) {
 +
    if (action.id == "org.freedesktop.systemd1.manage-units") {
 +
        if (action.lookup("unit") == "wpa_supplicant.service") {
 +
            var verb = action.lookup("verb");
 +
            if (verb == "start" || verb == "stop" || verb == "restart") {
 +
                return polkit.Result.YES;
 +
            }
 +
        }
 +
    }
 +
});</nowiki>
 +
}}
  
man pklocalauthority
+
== See also ==
  
==See also==
+
* [http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html Polkit manual page]
* [[ConsoleKit]]
+

Latest revision as of 07:47, 20 April 2016

Related articles

From polkit homepage:

polkit is an application-level toolkit for defining and handling the policy that allows unprivileged processes to speak to privileged processes: It is a framework for centralizing the decision making process with respect to granting access to privileged operations for unprivileged applications.

Polkit is used for controlling system-wide privileges. It provides an organized way for non-privileged processes to communicate with privileged ones. In contrast to systems such as sudo, it does not grant root permission to an entire process, but rather allows a finer level of control of centralized system policy.

Polkit works by delimiting distinct actions, e.g. running GParted, and delimiting users by group or by name, e.g. members of the wheel group. It then defines how – if at all – those users are allowed those actions, e.g. by identifying as members of the group by typing in their passwords.

Installation

Install the polkit package.

Authentication agents

An authentication agent is used to make the user of a session prove that the user of the session really is 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 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, which provides /usr/bin/lxpolkit
  • mate-polkit, which provides /usr/lib/mate-polkit/polkit-mate-authentication-agent-1
  • polkit-efl-gitAUR, which provides /usr/bin/polkit-efl-authentication-agent-1
  • polkit-gnome, which provides /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1
  • polkit-kde-agent, which provides /usr/lib/polkit-kde/polkit-kde-authentication-agent-1
  • xfce-polkit-gitAUR, which provides /usr/lib/xfce-polkit/xfce-polkit

Configuration

Warning: Do not amend the default permission files of packages, as these may be be overwritten on package upgrades.

Polkit definitions can be divided into two kinds:

  • Actions are defined in XML .policy files located in /usr/share/polkit-1/actions. Each action has a set of default permissions attached to it (e.g. you need to identify as an administrator to use the GParted action). The defaults can be overruled but editing the actions files is NOT the correct way.
  • Authorization rules are defined in JavaScript .rules files. They are found in two places: 3rd party packages can use /usr/share/polkit-1/rules.d (though few if any do) and /etc/polkit-1/rules.d is for local configuration.

Polkit operates on top of the existing permissions systems in Linux – group membership, administrator status – it does not replace them. The .rules files designate a subset of users, refer to one (or more) of the actions specified in the actions files and determine with what restrictions these actions can be taken by that/those user(s). As an example, a rules file could overrule the default requirement for all users to authenticate as an admin when using GParted, determining that some specific user doesn't need to. Or isn't allowed to use GParted at all.

Note: This does not preclude running GParted by means which do not respect polkit, such as the command line. Therefore, polkit should be used to expand access to privileged services for unprivileged users, rather than try to curtail the rights of (semi-)privileged users. For security purposes, sudoers is still the way to go.

Actions

Tip: To display Policykit actions in a graphical interface, install the polkit-explorerAUR package.

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.archlinux.pkexec.gparted.policy). The command pkaction lists all the actions defined in /usr/share/polkit-1/actions 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 org.archlinux.pkexec.gparted.policy 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.archlinux.pkexec.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 require.
  • 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

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 /etc/polkit-1/rules.d should be used.

The addRule() 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 /etc/polkit-1/rules.d with a name that sorts before other rules files, for example 00-early-checks.rules.

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.archlinux.pkexec.gparted" &&
        subject.isInGroup("admin")) {
        return polkit.Result.YES;
    }
});

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

Administrator identities

The addAdminRule() 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 50-default.rules so any changes to that configuration should be made by copying the file to, say, 40-default.rules and editing that file.

/etc/polkit-1/rules.d/50-default.rules
polkit.addAdminRule(function(action, subject) {
    return ["unix-group:wheel"];
});

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 she herself is a member of the group designated as admins, she only need enter her own password. If some other user, e.g. root, is the only admin identity, she would need to enter in root's 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.

/etc/polkit-1/rules.d/49-rootpw_global.rules
/* Always authenticate Admins by prompting for the root
 * password, similar to the rootpw option in sudo
 */
polkit.addAdminRule(function(action, subject) {
    return ["unix-user:root"];
});

Examples

Disable suspend and hibernate

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;
    }
});

Bypass password prompt

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

Globally

Create the following file as root:

/etc/polkit-1/rules.d/49-nopasswd_global.rules
/* Allow members of the wheel group to execute any actions
 * without password authentication, similar to "sudo NOPASSWD:"
 */
polkit.addRule(function(action, subject) {
    if (subject.isInGroup("wheel")) {
        return polkit.Result.YES;
    }
});

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

For specific actions

Create the following file as root:

/etc/polkit-1/rules.d/49-nopasswd_limited.rules
/* Allow members of the wheel group to execute the defined actions 
 * without password authentication, similar to "sudo NOPASSWD:"
 */
polkit.addRule(function(action, subject) {
    if ((action.id == "org.archlinux.pkexec.gparted" ||
	 action.id == "org.libvirt.unix.manage") &&
        subject.isInGroup("wheel"))
    {
        return polkit.Result.YES;
    }
});

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

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

Udisks

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.

Allow management of individual systemd units by regular users

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:

/etc/polkit-1/rules.d/10-wifimanagement.rules
polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units") {
        if (action.lookup("unit") == "wpa_supplicant.service") {
            var verb = action.lookup("verb");
            if (verb == "start" || verb == "stop" || verb == "restart") {
                return polkit.Result.YES;
            }
        }
    }
});

See also