1POLKIT(8) polkit POLKIT(8)
2
6 polkit - Authorization Manager
7
9 polkit provides an authorization API intended to be used by privileged
10 programs (“MECHANISMS”) offering service to unprivileged programs
11 (“SUBJECTS”) often through some form of inter-process communication
12 mechanism. In this scenario, the mechanism typically treats the subject
13 as untrusted. For every request from a subject, the mechanism needs to
14 determine if the request is authorized or if it should refuse to
15 service the subject. Using the polkit APIs, a mechanism can offload
16 this decision to a trusted party: The polkit authority.
17 The polkit authority is implemented as an system daemon, polkitd(8),
19 which itself has little privilege as it is running as the polkitd
20 system user. Mechanisms, subjects and authentication agents communicate
21 with the authority using the system message bus.
22 In addition to acting as an authority, polkit allows users to obtain
24 temporary authorization through authenticating either an administrative
25 user or the owner of the session the client belongs to. This is useful
26 for scenarios where a mechanism needs to verify that the operator of
27 the system really is the user or really is an administrative user.
28
30 The system architecture of polkit is comprised of the Authority
31 (implemented as a service on the system message bus) and an
32 Authentication Agent per user session (provided and started by the
33 user's graphical environment). Actions are defined by applications.
34 Vendors, sites and system administrators can control authorization
35 policy through Authorization Rules.
36 [IMAGE][1]
38 +-------------------+
40 | Authentication |
41 | Agent |
42 +-------------------+
43 | libpolkit-agent-1 |
44 +-------------------+
45 ^ +---------+
46 | | Subject |
47 +--------------+ +---------+
48 | ^
49 | |
50 User Session | |
51 =======================|========================|=============
52 System Context | |
53 | |
54 | +---+
55 V |
56 /------------\ |
57 | System Bus | |
58 \------------/ |
59 ^ ^ V
60 | | +---------------------+
61 +--------------+ | | Mechanism |
62 | | +---------------------+
63 V +----> | libpolkit-gobject-1 |
64 +------------------+ +---------------------+
65 | polkitd(8) |
66 +------------------+
67 | org.freedesktop. |
68 | PolicyKit1 |<---------+
69 +------------------+ |
70 ^ |
71 | +--------------------------------------+
72 | | /usr/share/polkit-1/actions/*.policy |
73 | +--------------------------------------+
74 |
75 +--------------------------------------+
76 | /etc/polkit-1/rules.d/*.rules |
77 | /usr/share/polkit-1/rules.d/*.rules |
78 +--------------------------------------+
79 For convenience, the libpolkit-gobject-1 library wraps the polkit D-Bus
81 API and is usable from any C/C++ program as well as higher-level
82 languages supporting GObjectIntrospection[2] such as JavaScript and
83 Python. A mechanism can also use the D-Bus API or the pkcheck(1)
84 command to check authorizations. The libpolkit-agent-1 library provides
85 an abstraction of the native authentication system, e.g. pam(8) and
86 also facilities for registration and communication with the polkit
87 D-Bus service.
88 See the developer documentation[3] for more information about writing
90 polkit applications.
91
93 An authentication agent is used to make the user of a session prove
94 that the user of the session really is the user (by authenticating as
95 the user) or an administrative user (by authenticating as an
96 administrator). In order to integrate well with the rest of the user
97 session (e.g. match the look and feel), authentication agents are meant
98 to be provided by the user session that the user uses. For example, an
99 authentication agent may look like this:
100 [IMAGE][4]
102 +----------------------------------------------------------+
104 | |
105 | [Icon] Authentication required |
106 | |
107 | Authentication is required to format INTEL |
108 | SSDSA2MH080G1GC (/dev/sda) |
109 | |
110 | Administrator |
111 | |
112 | Password: [__________________________________] |
113 | |
114 | [Cancel] [Authenticate] |
115 +----------------------------------------------------------+
116 If the system is configured without a root account, it may prompt for a
118 specific user designated as the administrative user:
119 [IMAGE][5]
121 +----------------------------------------------------------+
123 | |
124 | [Icon] Authentication required |
125 | |
126 | Authentication is required to format INTEL |
127 | SSDSA2MH080G1GC (/dev/sda) |
128 | |
129 | [Icon] David Zeuthen |
130 | |
131 | Password: [__________________________________] |
132 | |
133 | [Cancel] [Authenticate] |
134 +----------------------------------------------------------+
135 Applications that do not run under a desktop environment (for example,
137 if launched from an ssh(1) login) may not have an authentication agent
138 associated with them. Such applications may use the
139 PolkitAgentTextListener type or the pkttyagent(1) helper so the user
140 can authenticate using a textual interface.
141
143 A mechanism needs to declare a set of actions in order to use polkit.
144 Actions correspond to operations that clients can request the mechanism
145 to carry out and are defined in XML files that the mechanism installs
146 into the /usr/share/polkit-1/actions directory.
147 polkit actions are namespaced and can only contain the characters
149 "[A-Z][a-z][0-9].-", e.g. ASCII, digits, period and hyphen. Each XML
150 file can contain more than one action but all actions need to be in the
151 same namespace and the file needs to be named after the namespace and
152 have the extension .policy.
153 The XML file must have the following doctype declaration
155 <?xml version="1.0" encoding="UTF-8"?>
157 <!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD polkit Policy Configuration 1.0//EN"
158 "http://www.freedesktop.org/software/polkit/policyconfig-1.dtd">
159 The policyconfig element must be present exactly once. Elements that
161 can be used inside policyconfig includes:
162 vendor
164 The name of the project or vendor that is supplying the actions in
165 the XML document. Optional.
166 vendor_url
168 A URL to the project or vendor that is supplying the actions in the
169 XML document. Optional.
170 icon_name
172 An icon representing the project or vendor that is supplying the
173 actions in the XML document. The icon name must adhere to the
174 Freedesktop.org Icon Naming Specification[6]. Optional.
175 action
177 Declares an action. The action name is specified using the id
178 attribute and can only contain the characters "[A-Z][a-z][0-9].- ",
179 e.g. ASCII, digits, period and hyphen.
180 Elements that can be used inside action include:
182 description
184 A human readable description of the action, e.g. “Install unsigned
185 software”.
186 message
188 A human readable message displayed to the user when asking for
189 credentials when authentication is needed, e.g. “Installing
190 unsigned software requires authentication”.
191 defaults
193 This element is used to specify implicit authorizations for
194 clients. Elements that can be used inside defaults include:
195 allow_any
197 Implicit authorizations that apply to any client. Optional.
198 allow_inactive
200 Implicit authorizations that apply to clients in inactive
201 sessions on local consoles. Optional.
202 allow_active
204 Implicit authorizations that apply to clients in active
205 sessions on local consoles. Optional.
206 Each of the allow_any, allow_inactive and allow_active elements can
208 contain the following values:
209 no
211 Not authorized.
212 yes
214 Authorized.
215 auth_self
217 Authentication by the owner of the session that the client
218 originates from is required. Note that this is not restrictive
219 enough for most uses on multi-user systems; auth_admin* is
220 generally recommended.
221 auth_admin
223 Authentication by an administrative user is required.
224 auth_self_keep
226 Like auth_self but the authorization is kept for a brief period
227 (e.g. five minutes). The warning about auth_self above applies
228 likewise.
229 auth_admin_keep
231 Like auth_admin but the authorization is kept for a brief
232 period (e.g. five minutes).
233 annotate
235 Used for annotating an action with a key/value pair. The key is
236 specified using the key attribute and the value is specified using
237 the value attribute. This element may appear zero or more times.
238 See below for known annotations.
239 vendor
241 Used for overriding the vendor on a per-action basis. Optional.
242 vendor_url
244 Used for overriding the vendor URL on a per-action basis. Optional.
245 icon_name
247 Used for overriding the icon name on a per-action basis. Optional.
248 For localization, description and message elements may occur multiple
250 times with different xml:lang attributes.
251 To list installed polkit actions, use the pkaction(1) command.
253 Known annotations
255 The org.freedesktop.policykit.exec.path annotation is used by the
256 pkexec program shipped with polkit - see the pkexec(1) man page for
257 details.
258 The org.freedesktop.policykit.imply annotation (its value is a string
260 containing a space-separated list of action identifiers) can be used to
261 define meta actions. The way it works is that if a subject is
262 authorized for an action with this annotation, then it is also
263 authorized for any action specified by the annotation. A typical use of
264 this annotation is when defining an UI shell with a single lock button
265 that should unlock multiple actions from distinct mechanisms.
266 The org.freedesktop.policykit.owner annotation can be used to define a
268 set of users who can query whether a client is authorized to perform
269 this action. If this annotation is not specified, then only root can
270 query whether a client running as a different user is authorized for an
271 action. The value of this annotation is a string containing a
272 space-separated list of PolkitIdentity entries, for example
273 "unix-user:42 unix-user:colord". A typical use of this annotation is
274 for a daemon process that runs as a system user rather than root.
275
277 polkitd reads .rules files from the /etc/polkit-1/rules.d and
278 /usr/share/polkit-1/rules.d directories by sorting the files in lexical
279 order based on the basename on each file (if there's a tie, files in
280 /etc are processed before files in /usr). For example, for the
281 following four files, the order is
282 • /etc/polkit-1/rules.d/10-auth.rules
284 • /usr/share/polkit-1/rules.d/10-auth.rules
286 • /etc/polkit-1/rules.d/15-auth.rules
288 • /usr/share/polkit-1/rules.d/20-auth.rules
290 Both directories are monitored so if a rules file is changed, added or
292 removed, existing rules are purged and all files are read and processed
293 again. Rules files are written in the JavaScript[7] programming
294 language and interface with polkitd through the global polkit object
295 (of type Polkit).
296 While the JavaScript interpreter used in particular versions of polkit
298 may support non-standard features (such as the let keyword),
299 authorization rules must conform to ECMA-262 edition 5[8] (in other
300 words, the JavaScript interpreter used may change in future versions of
301 polkit).
302 Authorization rules are intended for two specific audiences
304 • System Administrators
306 • Special-purpose Operating Systems / Environments
308 and those audiences only. In particular, applications, mechanisms and
310 general-purpose operating systems must never include any authorization
311 rules.
312 The Polkit type
314 The following methods are available on the polkit object:
315 void addRule(polkit.Result function(action, subject) {...});
317 void addAdminRule(string[] function(action, subject) {...});
319 void log(string message);
321 string spawn(string[] argv);
323 The addRule() method is used for adding a function that may be called
325 whenever an authorization check for action and subject is performed.
326 Functions are called in the order they have been added until one of the
327 functions returns a value. Hence, to add an authorization rule that is
328 processed before other rules, put it in a file in /etc/polkit-1/rules.d
329 with a name that sorts before other rules files, for example
330 00-early-checks.rules. Each function should return a value from
331 polkit.Result
332 polkit.Result = {
334 NO : "no",
335 YES : "yes",
336 AUTH_SELF : "auth_self",
337 AUTH_SELF_KEEP : "auth_self_keep",
338 AUTH_ADMIN : "auth_admin",
339 AUTH_ADMIN_KEEP : "auth_admin_keep",
340 NOT_HANDLED : null
341 };
342 corresponding to the values that can be used as defaults. If the
344 function returns polkit.Result.NOT_HANDLED, null, undefined or does not
345 return a value at all, the next user function is tried.
346 Keep in mind that if polkit.Result.AUTH_SELF_KEEP or
348 polkit.Result.AUTH_ADMIN_KEEP is returned, authorization checks for the
349 same action identifier and subject will succeed (that is, return
350 polkit.Result.YES) for the next brief period (e.g. five minutes) even
351 if the variables passed along with the check are different. Therefore,
352 if the result of an authorization rule depend on such variables, it
353 should not use the "*_KEEP" constants (if similar functionality is
354 required, the authorization rule can easily implement temporary
355 authorizations using the Date[9] type for timestamps).
356 The addAdminRule() method is used for adding a function that may be
358 called whenever administrator authentication is required. The function
359 is used to specify what identities may be used for administrator
360 authentication for the authorization check identified by action and
361 subject. Functions added are called in the order they have been added
362 until one of the functions returns a value. Each function should return
363 an array of strings where each string is of the form
364 "unix-group:<group>", "unix-netgroup:<netgroup>" or "unix-user:<user>".
365 If the function returns null, undefined or does not return a value at
366 all, the next function is tried.
367 There is no guarantee that a function registered with addRule() or
369 addAdminRule() is ever called - for example an early rules file could
370 register a function that always returns a value, hence ensuring that
371 functions added later are never called.
372 If user-provided code takes a long time to execute, an exception will
374 be thrown which normally results in the function being terminated (the
375 current limit is 15 seconds). This is used to catch runaway scripts.
376 The spawn() method spawns an external helper identified by the argument
378 vector argv and waits for it to terminate. If an error occurs or the
379 helper doesn't exit normally with exit code 0, an exception is thrown.
380 If the helper does not exit within 10 seconds, it is killed. Otherwise,
381 the program's standard output is returned as a string. The spawn()
382 method should be used sparingly as helpers may take a very long or
383 indeterminate amount of time to complete and no other authorization
384 check can be handled while the helper is running. Note that the spawned
385 programs will run as the unprivileged polkitd system user.
386 The log() method writes the given message to the system logger prefixed
388 with the JavaScript filename and line number. Log entries are emitted
389 using the LOG_AUTHPRIV flag meaning that the log entries usually ends
390 up in the file /var/log/secure. The log() method is usually only used
391 when debugging rules. The Action and Subject types has suitable
392 toString() methods defined for easy logging, for example,
393 polkit.addRule(function(action, subject) {
395 if (action.id == "org.freedesktop.policykit.exec") {
396 polkit.log("action=" + action);
397 polkit.log("subject=" + subject);
398 }
399 });
400 will produce the following when the user runs 'pkexec -u bateman bash
402 -i' from a shell:
403 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:3: action=[Action id='org.freedesktop.policykit.exec' command_line='/usr/bin/bash -i' program='/usr/bin/bash' user='bateman' user.gecos='Patrick Bateman' user.display='Patrick Bateman (bateman)']
405 May 24 14:28:50 thinkpad polkitd[32217]: /etc/polkit-1/rules.d/10-test.rules:4: subject=[Subject pid=1352 user='davidz' groups=davidz,wheel, seat='seat0' session='1' local=true active=true]
406 The Action type
408 The action parameter passed to user functions is an object with
409 information about the action being checked. It is of type Action and
410 has the following attribute:
411 string id
413 The action identifier, for example org.freedesktop.policykit.exec.
414 The following methods are available on the Action type:
416 string lookup(string key);
418 The lookup() method is used to lookup the polkit variables passed from
420 the mechanism. For example, the pkexec(1) mechanism sets the variable
421 program which can be obtained in JavaScript using the expression
422 action.lookup("program"). If there is no value for the given key, then
423 undefined is returned.
424 Consult the documentation for each mechanism for what variables are
426 available for each action.
427 The Subject type
429 The subject parameter passed to user functions is an object with
430 information about the process being checked. It is of type Subject and
431 has the following attributes
432 int pid
434 The process id.
435 string user
437 The user name.
438 string[] groups
440 Array of groups that user user belongs to.
441 string seat
443 The seat that the subject is associated with - blank if not on a
444 local seat.
445 string session
447 The session that the subject is associated with.
448 boolean local
450 Set to true only if seat is local.
451 boolean active
453 Set to true only if the session is active.
454 The following methods are available on the Subject type:
456 boolean isInGroup(string groupName);
458 boolean isInNetGroup(string netGroupName);
460 The isInGroup() method can be used to check if the subject is in a
462 given group and isInNetGroup() can be used to check if the subject is
463 in a given netgroup.
464 Authorization Rules Examples
466 Allow all users in the admin group to perform user administration
467 without changing policy for other users:
468 polkit.addRule(function(action, subject) {
470 if (action.id == "org.freedesktop.accounts.user-administration" &&
471 subject.isInGroup("admin")) {
472 return polkit.Result.YES;
473 }
474 });
475 Define administrative users to be the users in the wheel group:
477 polkit.addAdminRule(function(action, subject) {
479 return ["unix-group:wheel"];
480 });
481 Forbid users in group children to change hostname configuration (that
483 is, any action with an identifier starting with
484 org.freedesktop.hostname1.) and allow anyone else to do it after
485 authenticating as themselves:
486 polkit.addRule(function(action, subject) {
488 if (action.id.indexOf("org.freedesktop.hostname1.") == 0) {
489 if (subject.isInGroup("children")) {
490 return polkit.Result.NO;
491 } else {
492 return polkit.Result.AUTH_SELF_KEEP;
493 }
494 }
495 });
496 Run an external helper to determine if the current user may reboot the
498 system:
499 polkit.addRule(function(action, subject) {
501 if (action.id.indexOf("org.freedesktop.login1.reboot") == 0) {
502 try {
503 // user-may-reboot exits with success (exit code 0)
504 // only if the passed username is authorized
505 polkit.spawn(["/opt/company/bin/user-may-reboot",
506 subject.user]);
507 return polkit.Result.YES;
508 } catch (error) {
509 // Nope, but do allow admin authentication
510 return polkit.Result.AUTH_ADMIN;
511 }
512 }
513 });
514 The following example shows how the authorization decision can depend
516 on variables passed by the pkexec(1) mechanism:
517 polkit.addRule(function(action, subject) {
519 if (action.id == "org.freedesktop.policykit.exec" &&
520 action.lookup("program") == "/usr/bin/cat") {
521 return polkit.Result.AUTH_ADMIN;
522 }
523 });
524 The following example shows another use of variables passed from the
526 mechanism. In this case, the mechanism is UDisks[10] which defines a
527 set of actions and variables[11] that is used to match on:
528 // Allow users in group 'engineers' to perform any operation on
530 // some drives without having to authenticate
531 //
532 polkit.addRule(function(action, subject) {
533 if (action.id.indexOf("org.freedesktop.udisks2.") == 0 &&
534 action.lookup("drive.vendor") == "SEAGATE" &&
535 action.lookup("drive.model") == "ST3300657SS" &&
536 subject.isInGroup("engineers")) {
537 return polkit.Result.YES;
538 }
539 }
540 });
541
543 Written by David Zeuthen <davidz@redhat.com> with a lot of help from
544 many others.
545
547 Please send bug reports to either the distribution or the polkit-devel
548 mailing list, see the link
549 http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to
550 subscribe.
551
553 polkitd(8), pkaction(1), pkcheck(1), pkexec(1), pkttyagent(1)
554
556 1. /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png
557 2. GObjectIntrospection
559 https://live.gnome.org/GObjectIntrospection
560 3. developer documentation
562 http://www.freedesktop.org/software/polkit/docs/latest/
563 4. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
565 example.png
566 5. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
568 example-wheel.png
569 6. Freedesktop.org Icon Naming Specification
571 http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
572 7. JavaScript
574 http://en.wikipedia.org/wiki/JavaScript
575 8. ECMA-262 edition 5
577 http://en.wikipedia.org/wiki/ECMAScript#ECMAScript.2C_5th_Edition
578 9. Date
580 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
581 10. UDisks
583 http://udisks.freedesktop.org/docs/latest/udisks.8.html
584 11. actions and variables
586 http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html
587polkit February 2021 POLKIT(8)