1PKLOCALAUTHORITY(8) pklocalauthority PKLOCALAUTHORITY(8)
2
6 pklocalauthority - PolicyKit Local Authority
7
9 The Local Authority is the default PolicyKit authority implementation.
10 Configuration for the Local Authority and information pertaining to
11 authorization decisions are read from local files on the disk. One
12 design goal of the Local Authority is to split configuration items into
13 separate files such that 3rd party packages and users won´t conflict
14 trying to edit the same files. This policy also ensures smooth upgrades
15 when distributing PolicyKit using a package management system.
16 Files shipped with PolicyKit and 3rd party packages (e.g. under package
18 manager control) typically have comments (such as “DO NOT EDIT THIS
19 FILE, it will be overwritten on update”) telling the system
20 administrator that changes will be overwritten on update.
21
23 PolicyKit makes a distinction between user authentication (to make the
24 user in front of the system prove he really is the user) and
25 administrator authentication (to make the user in front of the system
26 prove he really is an administrator). Since various operating systems
27 (or even flavors of the same operating system) has different ways of
28 defining "administrator", the Local Authority provides a way to specify
29 what "administrator authentication" means.
30 By default, "administrator authentication" is defined as asking for the
32 root password. Since some systems, for usability reasons, don´t have a
33 root password and instead rely on a group of users being member of an
34 administrative group that gives them super-user privileges, the Local
35 Authority can be configured to support this use-case as well.
36 Configuration for the Local Authority is read from files in the
38 /etc/polkit-1/localauthority.conf.d directory. All files are read in
39 lexigraphical order (using the C locale) meaning that later files can
40 override earlier ones. The file 50-localauthority.conf contains the
41 settings provided by the OS vendor. Users and 3rd party packages can
42 drop configuration files with a priority higher than 60 to change the
43 defaults. The configuration file format is simple. Each configuration
44 file is a key file (also commonly known as a ini file) with a single
45 group called [Configuration]. Only a single key, AdminIdentities is
46 read. The value of this key is a semi-colon separated list of
47 identities that can be used when administrator authentication is
48 required. Users are specified by prefixing the user name with
49 unix-user: and groups of users are specified by prefixing with
50 unix-group:. See the section called “EXAMPLES” for an example of a
51 configuration file.
52
54 The Local Authority reads files with .pkla extension from all
55 directories located inside the /etc/polkit-1/localauthority and
56 /var/lib/polkit-1/localauthority directories. By default, the following
57 sub-directories are installed.
58 /etc/polkit-1/
60 `-- localauthority
61 |-- 10-vendor.d
62 |-- 20-org.d
63 |-- 30-site.d
64 |-- 50-local.d
65 `-- 90-mandatory.d
66 and
69 /var/lib/polkit-1/
71 `-- localauthority
72 |-- 10-vendor.d
73 |-- 20-org.d
74 |-- 30-site.d
75 |-- 50-local.d
76 `-- 90-mandatory.d
77 The /etc/polkit-1/localauthority hierarchy is inteded for local
80 configuration and the /var/lib/polkit-1/localauthority is intended for
81 3rd party packages.
82 Each .pkla file contains one or more authorization entries. If the
84 underlying filesystem supports file monitoring, the Local Authority
85 will reload information whenever .pkla files are added, removed or
86 changed.
87 Each directory is intended for a specific audience
89 10-vendor.d
91 Intended for use by the OS vendor.
92 20-org.d
94 Intended for the organization deploying the OS.
95 30-site.d
97 Intended for the site deploying the system.
98 50-local.d
100 Intended for local usage.
101 90-mandatory.d
103 Intended for the organization deploying the OS.
104 and new directories can be added/removed as needed.
106 As to regards to the content, each .pkla file is a standard key file
108 and contains key/value pairs in one or more groups with each group
109 representing an authorization entry. A .pkla file MUST be named by
110 using a scheme to ensure that the name is unique, e.g. reverse DNS
111 notation or similar. For example, if the organization is “Acme Corp”
112 needs to modify policy for the product “Frobnicator”, a name like
113 com.acme.frobnicator.pkla would be suitable.
114
116 Each group in a .pkla file must have a name that is unique within the
117 file it belongs to. The following keys are are recognized:
118 Identity
120 A semi-colon separated list of globs to match identities. Each glob
121 should start with unix-user: or unix-group: to specify whether to
122 match on a UNIX user name or a UNIX group name. Finally, an entry
123 "default" (with no prefix) can be used to specify the default
124 match.
125 Action
127 A semi-colon separated list of globs to match action identifiers.
128 ResultActive
130 The result to return for subjects in an active local session that
131 matches one or more of the given identities. Allowed values are
132 similar to what can be used in the defaults section of .policy
133 files used to define actions, e.g. yes, no, auth_self,
134 auth_self_keep, auth_admin and auth_admin_keep.
135 ResultInactive
137 Like ResultActive but instead applies to subjects in inactive local
138 sessions.
139 ResultAny
141 Like ResultActive but instead applies to any subject.
142 ReturnValue
144 A semi-colon separated list of key/value pairs (of the form
145 key=value) that are added to the details of authorization result on
146 positive matches.
147 All keys specified above are required except that only at least one of
149 ResultAny, ResultInactive and ResultActive must be present. The
150 ReturnValue key is optional.
151
153 When a Mechanism requests services from the Authority to check if a
154 given Subject is authorized for a given Action, the authorization
155 entries discussed above are consulted using the following algorithm.
156 The authorization entries from all .pkla files are ordered using the
158 following rules. First all the basename of all sub-directories (e.g.
159 30-site.d) from both the /etc/polkit-1/localauthority and
160 /var/lib/polkit-1/localauthority directories are enumerated and sorted
161 (using the C locale). If a name exists in both /etc and /var, the one
162 in /etc takes precedence. Then all .pkla files are read in order from
163 this list of sub-directories. For each .pkla file, authorizations from
164 each file are appended in order resulting in an ordered list of
165 authorization entries.
166 For example, given the following files
168 /var/lib/polkit-1
170 └── localauthority
171 ├── 10-vendor.d
172 │ └── 10-desktop-policy.pkla
173 ├── 20-org.d
174 ├── 30-site.d
175 ├── 50-local.d
176 ├── 55-org.my.company.d
177 │ └── 10-org.my.company.product.pkla
178 └── 90-mandatory.d
179 /etc/polkit-1
181 └── localauthority
182 ├── 10-vendor.d
183 │ └── 01-some-changes-from-a-subvendor.pkla
184 ├── 20-org.d
185 ├── 30-site.d
186 ├── 50-local.d
187 ├── 55-org.my.company.d
188 │ └── 10-org.my.company.product.pkla
189 └── 90-mandatory.d
190 the evaluation order of the .pkla files is:
193 1. 10-desktop-policy.pkla
195 2. 01-some-changes-from-a-subvendor.pkla
197 3. 10-org.my.company.product.pkla (the /var one)
199 4. 10-org.my.company.product.pkla (the /etc one)
201 When the list of authorization entries has been calculated, the
203 authorization check can be made. First, the user of the Subject is
204 determined and the groups that the user belongs are looked up.
205 Then, authorization entries that include the "default" field value in
207 the Identity field are consulted in order. If the authorization entry
208 matches the data from the authorization check, then the authorization
209 result from RequireAny, RequireInactive or RequireActive is used and
210 ReturnValue is added to the authorization result.
211 For each group identity, all authorization entries that contain a
213 matching group entry are again consulted in the same manner.
214 Finally, the authorization entries are consulted using the user
216 identity in the same manner.
217 Note that processing continues even after a match. This allows for
219 socalled “negative authorizations”, see the section called “EXAMPLES”
220 for further discussion.
221
223 The following .conf file
224 [Configuration]
226 AdminIdentities=unix-group:desktop_admin_r
227 that any user in the desktop_admin_r UNIX group can be used for
230 authentication when administrator authentication is needed. This file
231 would typically be installed in the /etc/polkit-1/localauthority.conf.d
232 directory and given the name 60-desktop-policy.conf to ensure that it
233 is evaluted after the 50-localauthority.conf file shipped with
234 PolicyKit. If the local administrator wants to override this (suppose
235 60-desktop-policy.conf was shipped as part of the OS) he can simply
236 create a file 99-my-admin-configuration.conf with the following content
237 [Configuration]
239 AdminIdentities=unix-user:lisa;unix-user:marge
240 to specify that only the users lisa and marge can authenticate when
243 administrator authentication is needed.
244 The following .pkla file grants authorization to all users in the staff
246 group for actions matching the glob com.example.awesomeproduct.*
247 provided they are in an active session on the local console:
248 [Normal Staff Permissions]
250 Identity=unix-group:staff
251 Action=com.example.awesomeproduct.*
252 ResultAny=no
253 ResultInactive=no
254 ResultActive=yes
255 If the users homer and grimes are member of the staff group but policy
258 requires that an administrator needs to authenticate every time
259 authorization for any action matching com.example.awesomeproduct.* is
260 required, one would add
261 [Exclude Some Problematic Users]
263 Identity=unix-user:homer;unix-user:grimes
264 Action=com.example.awesomeproduct.*
265 ResultAny=no
266 ResultInactive=no
267 ResultActive=auth_admin
268 and make sure this authorization entry is after the first one.
271
273 Written by David Zeuthen davidz@redhat.com with a lot of help from many
274 others.
275
277 Please send bug reports to either the distribution or the polkit-devel
278 mailing list, see the link
279 http://lists.freedesktop.org/mailman/listinfo/polkit-devel on how to
280 subscribe.
281
283 polkit(8)
284polkit May 2009 PKLOCALAUTHORITY(8)