]>
Commit | Line | Data |
---|---|---|
80c0adcb | 1 | [[chapter_user_management]] |
506839a5 SS |
2 | |
3 | [[user_mgmt]] | |
4 | ||
3c8533f2 | 5 | ifdef::manvolnum[] |
b2f242ab DM |
6 | pveum(1) |
7 | ======== | |
5f09af76 DM |
8 | :pve-toplevel: |
9 | ||
3c8533f2 DM |
10 | NAME |
11 | ---- | |
12 | ||
13 | pveum - Proxmox VE User Manager | |
14 | ||
15 | ||
49a5e11c | 16 | SYNOPSIS |
3c8533f2 DM |
17 | -------- |
18 | ||
19 | include::pveum.1-synopsis.adoc[] | |
20 | ||
21 | ||
22 | DESCRIPTION | |
23 | ----------- | |
24 | endif::manvolnum[] | |
3c8533f2 DM |
25 | ifndef::manvolnum[] |
26 | User Management | |
27 | =============== | |
5f09af76 | 28 | :pve-toplevel: |
194d2f29 | 29 | endif::manvolnum[] |
5f09af76 | 30 | |
3c8533f2 DM |
31 | // Copied from pve wiki: Revision as of 16:10, 27 October 2015 |
32 | ||
96942248 | 33 | {pve} supports multiple authentication sources, for example Linux PAM, |
5462c161 | 34 | an integrated Proxmox VE authentication server, LDAP, Microsoft Active |
96942248 | 35 | Directory and OpenID Connect. |
3c8533f2 | 36 | |
96942248 DW |
37 | By using role-based user and permission management for all objects (VMs, |
38 | Storage, nodes, etc.), granular access can be defined. | |
5eba0743 | 39 | |
3c8533f2 | 40 | |
80c0adcb | 41 | [[pveum_users]] |
c80b9ee6 WB |
42 | Users |
43 | ----- | |
44 | ||
45 | {pve} stores user attributes in `/etc/pve/user.cfg`. | |
96942248 | 46 | Passwords are not stored here; users are instead associated with the |
80c0adcb | 47 | <<pveum_authentication_realms,authentication realms>> described below. |
96942248 | 48 | Therefore, a user is often internally identified by their username and |
c80b9ee6 WB |
49 | realm in the form `<userid>@<realm>`. |
50 | ||
51 | Each user entry in this file contains the following information: | |
52 | ||
53 | * First name | |
54 | * Last name | |
55 | * E-mail address | |
56 | * Group memberships | |
96942248 | 57 | * An optional expiration date |
c80b9ee6 WB |
58 | * A comment or note about this user |
59 | * Whether this user is enabled or disabled | |
74662f51 | 60 | * Optional two-factor authentication keys |
c80b9ee6 | 61 | |
96942248 | 62 | CAUTION: When you disable or delete a user, or if the expiry date set is |
f06ba6a6 | 63 | in the past, this user will not be able to log in to new sessions or start new |
96942248 | 64 | tasks. All tasks which have already been started by this user (for example, |
f06ba6a6 | 65 | terminal sessions) will **not** be terminated automatically by any such event. |
8d02d0a2 | 66 | |
c80b9ee6 WB |
67 | |
68 | System administrator | |
69 | ~~~~~~~~~~~~~~~~~~~~ | |
70 | ||
71 | The system's root user can always log in via the Linux PAM realm and is an | |
72 | unconfined administrator. This user cannot be deleted, but attributes can | |
96942248 | 73 | still be changed. System mails will be sent to the email address |
c80b9ee6 WB |
74 | assigned to this user. |
75 | ||
76 | ||
80c0adcb | 77 | [[pveum_groups]] |
c80b9ee6 | 78 | Groups |
a10a91c2 | 79 | ------ |
c80b9ee6 | 80 | |
96942248 DW |
81 | Each user can be a member of several groups. Groups are the preferred |
82 | way to organize access permissions. You should always grant permissions | |
83 | to groups instead of individual users. That way you will get a | |
84 | much more maintainable access control list. | |
c80b9ee6 | 85 | |
181db098 FG |
86 | [[pveum_tokens]] |
87 | API Tokens | |
a10a91c2 | 88 | ---------- |
181db098 | 89 | |
96942248 | 90 | API tokens allow stateless access to most parts of the REST API from another |
710713ea TL |
91 | system, software or API client. Tokens can be generated for individual users |
92 | and can be given separate permissions and expiration dates to limit the scope | |
96942248 | 93 | and duration of the access. Should the API token get compromised, it can be |
710713ea | 94 | revoked without disabling the user itself. |
181db098 FG |
95 | |
96 | API tokens come in two basic types: | |
97 | ||
96942248 DW |
98 | * Separated privileges: The token needs to be given explicit access with ACLs. |
99 | Its effective permissions are calculated by intersecting user and token | |
181db098 | 100 | permissions. |
96942248 | 101 | * Full privileges: The token's permissions are identical to that of the |
181db098 FG |
102 | associated user. |
103 | ||
c6e098a2 TL |
104 | CAUTION: The token value is only displayed/returned once when the token is |
105 | generated. It cannot be retrieved again over the API at a later time! | |
181db098 FG |
106 | |
107 | To use an API token, set the HTTP header 'Authorization' to the displayed value | |
108 | of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or | |
96942248 | 109 | refer to your API client's documentation. |
c80b9ee6 | 110 | |
23b447be DW |
111 | [[pveum_resource_pools]] |
112 | Resource Pools | |
113 | -------------- | |
114 | ||
115 | [thumbnail="screenshot/gui-datacenter-pool-window.png"] | |
116 | ||
117 | A resource pool is a set of virtual machines, containers, and storage | |
118 | devices. It is useful for permission handling in cases where certain users | |
119 | should have controlled access to a specific set of resources, as it allows for a | |
120 | single permission to be applied to a set of elements, rather than having to | |
96942248 DW |
121 | manage this on a per-resource basis. Resource pools are often used in tandem |
122 | with groups, so that the members of a group have permissions on a set of | |
123 | machines and storage. | |
23b447be | 124 | |
80c0adcb | 125 | [[pveum_authentication_realms]] |
3c8533f2 DM |
126 | Authentication Realms |
127 | --------------------- | |
128 | ||
d6614202 WB |
129 | As {pve} users are just counterparts for users existing on some external |
130 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
131 | The following realms (authentication methods) are available: | |
3c8533f2 | 132 | |
78000a64 DW |
133 | Linux PAM Standard Authentication:: |
134 | ||
135 | Linux PAM is a framework for system-wide user authentication. These users are | |
136 | created on the host system with commands such as `adduser`. If PAM users exist | |
137 | on the {pve} host system, corresponding entries can be added to {pve}, to allow | |
138 | these users to log in via their system username and password. | |
3c8533f2 | 139 | |
78000a64 DW |
140 | {pve} Authentication Server:: |
141 | ||
142 | This is a Unix-like password store, which stores hashed passwords in | |
143 | `/etc/pve/priv/shadow.cfg`. Passwords are hashed using the SHA-256 hashing | |
144 | algorithm. This is the most convenient realm for small-scale (or even | |
145 | mid-scale) installations, where users do not need access to anything outside of | |
146 | {pve}. In this case, users are fully managed by {pve} and are able to change | |
147 | their own passwords via the GUI. | |
d6614202 WB |
148 | |
149 | LDAP:: | |
78000a64 DW |
150 | |
151 | LDAP (Lightweight Directory Access Protocol) is an open, cross-platform protocol | |
152 | for authentication using directory services. OpenLDAP is a popular open-source | |
153 | implementations of the LDAP protocol. | |
154 | ||
155 | Microsoft Active Directory (AD):: | |
156 | ||
157 | Microsoft Active Directory (AD) is a directory service for Windows domain | |
158 | networks and is supported as an authentication realm for {pve}. It supports LDAP | |
159 | as an authentication protocol. | |
160 | ||
161 | OpenID Connect:: | |
162 | ||
163 | OpenID Connect is implemented as an identity layer on top of the OATH 2.0 | |
164 | protocol. It allows clients to verify the identity of the user, based on | |
165 | authentication performed by an external authorization server. | |
166 | ||
7d8e9391 | 167 | [[user-realms-pam]] |
78000a64 DW |
168 | Linux PAM Standard Authentication |
169 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
170 | ||
171 | As Linux PAM corresponds to host system users, a system user must exist on each | |
172 | node which the user is allowed to log in on. The user authenticates with their | |
173 | usual system password. This realm is added by default and can't be removed. In | |
174 | terms of configurability, an administrator can choose to require two-factor | |
175 | authentication with logins from the realm and to set the realm as the default | |
176 | authentication realm. | |
177 | ||
178 | ||
7d8e9391 | 179 | [[user-realms-pve]] |
78000a64 DW |
180 | {pve} Authentication Server |
181 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
182 | ||
183 | The {pve} authentication server realm is a simple Unix-like password store. | |
184 | The realm is created by default, and as with Linux PAM, the only configuration | |
185 | items available are the ability to require two-factor authentication for users | |
186 | of the realm, and to set it as the default realm for login. | |
187 | ||
188 | Unlike the other {pve} realm types, users are created and authenticated entirely | |
189 | through {pve}, rather than authenticating against another system. Hence, you are | |
190 | required to set a password for this type of user upon creation. | |
191 | ||
192 | ||
7d8e9391 | 193 | [[user-realms-ldap]] |
78000a64 DW |
194 | LDAP |
195 | ~~~~ | |
196 | ||
197 | You can also use an external LDAP server for user authentication (for examle, | |
198 | OpenLDAP). In this realm type, users are searched under a 'Base Domain Name' | |
199 | (`base_dn`), using the username attribute specified in the 'User Attribute Name' | |
d6614202 | 200 | (`user_attr`) field. |
78000a64 DW |
201 | |
202 | A server and optional fallback server can be configured, and the connection can | |
203 | be encrypted via SSL. Furthermore, filters can be configured for directories and | |
204 | groups. Filters allow you to further limit the scope of the realm. | |
205 | ||
206 | For instance, if a user is represented via the following LDIF dataset: | |
207 | ||
d6614202 WB |
208 | ---- |
209 | # user1 of People at ldap-test.com | |
210 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
211 | objectClass: top | |
212 | objectClass: person | |
213 | objectClass: organizationalPerson | |
214 | objectClass: inetOrgPerson | |
215 | uid: user1 | |
216 | cn: Test User 1 | |
217 | sn: Testers | |
218 | description: This is the first test user. | |
219 | ---- | |
78000a64 | 220 | |
d6614202 WB |
221 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user |
222 | attribute would be `uid`. | |
78000a64 | 223 | |
3a433e9b | 224 | If {pve} needs to authenticate (bind) to the LDAP server before being |
d6614202 WB |
225 | able to query and authenticate users, a bind domain name can be |
226 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
227 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
96942248 DW |
228 | (for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a |
229 | single line with the raw password. | |
78000a64 | 230 | |
96942248 | 231 | To verify certificates, you need to set `capath`. You can set it either |
4ab527b1 TL |
232 | directly to the CA certificate of your LDAP server, or to the system path |
233 | containing all trusted CA certificates (`/etc/ssl/certs`). | |
3a433e9b | 234 | Additionally, you need to set the `verify` option, which can also be done over |
4ab527b1 | 235 | the web interface. |
d6614202 | 236 | |
78000a64 DW |
237 | The main configuration options for an LDAP server realm are as follows: |
238 | ||
239 | * `Realm` (`realm`): The realm identifier for {pve} users | |
240 | ||
241 | * `Base Domain Name` (`base_dn`): The directory which users are searched under | |
242 | ||
243 | * `User Attribute Name` (`user_attr`): The LDAP attribute containing the | |
244 | username that users will log in with | |
245 | ||
246 | * `Server` (`server1`): The server hosting the LDAP directory | |
247 | ||
248 | * `Fallback Server` (`server2`): An optional fallback server address, in case | |
249 | the primary server is unreachable | |
250 | ||
251 | * `Port` (`port`): The port that the LDAP server listens on | |
252 | ||
96942248 | 253 | NOTE: In order to allow a particular user to authenticate using the LDAP server, |
78000a64 DW |
254 | you must also add them as a user of that realm from the {pve} server. This can |
255 | be carried out automatically with <<pveum_ldap_sync, syncing>>. | |
3c8533f2 | 256 | |
3c8533f2 | 257 | |
7d8e9391 | 258 | [[user-realms-ad]] |
78000a64 DW |
259 | Microsoft Active Directory (AD) |
260 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
f3ee27eb | 261 | |
78000a64 DW |
262 | To set up Microsoft AD as a realm, a server address and authentication domain |
263 | need to be specified. Active Directory supports most of the same properties as | |
264 | LDAP, such as an optional fallback server, port, and SSL encryption. | |
265 | Furthermore, users can be added to {pve} automatically via | |
266 | <<pveum_ldap_sync, sync>> operations, after configuration. | |
267 | ||
268 | As with LDAP, if {pve} needs to authenticate before it binds to the AD server, | |
269 | you must configure the 'Bind User' (`bind_dn`) property. This property is | |
270 | typically required by default for Microsoft AD. | |
271 | ||
272 | The main configuration settings for Microsoft Active Directory are: | |
273 | ||
274 | * `Realm` (`realm`): The realm identifier for {pve} users | |
275 | ||
276 | * `Domain` (`domain`): The AD domain of the server | |
277 | ||
278 | * `Server` (`server1`): The FQDN or IP address of the server | |
279 | ||
280 | * `Fallback Server` (`server2`): An optional fallback server address, in case | |
281 | the primary server is unreachable | |
282 | ||
283 | * `Port` (`port`): The port that the Microsoft AD server listens on | |
284 | ||
ff62dafe TL |
285 | |
286 | NOTE: Microsoft AD normally checks values like usernames without case | |
287 | sensitivity. To make {pve} do the same, you can disable the default | |
288 | `case-sensitive` option by editing the realm in the web UI, or using the CLI | |
289 | (change the `ID` with the realm ID): | |
290 | `pveum realm modify ID --case-sensitive 0` | |
291 | ||
78000a64 DW |
292 | [[pveum_ldap_sync]] |
293 | Syncing LDAP-Based Realms | |
294 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
295 | ||
296 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"] | |
297 | ||
298 | It's possible to automatically sync users and groups for LDAP-based realms (LDAP | |
299 | & Microsoft Active Directory), rather than having to add them to {pve} manually. | |
300 | You can access the sync options from the Add/Edit window of the web interface's | |
301 | `Authentication` panel or via the `pveum realm add/modify` commands. You can | |
302 | then carry out the sync operation from the `Authentication` panel of the GUI or | |
303 | using the following command: | |
304 | ||
305 | ---- | |
306 | pveum realm sync <realm> | |
307 | ---- | |
308 | ||
309 | Users and groups are synced to the cluster-wide configuration file, | |
310 | `/etc/pve/user.cfg`. | |
311 | ||
9c2fa0b5 TL |
312 | |
313 | Attributes to Properties | |
314 | ^^^^^^^^^^^^^^^^^^^^^^^^ | |
315 | ||
78881712 | 316 | If the sync response includes user attributes, they will be synced into the |
9c2fa0b5 TL |
317 | matching user property in the `user.cfg`. For example: `firstname` or |
318 | `lastname`. | |
319 | ||
320 | If the names of the attributes are not matching the {pve} properties, you can | |
321 | set a custom field-to-field map in the config by using the `sync_attributes` | |
78881712 | 322 | option. |
78000a64 | 323 | |
9c2fa0b5 TL |
324 | How such properties are handled if anything vanishes can be controlled via the |
325 | sync options, see below. | |
326 | ||
78000a64 DW |
327 | Sync Configuration |
328 | ^^^^^^^^^^^^^^^^^^ | |
329 | ||
330 | The configuration options for syncing LDAP-based realms can be found in the | |
331 | `Sync Options` tab of the Add/Edit window. | |
332 | ||
333 | The configuration options are as follows: | |
334 | ||
335 | * `Bind User` (`bind_dn`): Refers to the LDAP account used to query users | |
336 | and groups. This account needs access to all desired entries. If it's set, the | |
337 | search will be carried out via binding; otherwise, the search will be carried | |
338 | out anonymously. The user must be a complete LDAP formatted distinguished name | |
339 | (DN), for example, `cn=admin,dc=example,dc=com`. | |
340 | ||
341 | * Groupname attr. (group_name_attr): Represents the | |
342 | users' groups. Only entries which adhere to the usual character limitations of | |
343 | the `user.cfg` are synced. Groups are synced with `-$realm` attached to the | |
344 | name, in order to avoid naming conflicts. Please ensure that a sync does not | |
345 | overwrite manually created groups. | |
346 | ||
347 | * `User classes` (`user_classes`): Objects classes associated with users. | |
348 | ||
349 | * `Group classes` (`group_classes`): Objects classes associated with groups. | |
350 | ||
351 | * `E-Mail attribute`: If the LDAP-based server specifies user email addresses, | |
352 | these can also be included in the sync by setting the associated attribute | |
353 | here. From the command line, this is achievable through the | |
354 | `--sync_attributes` parameter. | |
355 | ||
356 | * `User Filter` (`filter`): For further filter options to target specific users. | |
357 | ||
358 | * `Group Filter` (`group_filter`): For further filter options to target specific | |
359 | groups. | |
360 | ||
361 | NOTE: Filters allow you to create a set of additional match criteria, to narrow | |
362 | down the scope of a sync. Information on available LDAP filter types and their | |
363 | usage can be found at https://ldap.com/ldap-filters/[ldap.com]. | |
364 | ||
78000a64 DW |
365 | [[pveum_ldap_sync_options]] |
366 | Sync Options | |
367 | ^^^^^^^^^^^^ | |
368 | ||
369 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"] | |
370 | ||
371 | In addition to the options specified in the previous section, you can also | |
372 | configure further options that describe the behavior of the sync operation. | |
373 | ||
374 | These options are either set as parameters before the sync, or as defaults via | |
375 | the realm option `sync-defaults-options`. | |
376 | ||
377 | The main options for syncing are: | |
378 | ||
379 | * `Scope` (`scope`): The scope of what to sync. It can be either `users`, | |
380 | `groups` or `both`. | |
381 | ||
382 | * `Enable new` (`enable-new`): If set, the newly synced users are enabled and | |
383 | can log in. The default is `true`. | |
384 | ||
217b2cae DC |
385 | * `Remove Vanished` (`remove-vanished`): This is a list of options which, when |
386 | activated, determine if they are removed when they are not returned from | |
387 | the sync response. The options are: | |
78000a64 | 388 | |
217b2cae DC |
389 | - `ACL` (`acl)`: Remove ACLs of users and groups which were not returned |
390 | returned in the sync response. This most often makes sense together with | |
391 | `Entry`. | |
392 | ||
393 | - `Entry` (`entry`): Removes entries (i.e. users and groups) when they are | |
394 | not returned in the sync response. | |
395 | ||
78881712 DC |
396 | - `Properties` (`properties`): Removes properties of entries where the user |
397 | in the sync response did not contain those attributes. This includes | |
398 | all properties, even those never set by a sync. Exceptions are tokens | |
399 | and the enable flag, these will be retained even with this option enabled. | |
78000a64 DW |
400 | |
401 | * `Preview` (`dry-run`): No data is written to the config. This is useful if you | |
402 | want to see which users and groups would get synced to the `user.cfg`. | |
f3ee27eb | 403 | |
89e5ecc9 CH |
404 | [[pveum_ldap_reserved_characters]] |
405 | Reserved characters | |
406 | ^^^^^^^^^^^^^^^^^^^ | |
407 | ||
62d3b564 DC |
408 | Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be |
409 | easily used in attribute values in DNs without being escaped properly. | |
89e5ecc9 CH |
410 | |
411 | Following characters need escaping: | |
412 | ||
fd95afe2 DC |
413 | * Space ( ) at the beginning or end |
414 | * Number sign (`#`) at the beginning | |
89e5ecc9 | 415 | * Comma (`,`) |
89e5ecc9 | 416 | * Plus sign (`+`) |
89e5ecc9 | 417 | * Double quote (`"`) |
89e5ecc9 | 418 | * Forward slashes (`/`) |
89e5ecc9 | 419 | * Angle brackets (`<>`) |
89e5ecc9 | 420 | * Semicolon (`;`) |
89e5ecc9 CH |
421 | * Equals sign (`=`) |
422 | ||
423 | To use such characters in DNs, surround the attribute value in double quotes. | |
424 | For example, to bind with a user with the CN (Common Name) `Example, User`, use | |
425 | `CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`. | |
426 | ||
427 | This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes. | |
428 | ||
429 | NOTE: Users with colons and forward slashes cannot be synced since these are | |
430 | reserved characters in usernames. | |
f3ee27eb DM |
431 | |
432 | [[pveum_openid]] | |
96942248 | 433 | OpenID Connect |
f3ee27eb DM |
434 | ~~~~~~~~~~~~~~ |
435 | ||
436 | The main OpenID Connect configuration options are: | |
437 | ||
78000a64 DW |
438 | * `Issuer URL` (`issuer-url`): This is the URL of the authorization server. |
439 | Proxmox uses the OpenID Connect Discovery protocol to automatically configure | |
f3ee27eb DM |
440 | further details. |
441 | + | |
96942248 | 442 | While it is possible to use unencrypted `http://` URLs, we strongly recommend to |
f3ee27eb DM |
443 | use encrypted `https://` connections. |
444 | ||
78000a64 | 445 | * `Realm` (`realm`): The realm identifier for {pve} users |
f3ee27eb | 446 | |
78000a64 | 447 | * `Client ID` (`client-id`): OpenID Client ID. |
f3ee27eb | 448 | |
78000a64 | 449 | * `Client Key` (`client-key`): Optional OpenID Client Key. |
f3ee27eb | 450 | |
78000a64 DW |
451 | * `Autocreate Users` (`autocreate`): Automatically create users if they do not |
452 | exist. While authentication is done at the OpenID server, all users still need | |
453 | an entry in the {pve} user configuration. You can either add them manually, or | |
454 | use the `autocreate` option to automatically add new users. | |
455 | ||
456 | * `Username Claim` (`username-claim`): OpenID claim used to generate the unique | |
457 | username (`subject`, `username` or `email`). | |
f3ee27eb DM |
458 | |
459 | Username mapping | |
460 | ^^^^^^^^^^^^^^^^ | |
461 | ||
96942248 DW |
462 | The OpenID Connect specification defines a single unique attribute |
463 | ('claim' in OpenID terms) named `subject`. By default, we use the | |
f3ee27eb DM |
464 | value of this attribute to generate {pve} usernames, by simple adding |
465 | `@` and the realm name: `${subject}@${realm}`. | |
466 | ||
96942248 | 467 | Unfortunately, most OpenID servers use random strings for `subject`, like |
f3ee27eb | 468 | `DGH76OKH34BNG3245SB`, so a typical username would look like |
96942248 | 469 | `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for |
f3ee27eb | 470 | humans to remember such random strings, making it quite impossible to |
96942248 | 471 | associate real users with this. |
f3ee27eb DM |
472 | |
473 | The `username-claim` setting allows you to use other attributes for | |
96942248 DW |
474 | the username mapping. Setting it to `username` is preferred if the |
475 | OpenID Connect server provides that attribute and guarantees its | |
f3ee27eb DM |
476 | uniqueness. |
477 | ||
96942248 | 478 | Another option is to use `email`, which also yields human readable |
62547dfa | 479 | usernames. Again, only use this setting if the server guarantees the |
f3ee27eb DM |
480 | uniqueness of this attribute. |
481 | ||
482 | Examples | |
483 | ^^^^^^^^ | |
484 | ||
96942248 | 485 | Here is an example of creating an OpenID realm using Google. You need to |
f3ee27eb | 486 | replace `--client-id` and `--client-key` with the values |
96942248 | 487 | from your Google OpenID settings. |
f3ee27eb DM |
488 | |
489 | ---- | |
490 | pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email | |
491 | ---- | |
492 | ||
96942248 DW |
493 | The above command uses `--username-claim email`, so that the usernames on the |
494 | {pve} side look like `example.user@google.com@myrealm1`. | |
f3ee27eb | 495 | |
96942248 DW |
496 | Keycloak (https://www.keycloak.org/) is a popular open source Identity |
497 | and Access Management tool, which supports OpenID Connect. In the following | |
f3ee27eb | 498 | example, you need to replace the `--issuer-url` and `--client-id` with |
96942248 | 499 | your information: |
f3ee27eb DM |
500 | |
501 | ---- | |
fd174571 | 502 | pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username |
f3ee27eb DM |
503 | ---- |
504 | ||
96942248 | 505 | Using `--username-claim username` enables simple usernames on the |
f3ee27eb DM |
506 | {pve} side, like `example.user@myrealm2`. |
507 | ||
96942248 DW |
508 | WARNING: You need to ensure that the user is not allowed to edit |
509 | the username setting themselves (on the Keycloak server). | |
f3ee27eb DM |
510 | |
511 | ||
0523992b | 512 | [[pveum_tfa_auth]] |
96942248 | 513 | Two-Factor Authentication |
9e8f2770 WB |
514 | ------------------------- |
515 | ||
74662f51 | 516 | There are two ways to use two-factor authentication: |
2837cf1d | 517 | |
74662f51 | 518 | It can be required by the authentication realm, either via 'TOTP' |
96942248 DW |
519 | (Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly |
520 | created user needs to have their keys added immediately, as there is no way to | |
74662f51 OB |
521 | log in without the second factor. In the case of 'TOTP', users can |
522 | also change the 'TOTP' later on, provided they can log in first. | |
2837cf1d | 523 | |
96942248 | 524 | Alternatively, users can choose to opt-in to two-factor authentication |
1245cebe WB |
525 | later on, even if the realm does not enforce it. |
526 | ||
527 | Available Second Factors | |
528 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
529 | ||
530 | You can set up multiple second factors, in order to avoid a situation in | |
531 | which losing your smartphone or security key locks you out of your | |
532 | account permanently. | |
533 | ||
534 | The following two-factor authentication methods are available in | |
535 | addition to realm-enforced TOTP and YubiKey OTP: | |
536 | ||
537 | * User configured TOTP | |
538 | (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]). | |
539 | A short code derived from a shared secret and the current time, it changes | |
540 | every 30 seconds. | |
541 | * WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]). | |
542 | A general standard for authentication. It is implemented by various | |
543 | security devices, like hardware keys or trusted platform modules (TPM) | |
544 | from a computer or smart phone. | |
545 | * Single use Recovery Keys. A list of keys which should either be | |
546 | printed out and locked in a secure place or saved digitally in an | |
547 | electronic vault. Each key can be used only once. These are perfect for | |
548 | ensuring that you are not locked out, even if all of your other second | |
549 | factors are lost or corrupt. | |
550 | ||
551 | Before WebAuthn was supported, U2F could be setup by the user. Existing | |
552 | U2F factors can still be used, but it is recommended to switch to | |
553 | WebAuthn, once it is configured on the server. | |
2837cf1d | 554 | |
96942248 | 555 | Realm Enforced Two-Factor Authentication |
2837cf1d WB |
556 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
557 | ||
74662f51 OB |
558 | This can be done by selecting one of the available methods via the |
559 | 'TFA' dropdown box when adding or editing an Authentication Realm. | |
96942248 DW |
560 | When a realm has TFA enabled, it becomes a requirement, and only users |
561 | with configured TFA will be able to log in. | |
9e8f2770 WB |
562 | |
563 | Currently there are two methods available: | |
564 | ||
96942248 | 565 | Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm, |
74662f51 | 566 | where the current time is hashed with the user's configured key. The |
96942248 | 567 | time step and password length parameters are configurable. |
9e8f2770 | 568 | + |
74662f51 OB |
569 | A user can have multiple keys configured (separated by spaces), and the keys |
570 | can be specified in Base32 (RFC3548) or hexadecimal notation. | |
9e8f2770 | 571 | + |
74662f51 | 572 | {pve} provides a key generation tool (`oathkeygen`) which prints out a random |
96942248 | 573 | key in Base32 notation, that can be used directly with various OTP tools, such |
ff4ae052 | 574 | as the `oathtool` command-line tool, or on Android Google Authenticator, |
74662f51 | 575 | FreeOTP, andOTP or similar applications. |
9e8f2770 WB |
576 | |
577 | YubiKey OTP:: | |
578 | For authenticating via a YubiKey a Yubico API ID, API KEY and validation | |
579 | server URL must be configured, and users must have a YubiKey available. In | |
580 | order to get the key ID from a YubiKey, you can trigger the YubiKey once | |
96942248 | 581 | after connecting it via USB, and copy the first 12 characters of the typed |
9e8f2770 | 582 | password into the user's 'Key IDs' field. |
74662f51 | 583 | |
74662f51 OB |
584 | Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP] |
585 | documentation for how to use the | |
9e8f2770 | 586 | https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or |
96942248 | 587 | https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server]. |
9e8f2770 | 588 | |
96a0d131 | 589 | [[pveum_tfa_lockout]] |
e253a787 | 590 | Limits and Lockout of Two-Factor Authentication |
96a0d131 WB |
591 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
592 | ||
593 | A second factor is meant to protect users if their password is somehow leaked | |
594 | or guessed. However, some factors could still be broken by brute force. For | |
595 | this reason, users will be locked out after too many failed 2nd factor login | |
596 | attempts. | |
597 | ||
e253a787 | 598 | For TOTP, 8 failed attempts will disable the user's TOTP factors. They are |
96a0d131 WB |
599 | unlocked when logging in with a recovery key. If TOTP was the only available |
600 | factor, admin intervention is required, and it is highly recommended to require | |
601 | the user to change their password immediately. | |
602 | ||
603 | Since FIDO2/Webauthn and recovery keys are less susceptible to brute force | |
e253a787 TL |
604 | attacks, the limit there is higher (100 tries), but all second factors are |
605 | blocked for an hour when exceeded. | |
96a0d131 WB |
606 | |
607 | An admin can unlock a user's Two-Factor Authentication at any time via the user | |
608 | list in the UI or the command line: | |
609 | ||
610 | [source,bash] | |
e712afa6 | 611 | ---- |
96a0d131 | 612 | pveum user tfa unlock joe@pve |
e712afa6 | 613 | ---- |
96a0d131 | 614 | |
0523992b | 615 | [[pveum_user_configured_totp]] |
96942248 | 616 | User Configured TOTP Authentication |
2837cf1d WB |
617 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
618 | ||
1245cebe WB |
619 | Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login, via |
620 | the 'TFA' button in the user list (unless the realm enforces 'YubiKey OTP'). | |
2837cf1d | 621 | |
1245cebe WB |
622 | Users can always add and use one time 'Recovery Keys'. |
623 | ||
624 | [thumbnail="screenshot/gui-datacenter-two-factor.png"] | |
2b59fcfb | 625 | |
96942248 DW |
626 | After opening the 'TFA' window, the user is presented with a dialog to set up |
627 | 'TOTP' authentication. The 'Secret' field contains the key, which can be | |
628 | randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be | |
629 | added to provide information to the 'TOTP' app about what the key belongs to. | |
2837cf1d | 630 | Most 'TOTP' apps will show the issuer name together with the corresponding |
96942248 | 631 | 'OTP' values. The username is also included in the QR code for the 'TOTP' app. |
2837cf1d | 632 | |
96942248 DW |
633 | After generating a key, a QR code will be displayed, which can be used with most |
634 | OTP apps such as FreeOTP. The user then needs to verify the current user | |
2837cf1d | 635 | password (unless logged in as 'root'), as well as the ability to correctly use |
96942248 DW |
636 | the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code' |
637 | field and pressing the 'Apply' button. | |
2837cf1d | 638 | |
1245cebe WB |
639 | [[user_tfa_setup_totp]] |
640 | === TOTP | |
641 | ||
642 | [thumbnail="screenshot/pve-gui-tfa-add-totp.png"] | |
643 | ||
644 | There is no server setup required. Simply install a TOTP app on your | |
645 | smartphone (for example, https://freeotp.github.io/[FreeOTP]) and use | |
646 | the Proxmox Backup Server web-interface to add a TOTP factor. | |
647 | ||
648 | [[user_tfa_setup_webauthn]] | |
649 | === WebAuthn | |
650 | ||
651 | For WebAuthn to work, you need to have two things: | |
652 | ||
653 | * A trusted HTTPS certificate (for example, by using | |
654 | https://pve.proxmox.com/wiki/Certificate_Management[Let's Encrypt]). | |
655 | While it probably works with an untrusted certificate, some browsers may | |
656 | warn or refuse WebAuthn operations if it is not trusted. | |
657 | * Setup the WebAuthn configuration (see *Datacenter -> Options -> | |
658 | WebAuthn Settings* in the Proxmox VE web interface). This can be | |
659 | auto-filled in most setups. | |
660 | ||
661 | Once you have fulfilled both of these requirements, you can add a WebAuthn | |
662 | configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two | |
663 | Factor*. | |
664 | ||
665 | [[user_tfa_setup_recovery_keys]] | |
666 | === Recovery Keys | |
667 | ||
668 | [thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"] | |
669 | ||
670 | Recovery key codes do not need any preparation; you can simply create a | |
671 | set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions | |
672 | -> Two Factor*. | |
673 | ||
674 | NOTE: There can only be one set of single-use recovery keys per user at any | |
675 | time. | |
676 | ||
677 | ||
e455949b | 678 | [[pveum_configure_webauthn]] |
1245cebe WB |
679 | Server Side Webauthn Configuration |
680 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
681 | ||
682 | [thumbnail="screenshot/gui-datacenter-webauthn-edit.png"] | |
683 | ||
684 | To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid | |
685 | domain with a valid SSL certificate, otherwise some browsers may warn or refuse | |
686 | to authenticate altogether. | |
687 | ||
688 | NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn' | |
689 | registrations unusable! | |
690 | ||
691 | This is done via `/etc/pve/datacenter.cfg`. For instance: | |
692 | ||
693 | ---- | |
5d993771 | 694 | webauthn: rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com |
1245cebe WB |
695 | ---- |
696 | ||
97d63abc | 697 | [[pveum_configure_u2f]] |
96942248 | 698 | Server Side U2F Configuration |
2837cf1d WB |
699 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
700 | ||
1245cebe WB |
701 | NOTE: It is recommended to use WebAuthn instead. |
702 | ||
58df830b | 703 | To allow users to use 'U2F' authentication, it may be necessary to use a valid |
96942248 DW |
704 | domain with a valid SSL certificate, otherwise, some browsers may print |
705 | a warning or reject U2F usage altogether. Initially, an 'AppId' | |
2837cf1d WB |
706 | footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] |
707 | needs to be configured. | |
708 | ||
709 | NOTE: Changing the 'AppId' will render all existing 'U2F' registrations | |
710 | unusable! | |
711 | ||
96942248 | 712 | This is done via `/etc/pve/datacenter.cfg`. For instance: |
2837cf1d WB |
713 | |
714 | ---- | |
715 | u2f: appid=https://mypve.example.com:8006 | |
716 | ---- | |
717 | ||
96942248 DW |
718 | For a single node, the 'AppId' can simply be the address of the web-interface, |
719 | exactly as it is used in the browser, including the 'https://' and the port, as | |
720 | shown above. Please note that some browsers may be more strict than others when | |
721 | matching 'AppIds'. | |
2837cf1d WB |
722 | |
723 | When using multiple nodes, it is best to have a separate `https` server | |
724 | providing an `appid.json` | |
725 | footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html] | |
726 | file, as it seems to be compatible with most | |
727 | browsers. If all nodes use subdomains of the same top level domain, it may be | |
96942248 DW |
728 | enough to use the TLD as 'AppId'. It should however be noted that some browsers |
729 | may not accept this. | |
2837cf1d WB |
730 | |
731 | NOTE: A bad 'AppId' will usually produce an error, but we have encountered | |
96942248 DW |
732 | situations when this does not happen, particularly when using a top level domain |
733 | 'AppId' for a node that is accessed via a subdomain in Chromium. For this reason | |
734 | it is recommended to test the configuration with multiple browsers, as changing | |
735 | the 'AppId' later will render existing 'U2F' registrations unusable. | |
2837cf1d | 736 | |
0523992b | 737 | [[pveum_user_configured_u2f]] |
96942248 | 738 | Activating U2F as a User |
2837cf1d WB |
739 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
740 | ||
741 | To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the | |
742 | current password (unless logged in as root), and press the 'Register' button. | |
96942248 | 743 | If the server is set up correctly and the browser accepts the server's provided |
2837cf1d | 744 | 'AppId', a message will appear prompting the user to press the button on the |
96942248 DW |
745 | 'U2F' device (if it is a 'YubiKey', the button light should be toggling on and |
746 | off steadily, roughly twice per second). | |
2837cf1d WB |
747 | |
748 | Firefox users may need to enable 'security.webauth.u2f' via 'about:config' | |
749 | before they can use a 'U2F' token. | |
9e8f2770 | 750 | |
80c0adcb | 751 | [[pveum_permission_management]] |
04f44730 | 752 | Permission Management |
3c8533f2 DM |
753 | --------------------- |
754 | ||
04f44730 | 755 | In order for a user to perform an action (such as listing, modifying or |
96942248 | 756 | deleting parts of a VM's configuration), the user needs to have the |
04f44730 WB |
757 | appropriate permissions. |
758 | ||
759 | {pve} uses a role and path based permission management system. An entry in | |
181db098 | 760 | the permissions table allows a user, group or token to take on a specific role |
96942248 | 761 | when accessing an 'object' or 'path'. This means that such an access rule can |
181db098 FG |
762 | be represented as a triple of '(path, user, role)', '(path, group, |
763 | role)' or '(path, token, role)', with the role containing a set of allowed | |
764 | actions, and the path representing the target of these actions. | |
04f44730 | 765 | |
5eba0743 | 766 | |
80c0adcb | 767 | [[pveum_roles]] |
853d288b WB |
768 | Roles |
769 | ~~~~~ | |
770 | ||
771 | A role is simply a list of privileges. Proxmox VE comes with a number | |
96942248 | 772 | of predefined roles, which satisfy most requirements. |
853d288b | 773 | |
96942248 | 774 | * `Administrator`: has full privileges |
853d288b | 775 | * `NoAccess`: has no privileges (used to forbid access) |
3c67d559 FG |
776 | * `PVEAdmin`: can do most tasks, but has no rights to modify system settings |
777 | (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`) or permissions | |
778 | (`Permissions.Modify`) | |
96942248 | 779 | * `PVEAuditor`: has read only access |
853d288b WB |
780 | * `PVEDatastoreAdmin`: create and allocate backup space and templates |
781 | * `PVEDatastoreUser`: allocate backup space and view storage | |
19934c36 MC |
782 | * `PVEMappingAdmin`: manage resource mappings |
783 | * `PVEMappingUser`: view and use resource mappings | |
853d288b | 784 | * `PVEPoolAdmin`: allocate pools |
19934c36 | 785 | * `PVEPoolUser`: view pools |
af79dcc5 MC |
786 | * `PVESDNAdmin`: manage SDN configuration |
787 | * `PVESDNUser`: access to bridges/vnets | |
3c67d559 | 788 | * `PVESysAdmin`: audit, system console and system logs |
853d288b | 789 | * `PVETemplateUser`: view and clone templates |
96942248 | 790 | * `PVEUserAdmin`: manage users |
853d288b | 791 | * `PVEVMAdmin`: fully administer VMs |
96942248 | 792 | * `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management |
853d288b | 793 | |
96942248 | 794 | You can see the whole set of predefined roles in the GUI. |
853d288b | 795 | |
96942248 | 796 | You can add new roles via the GUI or the command line. |
5e6b02ff TL |
797 | |
798 | [thumbnail="screenshot/gui-datacenter-role-add.png"] | |
96942248 DW |
799 | From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and |
800 | click on the 'Create' button. There you can set a role name and select any | |
801 | desired privileges from the 'Privileges' drop-down menu. | |
853d288b | 802 | |
96942248 DW |
803 | To add a role through the command line, you can use the 'pveum' CLI tool, for |
804 | example: | |
853d288b WB |
805 | [source,bash] |
806 | ---- | |
3c67d559 | 807 | pveum role add VM_Power-only --privs "VM.PowerMgmt VM.Console" |
96942248 | 808 | pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console" |
853d288b WB |
809 | ---- |
810 | ||
3c67d559 FG |
811 | NOTE: Roles starting with `PVE` are always builtin, custom roles are not |
812 | allowed use this reserved prefix. | |
853d288b | 813 | |
3c8533f2 DM |
814 | Privileges |
815 | ~~~~~~~~~~ | |
816 | ||
817 | A privilege is the right to perform a specific action. To simplify | |
818 | management, lists of privileges are grouped into roles, which can then | |
96942248 | 819 | be used in the permission table. Note that privileges cannot be directly |
0e1fda70 | 820 | assigned to users and paths without being part of a role. |
3c8533f2 | 821 | |
96942248 | 822 | We currently support the following privileges: |
3c8533f2 DM |
823 | |
824 | Node / System related privileges:: | |
825 | ||
96942248 | 826 | * `Group.Allocate`: create/modify/remove groups |
af79dcc5 MC |
827 | * `Mapping.Audit`: view resource mappings |
828 | * `Mapping.Modify`: manage resource mappings | |
829 | * `Mapping.Use`: use resource mappings | |
830 | * `Permissions.Modify`: modify access permissions | |
96942248 | 831 | * `Pool.Allocate`: create/modify/remove a pool |
696ebb3c | 832 | * `Pool.Audit`: view a pool |
3c8533f2 | 833 | * `Realm.AllocateUser`: assign user to a realm |
af79dcc5 | 834 | * `Realm.Allocate`: create/modify/remove authentication realms |
3c67d559 FG |
835 | * `SDN.Allocate`: manage SDN configuration |
836 | * `SDN.Audit`: view SDN configuration | |
af79dcc5 MC |
837 | * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config |
838 | * `Sys.Console`: console access to node | |
839 | * `Sys.Incoming`: allow incoming data streams from other clusters (experimental) | |
840 | * `Sys.Modify`: create/modify/remove node network parameters | |
841 | * `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...) | |
842 | * `Sys.Syslog`: view syslog | |
843 | * `User.Modify`: create/modify/remove user access and details. | |
3c8533f2 DM |
844 | |
845 | Virtual machine related privileges:: | |
846 | ||
af79dcc5 | 847 | * `SDN.Use`: access SDN vnets and local network bridges |
96942248 | 848 | * `VM.Allocate`: create/remove VM on a server |
3c8533f2 | 849 | * `VM.Audit`: view VM config |
af79dcc5 | 850 | * `VM.Backup`: backup/restore VMs |
3c8533f2 | 851 | * `VM.Clone`: clone/copy a VM |
3a433e9b | 852 | * `VM.Config.CDROM`: eject/change CD-ROM |
3c8533f2 | 853 | * `VM.Config.CPU`: modify CPU settings |
af79dcc5 MC |
854 | * `VM.Config.Cloudinit`: modify Cloud-init parameters |
855 | * `VM.Config.Disk`: add/modify/remove disks | |
856 | * `VM.Config.HWType`: modify emulated hardware types | |
96942248 DW |
857 | * `VM.Config.Memory`: modify memory settings |
858 | * `VM.Config.Network`: add/modify/remove network devices | |
3c8533f2 | 859 | * `VM.Config.Options`: modify any other VM configuration |
af79dcc5 MC |
860 | * `VM.Console`: console access to VM |
861 | * `VM.Migrate`: migrate VM to alternate server on cluster | |
862 | * `VM.Monitor`: access to VM monitor (kvm) | |
863 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
19934c36 | 864 | * `VM.Snapshot.Rollback`: rollback VM to one of its snapshots |
af79dcc5 | 865 | * `VM.Snapshot`: create/delete VM snapshots |
3c8533f2 DM |
866 | |
867 | Storage related privileges:: | |
868 | ||
96942248 | 869 | * `Datastore.Allocate`: create/modify/remove a datastore and delete volumes |
3c8533f2 | 870 | * `Datastore.AllocateSpace`: allocate space on a datastore |
96942248 | 871 | * `Datastore.AllocateTemplate`: allocate/upload templates and ISO images |
3c8533f2 DM |
872 | * `Datastore.Audit`: view/browse a datastore |
873 | ||
3c67d559 FG |
874 | WARNING: Both `Permissions.Modify` and `Sys.Modify` should be handled with |
875 | care, as they allow modifying aspects of the system and its configuration that | |
876 | are dangerous or sensitive. | |
877 | ||
878 | WARNING: Carefully read the section about inheritance below to understand how | |
879 | assigned roles (and their privileges) are propagated along the ACL tree. | |
5eba0743 | 880 | |
b8eeec52 WB |
881 | Objects and Paths |
882 | ~~~~~~~~~~~~~~~~~ | |
883 | ||
96942248 DW |
884 | Access permissions are assigned to objects, such as virtual machines, |
885 | storages or resource pools. | |
b8eeec52 | 886 | We use file system like paths to address these objects. These paths form a |
96942248 | 887 | natural tree, and permissions of higher levels (shorter paths) can |
b8eeec52 WB |
888 | optionally be propagated down within this hierarchy. |
889 | ||
7d48940b | 890 | [[pveum_templated_paths]] |
b8eeec52 WB |
891 | Paths can be templated. When an API call requires permissions on a |
892 | templated path, the path may contain references to parameters of the API | |
893 | call. These references are specified in curly braces. Some parameters are | |
96942248 | 894 | implicitly taken from the API call's URI. For instance, the permission path |
b8eeec52 WB |
895 | `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on |
896 | `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` | |
897 | refers to the method's `path` parameter. | |
898 | ||
899 | Some examples are: | |
900 | ||
901 | * `/nodes/{node}`: Access to {pve} server machines | |
902 | * `/vms`: Covers all VMs | |
903 | * `/vms/{vmid}`: Access to specific VMs | |
96942248 DW |
904 | * `/storage/{storeid}`: Access to a specific storage |
905 | * `/pool/{poolname}`: Access to resources contained in a specific <<pveum_pools,pool>> | |
b8eeec52 WB |
906 | * `/access/groups`: Group administration |
907 | * `/access/realms/{realmid}`: Administrative access to realms | |
908 | ||
909 | ||
3c8533f2 DM |
910 | Inheritance |
911 | ^^^^^^^^^^^ | |
912 | ||
5eba0743 | 913 | As mentioned earlier, object paths form a file system like tree, and |
96942248 DW |
914 | permissions can be inherited by objects down that tree (the propagate flag is |
915 | set by default). We use the following inheritance rules: | |
3c8533f2 | 916 | |
74936daf WB |
917 | * Permissions for individual users always replace group permissions. |
918 | * Permissions for groups apply when the user is member of that group. | |
96942248 | 919 | * Permissions on deeper levels replace those inherited from an upper level. |
3c67d559 | 920 | * `NoAccess` cancels all other roles on a given path. |
3c8533f2 | 921 | |
96942248 | 922 | Additionally, privilege separated tokens can never have permissions on any |
181db098 | 923 | given path that their associated user does not have. |
5eba0743 | 924 | |
80c0adcb | 925 | [[pveum_pools]] |
3c8533f2 DM |
926 | Pools |
927 | ~~~~~ | |
928 | ||
96942248 DW |
929 | Pools can be used to group a set of virtual machines and datastores. You can |
930 | then simply set permissions on pools (`/pool/{poolid}`), which are inherited by | |
931 | all pool members. This is a great way to simplify access control. | |
3c8533f2 | 932 | |
74936daf | 933 | |
96942248 DW |
934 | Which Permissions Do I Need? |
935 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
74936daf WB |
936 | |
937 | The required API permissions are documented for each individual | |
96942248 | 938 | method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/. |
74936daf | 939 | |
96942248 | 940 | The permissions are specified as a list, which can be interpreted as a |
74936daf WB |
941 | tree of logic and access-check functions: |
942 | ||
943 | `["and", <subtests>...]` and `["or", <subtests>...]`:: | |
944 | Each(`and`) or any(`or`) further element in the current list has to be true. | |
945 | ||
946 | `["perm", <path>, [ <privileges>... ], <options>...]`:: | |
7d48940b | 947 | The `path` is a templated parameter (see |
87ba80b0 | 948 | <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any` |
7d48940b | 949 | option is used, any) of the listed |
74936daf WB |
950 | privileges must be allowed on the specified path. If a `require-param` |
951 | option is specified, then its specified parameter is required even if the | |
952 | API call's schema otherwise lists it as being optional. | |
953 | ||
954 | `["userid-group", [ <privileges>... ], <options>...]`:: | |
470d4313 | 955 | The caller must have any of the listed privileges on `/access/groups`. In |
96942248 | 956 | addition, there are two possible checks, depending on whether the |
74936daf WB |
957 | `groups_param` option is set: |
958 | + | |
959 | * `groups_param` is set: The API call has a non-optional `groups` parameter | |
960 | and the caller must have any of the listed privileges on all of the listed | |
961 | groups. | |
962 | * `groups_param` is not set: The user passed via the `userid` parameter | |
963 | must exist and be part of a group on which the caller has any of the listed | |
964 | privileges (via the `/access/groups/<group>` path). | |
965 | ||
966 | `["userid-param", "self"]`:: | |
967 | The value provided for the API call's `userid` parameter must refer to the | |
96942248 DW |
968 | user performing the action (usually in conjunction with `or`, to allow |
969 | users to perform an action on themselves, even if they don't have elevated | |
970 | privileges). | |
74936daf WB |
971 | |
972 | `["userid-param", "Realm.AllocateUser"]`:: | |
973 | The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with | |
470d4313 | 974 | `<realm>` referring to the realm of the user passed via the `userid` |
74936daf WB |
975 | parameter. Note that the user does not need to exist in order to be |
976 | associated with a realm, since user IDs are passed in the form of | |
977 | `<username>@<realm>`. | |
978 | ||
979 | `["perm-modify", <path>]`:: | |
7d48940b DM |
980 | The `path` is a templated parameter (see |
981 | <<pveum_templated_paths,Objects and Paths>>). The user needs either the | |
96942248 | 982 | `Permissions.Modify` privilege or, |
74936daf WB |
983 | depending on the path, the following privileges as a possible substitute: |
984 | + | |
7816b93a LW |
985 | * `/storage/...`: requires 'Datastore.Allocate` |
986 | * `/vms/...`: requires 'VM.Allocate` | |
987 | * `/pool/...`: requires 'Pool.Allocate` | |
74936daf | 988 | + |
3c67d559 FG |
989 | If the path is empty, `Permissions.Modify` on `/access` is required. |
990 | + | |
991 | If the user does not have the `Permissions.Modify` privilege, they can only | |
992 | delegate subsets of their own privileges on the given path (e.g., a user with | |
993 | `PVEVMAdmin` could assign `PVEVMUser`, but not `PVEAdmin`). | |
74936daf | 994 | |
ff4ae052 | 995 | Command-line Tool |
3c8533f2 DM |
996 | ----------------- |
997 | ||
998 | Most users will simply use the GUI to manage users. But there is also | |
ff4ae052 NU |
999 | a fully featured command-line tool called `pveum` (short for ``**P**roxmox |
1000 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command-line | |
1001 | tools are wrappers around the API, so you can also access those | |
87ba80b0 | 1002 | functions through the REST API. |
3c8533f2 | 1003 | |
96942248 | 1004 | Here are some simple usage examples. To show help, type: |
3c8533f2 DM |
1005 | |
1006 | [source,bash] | |
e712afa6 | 1007 | ---- |
3c8533f2 | 1008 | pveum |
e712afa6 | 1009 | ---- |
3c8533f2 DM |
1010 | |
1011 | or (to show detailed help about a specific command) | |
1012 | ||
1013 | [source,bash] | |
e712afa6 | 1014 | ---- |
9135e321 | 1015 | pveum help user add |
e712afa6 | 1016 | ---- |
3c8533f2 DM |
1017 | |
1018 | Create a new user: | |
1019 | ||
1020 | [source,bash] | |
e712afa6 | 1021 | ---- |
9135e321 | 1022 | pveum user add testuser@pve -comment "Just a test" |
e712afa6 | 1023 | ---- |
3c8533f2 | 1024 | |
96942248 | 1025 | Set or change the password (not all realms support this): |
3c8533f2 DM |
1026 | |
1027 | [source,bash] | |
e712afa6 | 1028 | ---- |
3c8533f2 | 1029 | pveum passwd testuser@pve |
e712afa6 | 1030 | ---- |
3c8533f2 DM |
1031 | |
1032 | Disable a user: | |
1033 | ||
1034 | [source,bash] | |
e712afa6 | 1035 | ---- |
9135e321 | 1036 | pveum user modify testuser@pve -enable 0 |
e712afa6 | 1037 | ---- |
3c8533f2 DM |
1038 | |
1039 | Create a new group: | |
1040 | ||
1041 | [source,bash] | |
e712afa6 | 1042 | ---- |
9135e321 | 1043 | pveum group add testgroup |
e712afa6 | 1044 | ---- |
3c8533f2 DM |
1045 | |
1046 | Create a new role: | |
1047 | ||
1048 | [source,bash] | |
e712afa6 | 1049 | ---- |
9135e321 | 1050 | pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console" |
e712afa6 | 1051 | ---- |
3c8533f2 DM |
1052 | |
1053 | ||
1054 | Real World Examples | |
1055 | ------------------- | |
1056 | ||
5eba0743 | 1057 | |
3c8533f2 DM |
1058 | Administrator Group |
1059 | ~~~~~~~~~~~~~~~~~~~ | |
1060 | ||
96942248 DW |
1061 | It is possible that an administrator would want to create a group of users with |
1062 | full administrator rights (without using the root account). | |
3c8533f2 | 1063 | |
96942248 | 1064 | To do this, first define the group: |
3c8533f2 DM |
1065 | |
1066 | [source,bash] | |
e712afa6 | 1067 | ---- |
9135e321 | 1068 | pveum group add admin -comment "System Administrators" |
e712afa6 | 1069 | ---- |
3c8533f2 | 1070 | |
96942248 | 1071 | Then assign the role: |
3c8533f2 DM |
1072 | |
1073 | [source,bash] | |
e712afa6 | 1074 | ---- |
9135e321 | 1075 | pveum acl modify / -group admin -role Administrator |
e712afa6 | 1076 | ---- |
3c8533f2 | 1077 | |
96942248 | 1078 | Finally, you can add users to the new 'admin' group: |
3c8533f2 DM |
1079 | |
1080 | [source,bash] | |
e712afa6 | 1081 | ---- |
9135e321 | 1082 | pveum user modify testuser@pve -group admin |
e712afa6 | 1083 | ---- |
3c8533f2 DM |
1084 | |
1085 | ||
1086 | Auditors | |
1087 | ~~~~~~~~ | |
1088 | ||
1089 | You can give read only access to users by assigning the `PVEAuditor` | |
1090 | role to users or groups. | |
1091 | ||
96942248 | 1092 | Example 1: Allow user `joe@pve` to see everything |
3c8533f2 DM |
1093 | |
1094 | [source,bash] | |
e712afa6 | 1095 | ---- |
9135e321 | 1096 | pveum acl modify / -user joe@pve -role PVEAuditor |
e712afa6 | 1097 | ---- |
3c8533f2 | 1098 | |
96942248 | 1099 | Example 2: Allow user `joe@pve` to see all virtual machines |
3c8533f2 DM |
1100 | |
1101 | [source,bash] | |
e712afa6 | 1102 | ---- |
9135e321 | 1103 | pveum acl modify /vms -user joe@pve -role PVEAuditor |
e712afa6 | 1104 | ---- |
3c8533f2 | 1105 | |
5eba0743 | 1106 | |
3c8533f2 DM |
1107 | Delegate User Management |
1108 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
1109 | ||
96942248 | 1110 | If you want to delegate user management to user `joe@pve`, you can do |
3c8533f2 DM |
1111 | that with: |
1112 | ||
1113 | [source,bash] | |
e712afa6 | 1114 | ---- |
9135e321 | 1115 | pveum acl modify /access -user joe@pve -role PVEUserAdmin |
e712afa6 | 1116 | ---- |
3c8533f2 | 1117 | |
96942248 DW |
1118 | User `joe@pve` can now add and remove users, and change other user attributes, |
1119 | such as passwords. This is a very powerful role, and you most | |
1120 | likely want to limit it to selected realms and groups. The following | |
1121 | example allows `joe@pve` to modify users within the realm `pve`, if they | |
8c1189b6 | 1122 | are members of group `customers`: |
3c8533f2 DM |
1123 | |
1124 | [source,bash] | |
e712afa6 | 1125 | ---- |
9135e321 TL |
1126 | pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin |
1127 | pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin | |
e712afa6 | 1128 | ---- |
3c8533f2 | 1129 | |
0abc65b0 | 1130 | NOTE: The user is able to add other users, but only if they are |
96942248 | 1131 | members of the group `customers` and within the realm `pve`. |
8c1189b6 | 1132 | |
96942248 | 1133 | Limited API Token for Monitoring |
181db098 FG |
1134 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
1135 | ||
a13a971d DW |
1136 | Permissions on API tokens are always a subset of those of their corresponding |
1137 | user, meaning that an API token can't be used to carry out a task that the | |
1138 | backing user has no permission to do. This section will demonstrate how you can | |
1139 | use an API token with separate privileges, to limit the token owner's | |
1140 | permissions further. | |
1141 | ||
1142 | Give the user `joe@pve` the role PVEVMAdmin on all VMs: | |
181db098 FG |
1143 | |
1144 | [source,bash] | |
e712afa6 | 1145 | ---- |
9135e321 | 1146 | pveum acl modify /vms -user joe@pve -role PVEVMAdmin |
e712afa6 | 1147 | ---- |
181db098 FG |
1148 | |
1149 | Add a new API token with separate privileges, which is only allowed to view VM | |
96942248 | 1150 | information (for example, for monitoring purposes): |
181db098 FG |
1151 | |
1152 | [source,bash] | |
e712afa6 | 1153 | ---- |
181db098 | 1154 | pveum user token add joe@pve monitoring -privsep 1 |
9135e321 | 1155 | pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor |
e712afa6 | 1156 | ---- |
181db098 FG |
1157 | |
1158 | Verify the permissions of the user and token: | |
1159 | ||
1160 | [source,bash] | |
e712afa6 | 1161 | ---- |
181db098 FG |
1162 | pveum user permissions joe@pve |
1163 | pveum user token permissions joe@pve monitoring | |
e712afa6 | 1164 | ---- |
3c8533f2 | 1165 | |
23b447be DW |
1166 | Resource Pools |
1167 | ~~~~~~~~~~~~~~ | |
3c8533f2 | 1168 | |
23b447be DW |
1169 | An enterprise is usually structured into several smaller departments, and it is |
1170 | common that you want to assign resources and delegate management tasks to each | |
1171 | of these. Let's assume that you want to set up a pool for a software development | |
96942248 | 1172 | department. First, create a group: |
3c8533f2 DM |
1173 | |
1174 | [source,bash] | |
e712afa6 | 1175 | ---- |
9135e321 | 1176 | pveum group add developers -comment "Our software developers" |
e712afa6 | 1177 | ---- |
3c8533f2 | 1178 | |
96942248 | 1179 | Now we create a new user which is a member of that group: |
3c8533f2 DM |
1180 | |
1181 | [source,bash] | |
e712afa6 | 1182 | ---- |
9135e321 | 1183 | pveum user add developer1@pve -group developers -password |
e712afa6 | 1184 | ---- |
3c8533f2 | 1185 | |
96942248 | 1186 | NOTE: The "-password" parameter will prompt you for a password |
3c8533f2 | 1187 | |
96942248 | 1188 | Then we create a resource pool for our development department to use: |
23b447be DW |
1189 | |
1190 | [source,bash] | |
e712afa6 | 1191 | ---- |
9135e321 | 1192 | pveum pool add dev-pool --comment "IT development pool" |
e712afa6 | 1193 | ---- |
23b447be | 1194 | |
96942248 | 1195 | Finally, we can assign permissions to that pool: |
3c8533f2 DM |
1196 | |
1197 | [source,bash] | |
e712afa6 | 1198 | ---- |
9135e321 | 1199 | pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin |
e712afa6 | 1200 | ---- |
3c8533f2 | 1201 | |
96942248 | 1202 | Our software developers can now administer the resources assigned to |
3c8533f2 DM |
1203 | that pool. |
1204 | ||
1205 | ||
1206 | ifdef::manvolnum[] | |
1207 | include::pve-copyright.adoc[] | |
1208 | endif::manvolnum[] | |
1209 |