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. If
376 the duktape JavaScript backend is compiled in, instead of mozjs, no
377 exception will be thrown—the script will be killed right away (same
378 timeout).
379 The spawn() method spawns an external helper identified by the argument
381 vector argv and waits for it to terminate. If an error occurs or the
382 helper doesn't exit normally with exit code 0, an exception is thrown.
383 If the helper does not exit within 10 seconds, it is killed. Otherwise,
384 the program's standard output is returned as a string. The spawn()
385 method should be used sparingly as helpers may take a very long or
386 indeterminate amount of time to complete and no other authorization
387 check can be handled while the helper is running. Note that the spawned
388 programs will run as the unprivileged polkitd system user.
389 The log() method writes the given message to the system logger prefixed
391 with the JavaScript filename and line number. Log entries are emitted
392 using the LOG_AUTHPRIV flag meaning that the log entries usually ends
393 up in the file /var/log/secure. The log() method is usually only used
394 when debugging rules. The Action and Subject types has suitable
395 toString() methods defined for easy logging, for example,
396 polkit.addRule(function(action, subject) {
398 if (action.id == "org.freedesktop.policykit.exec") {
399 polkit.log("action=" + action);
400 polkit.log("subject=" + subject);
401 }
402 });
403 will produce the following when the user runs 'pkexec -u bateman bash
405 -i' from a shell:
406 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)']
408 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]
409 The Action type
411 The action parameter passed to user functions is an object with
412 information about the action being checked. It is of type Action and
413 has the following attribute:
414 string id
416 The action identifier, for example org.freedesktop.policykit.exec.
417 The following methods are available on the Action type:
419 string lookup(string key);
421 The lookup() method is used to lookup the polkit variables passed from
423 the mechanism. For example, the pkexec(1) mechanism sets the variable
424 program which can be obtained in JavaScript using the expression
425 action.lookup("program"). If there is no value for the given key, then
426 undefined is returned.
427 Consult the documentation for each mechanism for what variables are
429 available for each action.
430 The Subject type
432 The subject parameter passed to user functions is an object with
433 information about the process being checked. It is of type Subject and
434 has the following attributes
435 int pid
437 The process id.
438 string user
440 The user name.
441 string[] groups
443 Array of groups that user user belongs to.
444 string seat
446 The seat that the subject is associated with - blank if not on a
447 local seat.
448 string session
450 The session that the subject is associated with.
451 boolean local
453 Set to true only if seat is local.
454 boolean active
456 Set to true only if the session is active.
457 The following methods are available on the Subject type:
459 boolean isInGroup(string groupName);
461 boolean isInNetGroup(string netGroupName);
463 The isInGroup() method can be used to check if the subject is in a
465 given group and isInNetGroup() can be used to check if the subject is
466 in a given netgroup.
467 Authorization Rules Examples
469 Allow all users in the admin group to perform user administration
470 without changing policy for other users:
471 polkit.addRule(function(action, subject) {
473 if (action.id == "org.freedesktop.accounts.user-administration" &&
474 subject.isInGroup("admin")) {
475 return polkit.Result.YES;
476 }
477 });
478 Define administrative users to be the users in the wheel group:
480 polkit.addAdminRule(function(action, subject) {
482 return ["unix-group:wheel"];
483 });
484 Forbid users in group children to change hostname configuration (that
486 is, any action with an identifier starting with
487 org.freedesktop.hostname1.) and allow anyone else to do it after
488 authenticating as themselves:
489 polkit.addRule(function(action, subject) {
491 if (action.id.indexOf("org.freedesktop.hostname1.") == 0) {
492 if (subject.isInGroup("children")) {
493 return polkit.Result.NO;
494 } else {
495 return polkit.Result.AUTH_SELF_KEEP;
496 }
497 }
498 });
499 Run an external helper to determine if the current user may reboot the
501 system:
502 polkit.addRule(function(action, subject) {
504 if (action.id.indexOf("org.freedesktop.login1.reboot") == 0) {
505 try {
506 // user-may-reboot exits with success (exit code 0)
507 // only if the passed username is authorized
508 polkit.spawn(["/opt/company/bin/user-may-reboot",
509 subject.user]);
510 return polkit.Result.YES;
511 } catch (error) {
512 // Nope, but do allow admin authentication
513 return polkit.Result.AUTH_ADMIN;
514 }
515 }
516 });
517 The following example shows how the authorization decision can depend
519 on variables passed by the pkexec(1) mechanism:
520 polkit.addRule(function(action, subject) {
522 if (action.id == "org.freedesktop.policykit.exec" &&
523 action.lookup("program") == "/usr/bin/cat") {
524 return polkit.Result.AUTH_ADMIN;
525 }
526 });
527 The following example shows another use of variables passed from the
529 mechanism. In this case, the mechanism is UDisks[10] which defines a
530 set of actions and variables[11] that is used to match on:
531 // Allow users in group 'engineers' to perform any operation on
533 // some drives without having to authenticate
534 //
535 polkit.addRule(function(action, subject) {
536 if (action.id.indexOf("org.freedesktop.udisks2.") == 0 &&
537 action.lookup("drive.vendor") == "SEAGATE" &&
538 action.lookup("drive.model") == "ST3300657SS" &&
539 subject.isInGroup("engineers")) {
540 return polkit.Result.YES;
541 }
542 }
543 });
544
546 Written by David Zeuthen <davidz@redhat.com> with a lot of help from
547 many others.
548
550 Please send bug reports to either the distribution or the polkit-devel
551 mailing list, see the link
552 https://gitlab.freedesktop.org/polkit/polkit/-/issues/ on how to
553 subscribe.
554
556 polkitd(8), pkaction(1), pkcheck(1), pkexec(1), pkttyagent(1)
557
559 1. /usr/share/gtk-doc/html/polkit-1/polkit-architecture.png
560 2. GObjectIntrospection
562 https://live.gnome.org/GObjectIntrospection
563 3. developer documentation
565 http://www.freedesktop.org/software/polkit/docs/latest/
566 4. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
568 example.png
569 5. /usr/share/gtk-doc/html/polkit-1/polkit-authentication-agent-
571 example-wheel.png
572 6. Freedesktop.org Icon Naming Specification
574 http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html
575 7. JavaScript
577 http://en.wikipedia.org/wiki/JavaScript
578 8. ECMA-262 edition 5
580 http://en.wikipedia.org/wiki/ECMAScript#ECMAScript.2C_5th_Edition
581 9. Date
583 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
584 10. UDisks
586 http://udisks.freedesktop.org/docs/latest/udisks.8.html
587 11. actions and variables
589 http://udisks.freedesktop.org/docs/latest/udisks-polkit-actions.html
590polkit February 2021 POLKIT(8)