]>
Commit | Line | Data |
---|---|---|
80c0adcb | 1 | [[chapter_user_management]] |
3c8533f2 | 2 | ifdef::manvolnum[] |
b2f242ab DM |
3 | pveum(1) |
4 | ======== | |
5f09af76 DM |
5 | :pve-toplevel: |
6 | ||
3c8533f2 DM |
7 | NAME |
8 | ---- | |
9 | ||
10 | pveum - Proxmox VE User Manager | |
11 | ||
12 | ||
49a5e11c | 13 | SYNOPSIS |
3c8533f2 DM |
14 | -------- |
15 | ||
16 | include::pveum.1-synopsis.adoc[] | |
17 | ||
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
21 | endif::manvolnum[] | |
3c8533f2 DM |
22 | ifndef::manvolnum[] |
23 | User Management | |
24 | =============== | |
5f09af76 | 25 | :pve-toplevel: |
194d2f29 | 26 | endif::manvolnum[] |
5f09af76 | 27 | |
3c8533f2 DM |
28 | // Copied from pve wiki: Revision as of 16:10, 27 October 2015 |
29 | ||
96942248 | 30 | {pve} supports multiple authentication sources, for example Linux PAM, |
5462c161 | 31 | an integrated Proxmox VE authentication server, LDAP, Microsoft Active |
96942248 | 32 | Directory and OpenID Connect. |
3c8533f2 | 33 | |
96942248 DW |
34 | By using role-based user and permission management for all objects (VMs, |
35 | Storage, nodes, etc.), granular access can be defined. | |
5eba0743 | 36 | |
3c8533f2 | 37 | |
80c0adcb | 38 | [[pveum_users]] |
c80b9ee6 WB |
39 | Users |
40 | ----- | |
41 | ||
42 | {pve} stores user attributes in `/etc/pve/user.cfg`. | |
96942248 | 43 | Passwords are not stored here; users are instead associated with the |
80c0adcb | 44 | <<pveum_authentication_realms,authentication realms>> described below. |
96942248 | 45 | Therefore, a user is often internally identified by their username and |
c80b9ee6 WB |
46 | realm in the form `<userid>@<realm>`. |
47 | ||
48 | Each user entry in this file contains the following information: | |
49 | ||
50 | * First name | |
51 | * Last name | |
52 | * E-mail address | |
53 | * Group memberships | |
96942248 | 54 | * An optional expiration date |
c80b9ee6 WB |
55 | * A comment or note about this user |
56 | * Whether this user is enabled or disabled | |
74662f51 | 57 | * Optional two-factor authentication keys |
c80b9ee6 | 58 | |
96942248 | 59 | CAUTION: When you disable or delete a user, or if the expiry date set is |
f06ba6a6 | 60 | in the past, this user will not be able to log in to new sessions or start new |
96942248 | 61 | tasks. All tasks which have already been started by this user (for example, |
f06ba6a6 | 62 | terminal sessions) will **not** be terminated automatically by any such event. |
8d02d0a2 | 63 | |
c80b9ee6 WB |
64 | |
65 | System administrator | |
66 | ~~~~~~~~~~~~~~~~~~~~ | |
67 | ||
68 | The system's root user can always log in via the Linux PAM realm and is an | |
69 | unconfined administrator. This user cannot be deleted, but attributes can | |
96942248 | 70 | still be changed. System mails will be sent to the email address |
c80b9ee6 WB |
71 | assigned to this user. |
72 | ||
73 | ||
80c0adcb | 74 | [[pveum_groups]] |
c80b9ee6 | 75 | Groups |
a10a91c2 | 76 | ------ |
c80b9ee6 | 77 | |
96942248 DW |
78 | Each user can be a member of several groups. Groups are the preferred |
79 | way to organize access permissions. You should always grant permissions | |
80 | to groups instead of individual users. That way you will get a | |
81 | much more maintainable access control list. | |
c80b9ee6 | 82 | |
181db098 FG |
83 | [[pveum_tokens]] |
84 | API Tokens | |
a10a91c2 | 85 | ---------- |
181db098 | 86 | |
96942248 | 87 | API tokens allow stateless access to most parts of the REST API from another |
710713ea TL |
88 | system, software or API client. Tokens can be generated for individual users |
89 | and can be given separate permissions and expiration dates to limit the scope | |
96942248 | 90 | and duration of the access. Should the API token get compromised, it can be |
710713ea | 91 | revoked without disabling the user itself. |
181db098 FG |
92 | |
93 | API tokens come in two basic types: | |
94 | ||
96942248 DW |
95 | * Separated privileges: The token needs to be given explicit access with ACLs. |
96 | Its effective permissions are calculated by intersecting user and token | |
181db098 | 97 | permissions. |
96942248 | 98 | * Full privileges: The token's permissions are identical to that of the |
181db098 FG |
99 | associated user. |
100 | ||
c6e098a2 TL |
101 | CAUTION: The token value is only displayed/returned once when the token is |
102 | generated. It cannot be retrieved again over the API at a later time! | |
181db098 FG |
103 | |
104 | To use an API token, set the HTTP header 'Authorization' to the displayed value | |
105 | of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or | |
96942248 | 106 | refer to your API client's documentation. |
c80b9ee6 | 107 | |
23b447be DW |
108 | [[pveum_resource_pools]] |
109 | Resource Pools | |
110 | -------------- | |
111 | ||
112 | [thumbnail="screenshot/gui-datacenter-pool-window.png"] | |
113 | ||
114 | A resource pool is a set of virtual machines, containers, and storage | |
115 | devices. It is useful for permission handling in cases where certain users | |
116 | should have controlled access to a specific set of resources, as it allows for a | |
117 | single permission to be applied to a set of elements, rather than having to | |
96942248 DW |
118 | manage this on a per-resource basis. Resource pools are often used in tandem |
119 | with groups, so that the members of a group have permissions on a set of | |
120 | machines and storage. | |
23b447be | 121 | |
80c0adcb | 122 | [[pveum_authentication_realms]] |
3c8533f2 DM |
123 | Authentication Realms |
124 | --------------------- | |
125 | ||
d6614202 WB |
126 | As {pve} users are just counterparts for users existing on some external |
127 | realm, the realms have to be configured in `/etc/pve/domains.cfg`. | |
128 | The following realms (authentication methods) are available: | |
3c8533f2 DM |
129 | |
130 | Linux PAM standard authentication:: | |
96942248 DW |
131 | In this case, a system user must exist (for example, created via the `adduser` |
132 | command) on each node which the user is allowed to log in, and the user | |
d6614202 WB |
133 | authenticates with their usual system password. |
134 | + | |
3c8533f2 DM |
135 | [source,bash] |
136 | ---- | |
137 | useradd heinz | |
138 | passwd heinz | |
139 | groupadd watchman | |
140 | usermod -a -G watchman heinz | |
141 | ---- | |
142 | ||
143 | Proxmox VE authentication server:: | |
96942248 DW |
144 | This is a Unix-like password store (`/etc/pve/priv/shadow.cfg`). |
145 | Passwords are encrypted using the SHA-256 hashing algorithm. | |
146 | This is the most convenient method for small-scale (or even mid-scale) | |
147 | installations, where users do not need access to anything outside of | |
148 | {pve}. In this case, users are fully managed by {pve} and are able to | |
d6614202 WB |
149 | change their own passwords via the GUI. |
150 | ||
151 | LDAP:: | |
96942248 DW |
152 | It is possible to authenticate users via an LDAP server (for example, |
153 | openldap). A server and optional fallback server can be | |
154 | configured, and the connection can be encrypted via SSL. | |
d6614202 WB |
155 | + |
156 | Users are searched under a 'Base Domain Name' (`base_dn`), with the | |
96942248 | 157 | username found in the attribute specified in the 'User Attribute Name' |
d6614202 WB |
158 | (`user_attr`) field. |
159 | + | |
160 | For instance, if a user is represented via the | |
96942248 | 161 | following LDIF dataset: |
d6614202 WB |
162 | + |
163 | ---- | |
164 | # user1 of People at ldap-test.com | |
165 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
166 | objectClass: top | |
167 | objectClass: person | |
168 | objectClass: organizationalPerson | |
169 | objectClass: inetOrgPerson | |
170 | uid: user1 | |
171 | cn: Test User 1 | |
172 | sn: Testers | |
173 | description: This is the first test user. | |
174 | ---- | |
175 | + | |
176 | The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user | |
177 | attribute would be `uid`. | |
178 | + | |
3a433e9b | 179 | If {pve} needs to authenticate (bind) to the LDAP server before being |
d6614202 WB |
180 | able to query and authenticate users, a bind domain name can be |
181 | configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its | |
182 | password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw` | |
96942248 DW |
183 | (for example, `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a |
184 | single line with the raw password. | |
0fb9147a | 185 | + |
96942248 | 186 | To verify certificates, you need to set `capath`. You can set it either |
4ab527b1 TL |
187 | directly to the CA certificate of your LDAP server, or to the system path |
188 | containing all trusted CA certificates (`/etc/ssl/certs`). | |
3a433e9b | 189 | Additionally, you need to set the `verify` option, which can also be done over |
4ab527b1 | 190 | the web interface. |
d6614202 | 191 | |
96942248 DW |
192 | NOTE: In order to allow a particular user to authenticate using the LDAP server, |
193 | you must also add them as a user of that realm from the {pve} server. | |
3c8533f2 | 194 | |
3a433e9b OB |
195 | A server and authentication domain need to be specified. Like with LDAP, an |
196 | optional fallback server, port, and SSL encryption can be configured. | |
3c8533f2 | 197 | |
96942248 | 198 | OpenID Connect:: |
f3ee27eb | 199 | |
96942248 DW |
200 | OpenID Connect allows clients to verify the identity of the user, based on |
201 | authentication performed by an external authorization server. | |
f3ee27eb DM |
202 | |
203 | ||
204 | [[pveum_openid]] | |
96942248 | 205 | OpenID Connect |
f3ee27eb DM |
206 | ~~~~~~~~~~~~~~ |
207 | ||
208 | The main OpenID Connect configuration options are: | |
209 | ||
96942248 DW |
210 | * `issuer-url`: This is the URL to the authorization server. Proxmox |
211 | uses the OpenID Connect Discovery protocol to automatically configure | |
f3ee27eb DM |
212 | further details. |
213 | + | |
96942248 | 214 | While it is possible to use unencrypted `http://` URLs, we strongly recommend to |
f3ee27eb DM |
215 | use encrypted `https://` connections. |
216 | ||
217 | * `client-id`: OpenID Client ID. | |
218 | ||
219 | * `client-key`: Optional OpenID Client Key. | |
220 | ||
221 | * `autocreate`: Automatically create users if they do not exist. While | |
62547dfa | 222 | authentication is done at the OpenID server, all users still need an |
f3ee27eb DM |
223 | entry in the {pve} user configuration. You can either add them |
224 | manually, or use the `autocreate` option to automatically add new | |
225 | users. | |
226 | ||
227 | * `username-claim`: OpenID claim used to generate the unique username | |
228 | (`subject`, `username` or `email`). | |
229 | ||
230 | Username mapping | |
231 | ^^^^^^^^^^^^^^^^ | |
232 | ||
96942248 DW |
233 | The OpenID Connect specification defines a single unique attribute |
234 | ('claim' in OpenID terms) named `subject`. By default, we use the | |
f3ee27eb DM |
235 | value of this attribute to generate {pve} usernames, by simple adding |
236 | `@` and the realm name: `${subject}@${realm}`. | |
237 | ||
96942248 | 238 | Unfortunately, most OpenID servers use random strings for `subject`, like |
f3ee27eb | 239 | `DGH76OKH34BNG3245SB`, so a typical username would look like |
96942248 | 240 | `DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for |
f3ee27eb | 241 | humans to remember such random strings, making it quite impossible to |
96942248 | 242 | associate real users with this. |
f3ee27eb DM |
243 | |
244 | The `username-claim` setting allows you to use other attributes for | |
96942248 DW |
245 | the username mapping. Setting it to `username` is preferred if the |
246 | OpenID Connect server provides that attribute and guarantees its | |
f3ee27eb DM |
247 | uniqueness. |
248 | ||
96942248 | 249 | Another option is to use `email`, which also yields human readable |
62547dfa | 250 | usernames. Again, only use this setting if the server guarantees the |
f3ee27eb DM |
251 | uniqueness of this attribute. |
252 | ||
253 | Examples | |
254 | ^^^^^^^^ | |
255 | ||
96942248 | 256 | Here is an example of creating an OpenID realm using Google. You need to |
f3ee27eb | 257 | replace `--client-id` and `--client-key` with the values |
96942248 | 258 | from your Google OpenID settings. |
f3ee27eb DM |
259 | |
260 | ---- | |
261 | pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email | |
262 | ---- | |
263 | ||
96942248 DW |
264 | The above command uses `--username-claim email`, so that the usernames on the |
265 | {pve} side look like `example.user@google.com@myrealm1`. | |
f3ee27eb | 266 | |
96942248 DW |
267 | Keycloak (https://www.keycloak.org/) is a popular open source Identity |
268 | and Access Management tool, which supports OpenID Connect. In the following | |
f3ee27eb | 269 | example, you need to replace the `--issuer-url` and `--client-id` with |
96942248 | 270 | your information: |
f3ee27eb DM |
271 | |
272 | ---- | |
273 | pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username | |
274 | ---- | |
275 | ||
96942248 | 276 | Using `--username-claim username` enables simple usernames on the |
f3ee27eb DM |
277 | {pve} side, like `example.user@myrealm2`. |
278 | ||
96942248 DW |
279 | WARNING: You need to ensure that the user is not allowed to edit |
280 | the username setting themselves (on the Keycloak server). | |
f3ee27eb DM |
281 | |
282 | ||
a160926a DC |
283 | [[pveum_ldap_sync]] |
284 | Syncing LDAP-based realms | |
285 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
286 | ||
41c386ba TL |
287 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"] |
288 | ||
96942248 DW |
289 | It is possible to sync users and groups for LDAP-based realms. You can use the |
290 | following CLI command: | |
f5eb2299 TL |
291 | |
292 | ---- | |
96942248 | 293 | pveum realm sync <realm> |
f5eb2299 | 294 | ---- |
96942248 DW |
295 | |
296 | or the `Authentication` panel of the GUI. Users and groups are synced to the | |
f5eb2299 | 297 | cluster-wide user configuration file `/etc/pve/user.cfg`. |
a160926a DC |
298 | |
299 | Requirements and limitations | |
300 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
301 | ||
96942248 | 302 | The `bind_dn` is used to query users and groups. This account needs access |
f5eb2299 | 303 | to all desired entries. |
a160926a DC |
304 | |
305 | The fields which represent the names of the users and groups can be configured | |
306 | via the `user_attr` and `group_name_attr` respectively. Only entries which | |
96942248 | 307 | adhere to the usual character limitations of the `user.cfg` are synced. |
a160926a | 308 | |
96942248 DW |
309 | Groups are synced with `-$realm` attached to the name, in order to avoid naming |
310 | conflicts. Please ensure that a sync does not overwrite manually created | |
a160926a DC |
311 | groups. |
312 | ||
f5eb2299 | 313 | [[pveum_ldap_sync_options]] |
a160926a DC |
314 | Options |
315 | ^^^^^^^ | |
316 | ||
41c386ba TL |
317 | [thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"] |
318 | ||
a160926a DC |
319 | The main options for syncing are: |
320 | ||
321 | * `dry-run`: No data is written to the config. This is useful if you want to | |
96942248 | 322 | see which users and groups would get synced to the `user.cfg`. This is set |
a160926a DC |
323 | when you click `Preview` in the GUI. |
324 | ||
96942248 | 325 | * `enable-new`: If set, the newly synced users are enabled and can log in. |
a160926a DC |
326 | The default is `true`. |
327 | ||
96942248 DW |
328 | * `full`: If set, the sync uses the LDAP directory as a source of truth, |
329 | overwriting information set manually in the `user.cfg` and deleting users | |
a160926a DC |
330 | and groups which are not present in the LDAP directory. If not set, |
331 | only new data is written to the config, and no stale users are deleted. | |
332 | ||
333 | * `purge`: If set, sync removes all corresponding ACLs when removing users | |
334 | and groups. This is only useful with the option `full`. | |
335 | ||
336 | * `scope`: The scope of what to sync. It can be either `users`, `groups` or | |
337 | `both`. | |
338 | ||
96942248 | 339 | These options are either set as parameters or as defaults via the |
a160926a | 340 | realm option `sync-defaults-options`. |
5eba0743 | 341 | |
0523992b | 342 | [[pveum_tfa_auth]] |
96942248 | 343 | Two-Factor Authentication |
9e8f2770 WB |
344 | ------------------------- |
345 | ||
74662f51 | 346 | There are two ways to use two-factor authentication: |
2837cf1d | 347 | |
74662f51 | 348 | It can be required by the authentication realm, either via 'TOTP' |
96942248 DW |
349 | (Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly |
350 | created user needs to have their keys added immediately, as there is no way to | |
74662f51 OB |
351 | log in without the second factor. In the case of 'TOTP', users can |
352 | also change the 'TOTP' later on, provided they can log in first. | |
2837cf1d | 353 | |
96942248 | 354 | Alternatively, users can choose to opt-in to two-factor authentication |
74662f51 | 355 | via 'TOTP' later on, even if the realm does not enforce it. As another |
96942248 | 356 | option, if the server has an 'AppId' configured, a user can opt-in to |
74662f51 OB |
357 | 'U2F' authentication, provided the realm does not enforce any other |
358 | second factor. | |
2837cf1d | 359 | |
96942248 | 360 | Realm Enforced Two-Factor Authentication |
2837cf1d WB |
361 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
362 | ||
74662f51 OB |
363 | This can be done by selecting one of the available methods via the |
364 | 'TFA' dropdown box when adding or editing an Authentication Realm. | |
96942248 DW |
365 | When a realm has TFA enabled, it becomes a requirement, and only users |
366 | with configured TFA will be able to log in. | |
9e8f2770 WB |
367 | |
368 | Currently there are two methods available: | |
369 | ||
96942248 | 370 | Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm, |
74662f51 | 371 | where the current time is hashed with the user's configured key. The |
96942248 | 372 | time step and password length parameters are configurable. |
9e8f2770 | 373 | + |
74662f51 OB |
374 | A user can have multiple keys configured (separated by spaces), and the keys |
375 | can be specified in Base32 (RFC3548) or hexadecimal notation. | |
9e8f2770 | 376 | + |
74662f51 | 377 | {pve} provides a key generation tool (`oathkeygen`) which prints out a random |
96942248 | 378 | key in Base32 notation, that can be used directly with various OTP tools, such |
74662f51 OB |
379 | as the `oathtool` command line tool, or on Android Google Authenticator, |
380 | FreeOTP, andOTP or similar applications. | |
9e8f2770 WB |
381 | |
382 | YubiKey OTP:: | |
383 | For authenticating via a YubiKey a Yubico API ID, API KEY and validation | |
384 | server URL must be configured, and users must have a YubiKey available. In | |
385 | order to get the key ID from a YubiKey, you can trigger the YubiKey once | |
96942248 | 386 | after connecting it via USB, and copy the first 12 characters of the typed |
9e8f2770 | 387 | password into the user's 'Key IDs' field. |
74662f51 | 388 | |
74662f51 OB |
389 | Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP] |
390 | documentation for how to use the | |
9e8f2770 | 391 | https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or |
96942248 | 392 | https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server]. |
9e8f2770 | 393 | |
0523992b | 394 | [[pveum_user_configured_totp]] |
96942248 | 395 | User Configured TOTP Authentication |
2837cf1d WB |
396 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
397 | ||
96942248 | 398 | Users can choose to enable 'TOTP' as a second factor on login, via the 'TFA' |
74662f51 | 399 | button in the user list (unless the realm enforces 'YubiKey OTP'). |
2837cf1d | 400 | |
2b59fcfb TL |
401 | [thumbnail="screenshot/gui-datacenter-users-tfa.png"] |
402 | ||
96942248 DW |
403 | After opening the 'TFA' window, the user is presented with a dialog to set up |
404 | 'TOTP' authentication. The 'Secret' field contains the key, which can be | |
405 | randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be | |
406 | added to provide information to the 'TOTP' app about what the key belongs to. | |
2837cf1d | 407 | Most 'TOTP' apps will show the issuer name together with the corresponding |
96942248 | 408 | 'OTP' values. The username is also included in the QR code for the 'TOTP' app. |
2837cf1d | 409 | |
96942248 DW |
410 | After generating a key, a QR code will be displayed, which can be used with most |
411 | OTP apps such as FreeOTP. The user then needs to verify the current user | |
2837cf1d | 412 | password (unless logged in as 'root'), as well as the ability to correctly use |
96942248 DW |
413 | the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code' |
414 | field and pressing the 'Apply' button. | |
2837cf1d | 415 | |
97d63abc | 416 | [[pveum_configure_u2f]] |
96942248 | 417 | Server Side U2F Configuration |
2837cf1d WB |
418 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
419 | ||
58df830b | 420 | To allow users to use 'U2F' authentication, it may be necessary to use a valid |
96942248 DW |
421 | domain with a valid SSL certificate, otherwise, some browsers may print |
422 | a warning or reject U2F usage altogether. Initially, an 'AppId' | |
2837cf1d WB |
423 | footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] |
424 | needs to be configured. | |
425 | ||
426 | NOTE: Changing the 'AppId' will render all existing 'U2F' registrations | |
427 | unusable! | |
428 | ||
96942248 | 429 | This is done via `/etc/pve/datacenter.cfg`. For instance: |
2837cf1d WB |
430 | |
431 | ---- | |
432 | u2f: appid=https://mypve.example.com:8006 | |
433 | ---- | |
434 | ||
96942248 DW |
435 | For a single node, the 'AppId' can simply be the address of the web-interface, |
436 | exactly as it is used in the browser, including the 'https://' and the port, as | |
437 | shown above. Please note that some browsers may be more strict than others when | |
438 | matching 'AppIds'. | |
2837cf1d WB |
439 | |
440 | When using multiple nodes, it is best to have a separate `https` server | |
441 | providing an `appid.json` | |
442 | footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html] | |
443 | file, as it seems to be compatible with most | |
444 | browsers. If all nodes use subdomains of the same top level domain, it may be | |
96942248 DW |
445 | enough to use the TLD as 'AppId'. It should however be noted that some browsers |
446 | may not accept this. | |
2837cf1d WB |
447 | |
448 | NOTE: A bad 'AppId' will usually produce an error, but we have encountered | |
96942248 DW |
449 | situations when this does not happen, particularly when using a top level domain |
450 | 'AppId' for a node that is accessed via a subdomain in Chromium. For this reason | |
451 | it is recommended to test the configuration with multiple browsers, as changing | |
452 | the 'AppId' later will render existing 'U2F' registrations unusable. | |
2837cf1d | 453 | |
0523992b | 454 | [[pveum_user_configured_u2f]] |
96942248 | 455 | Activating U2F as a User |
2837cf1d WB |
456 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
457 | ||
458 | To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the | |
459 | current password (unless logged in as root), and press the 'Register' button. | |
96942248 | 460 | If the server is set up correctly and the browser accepts the server's provided |
2837cf1d | 461 | 'AppId', a message will appear prompting the user to press the button on the |
96942248 DW |
462 | 'U2F' device (if it is a 'YubiKey', the button light should be toggling on and |
463 | off steadily, roughly twice per second). | |
2837cf1d WB |
464 | |
465 | Firefox users may need to enable 'security.webauth.u2f' via 'about:config' | |
466 | before they can use a 'U2F' token. | |
9e8f2770 | 467 | |
80c0adcb | 468 | [[pveum_permission_management]] |
04f44730 | 469 | Permission Management |
3c8533f2 DM |
470 | --------------------- |
471 | ||
04f44730 | 472 | In order for a user to perform an action (such as listing, modifying or |
96942248 | 473 | deleting parts of a VM's configuration), the user needs to have the |
04f44730 WB |
474 | appropriate permissions. |
475 | ||
476 | {pve} uses a role and path based permission management system. An entry in | |
181db098 | 477 | the permissions table allows a user, group or token to take on a specific role |
96942248 | 478 | when accessing an 'object' or 'path'. This means that such an access rule can |
181db098 FG |
479 | be represented as a triple of '(path, user, role)', '(path, group, |
480 | role)' or '(path, token, role)', with the role containing a set of allowed | |
481 | actions, and the path representing the target of these actions. | |
04f44730 | 482 | |
5eba0743 | 483 | |
80c0adcb | 484 | [[pveum_roles]] |
853d288b WB |
485 | Roles |
486 | ~~~~~ | |
487 | ||
488 | A role is simply a list of privileges. Proxmox VE comes with a number | |
96942248 | 489 | of predefined roles, which satisfy most requirements. |
853d288b | 490 | |
96942248 | 491 | * `Administrator`: has full privileges |
853d288b | 492 | * `NoAccess`: has no privileges (used to forbid access) |
96942248 DW |
493 | * `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`) |
494 | * `PVEAuditor`: has read only access | |
853d288b WB |
495 | * `PVEDatastoreAdmin`: create and allocate backup space and templates |
496 | * `PVEDatastoreUser`: allocate backup space and view storage | |
497 | * `PVEPoolAdmin`: allocate pools | |
498 | * `PVESysAdmin`: User ACLs, audit, system console and system logs | |
499 | * `PVETemplateUser`: view and clone templates | |
96942248 | 500 | * `PVEUserAdmin`: manage users |
853d288b | 501 | * `PVEVMAdmin`: fully administer VMs |
96942248 | 502 | * `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management |
853d288b | 503 | |
96942248 | 504 | You can see the whole set of predefined roles in the GUI. |
853d288b | 505 | |
96942248 | 506 | You can add new roles via the GUI or the command line. |
5e6b02ff TL |
507 | |
508 | [thumbnail="screenshot/gui-datacenter-role-add.png"] | |
96942248 DW |
509 | From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and |
510 | click on the 'Create' button. There you can set a role name and select any | |
511 | desired privileges from the 'Privileges' drop-down menu. | |
853d288b | 512 | |
96942248 DW |
513 | To add a role through the command line, you can use the 'pveum' CLI tool, for |
514 | example: | |
853d288b WB |
515 | [source,bash] |
516 | ---- | |
96942248 DW |
517 | pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console" |
518 | pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console" | |
853d288b WB |
519 | ---- |
520 | ||
521 | ||
3c8533f2 DM |
522 | Privileges |
523 | ~~~~~~~~~~ | |
524 | ||
525 | A privilege is the right to perform a specific action. To simplify | |
526 | management, lists of privileges are grouped into roles, which can then | |
96942248 | 527 | be used in the permission table. Note that privileges cannot be directly |
0e1fda70 | 528 | assigned to users and paths without being part of a role. |
3c8533f2 | 529 | |
96942248 | 530 | We currently support the following privileges: |
3c8533f2 DM |
531 | |
532 | Node / System related privileges:: | |
533 | ||
534 | * `Permissions.Modify`: modify access permissions | |
96942248 DW |
535 | * `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...) |
536 | * `Sys.Console`: console access to node | |
537 | * `Sys.Syslog`: view syslog | |
538 | * `Sys.Audit`: view node status/config, Corosync cluster config, and HA config | |
539 | * `Sys.Modify`: create/modify/remove node network parameters | |
540 | * `Group.Allocate`: create/modify/remove groups | |
541 | * `Pool.Allocate`: create/modify/remove a pool | |
696ebb3c | 542 | * `Pool.Audit`: view a pool |
96942248 | 543 | * `Realm.Allocate`: create/modify/remove authentication realms |
3c8533f2 | 544 | * `Realm.AllocateUser`: assign user to a realm |
96942248 | 545 | * `User.Modify`: create/modify/remove user access and details. |
3c8533f2 DM |
546 | |
547 | Virtual machine related privileges:: | |
548 | ||
96942248 | 549 | * `VM.Allocate`: create/remove VM on a server |
3c8533f2 DM |
550 | * `VM.Migrate`: migrate VM to alternate server on cluster |
551 | * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...) | |
552 | * `VM.Console`: console access to VM | |
553 | * `VM.Monitor`: access to VM monitor (kvm) | |
554 | * `VM.Backup`: backup/restore VMs | |
555 | * `VM.Audit`: view VM config | |
556 | * `VM.Clone`: clone/copy a VM | |
96942248 | 557 | * `VM.Config.Disk`: add/modify/remove disks |
3a433e9b | 558 | * `VM.Config.CDROM`: eject/change CD-ROM |
3c8533f2 | 559 | * `VM.Config.CPU`: modify CPU settings |
96942248 DW |
560 | * `VM.Config.Memory`: modify memory settings |
561 | * `VM.Config.Network`: add/modify/remove network devices | |
562 | * `VM.Config.HWType`: modify emulated hardware types | |
3c8533f2 | 563 | * `VM.Config.Options`: modify any other VM configuration |
96942248 | 564 | * `VM.Snapshot`: create/delete VM snapshots |
3c8533f2 DM |
565 | |
566 | Storage related privileges:: | |
567 | ||
96942248 | 568 | * `Datastore.Allocate`: create/modify/remove a datastore and delete volumes |
3c8533f2 | 569 | * `Datastore.AllocateSpace`: allocate space on a datastore |
96942248 | 570 | * `Datastore.AllocateTemplate`: allocate/upload templates and ISO images |
3c8533f2 DM |
571 | * `Datastore.Audit`: view/browse a datastore |
572 | ||
5eba0743 | 573 | |
b8eeec52 WB |
574 | Objects and Paths |
575 | ~~~~~~~~~~~~~~~~~ | |
576 | ||
96942248 DW |
577 | Access permissions are assigned to objects, such as virtual machines, |
578 | storages or resource pools. | |
b8eeec52 | 579 | We use file system like paths to address these objects. These paths form a |
96942248 | 580 | natural tree, and permissions of higher levels (shorter paths) can |
b8eeec52 WB |
581 | optionally be propagated down within this hierarchy. |
582 | ||
7d48940b | 583 | [[pveum_templated_paths]] |
b8eeec52 WB |
584 | Paths can be templated. When an API call requires permissions on a |
585 | templated path, the path may contain references to parameters of the API | |
586 | call. These references are specified in curly braces. Some parameters are | |
96942248 | 587 | implicitly taken from the API call's URI. For instance, the permission path |
b8eeec52 WB |
588 | `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on |
589 | `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` | |
590 | refers to the method's `path` parameter. | |
591 | ||
592 | Some examples are: | |
593 | ||
594 | * `/nodes/{node}`: Access to {pve} server machines | |
595 | * `/vms`: Covers all VMs | |
596 | * `/vms/{vmid}`: Access to specific VMs | |
96942248 DW |
597 | * `/storage/{storeid}`: Access to a specific storage |
598 | * `/pool/{poolname}`: Access to resources contained in a specific <<pveum_pools,pool>> | |
b8eeec52 WB |
599 | * `/access/groups`: Group administration |
600 | * `/access/realms/{realmid}`: Administrative access to realms | |
601 | ||
602 | ||
3c8533f2 DM |
603 | Inheritance |
604 | ^^^^^^^^^^^ | |
605 | ||
5eba0743 | 606 | As mentioned earlier, object paths form a file system like tree, and |
96942248 DW |
607 | permissions can be inherited by objects down that tree (the propagate flag is |
608 | set by default). We use the following inheritance rules: | |
3c8533f2 | 609 | |
74936daf WB |
610 | * Permissions for individual users always replace group permissions. |
611 | * Permissions for groups apply when the user is member of that group. | |
96942248 | 612 | * Permissions on deeper levels replace those inherited from an upper level. |
3c8533f2 | 613 | |
96942248 | 614 | Additionally, privilege separated tokens can never have permissions on any |
181db098 | 615 | given path that their associated user does not have. |
5eba0743 | 616 | |
80c0adcb | 617 | [[pveum_pools]] |
3c8533f2 DM |
618 | Pools |
619 | ~~~~~ | |
620 | ||
96942248 DW |
621 | Pools can be used to group a set of virtual machines and datastores. You can |
622 | then simply set permissions on pools (`/pool/{poolid}`), which are inherited by | |
623 | all pool members. This is a great way to simplify access control. | |
3c8533f2 | 624 | |
74936daf | 625 | |
96942248 DW |
626 | Which Permissions Do I Need? |
627 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
74936daf WB |
628 | |
629 | The required API permissions are documented for each individual | |
96942248 | 630 | method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/. |
74936daf | 631 | |
96942248 | 632 | The permissions are specified as a list, which can be interpreted as a |
74936daf WB |
633 | tree of logic and access-check functions: |
634 | ||
635 | `["and", <subtests>...]` and `["or", <subtests>...]`:: | |
636 | Each(`and`) or any(`or`) further element in the current list has to be true. | |
637 | ||
638 | `["perm", <path>, [ <privileges>... ], <options>...]`:: | |
7d48940b | 639 | The `path` is a templated parameter (see |
87ba80b0 | 640 | <<pveum_templated_paths,Objects and Paths>>). All (or, if the `any` |
7d48940b | 641 | option is used, any) of the listed |
74936daf WB |
642 | privileges must be allowed on the specified path. If a `require-param` |
643 | option is specified, then its specified parameter is required even if the | |
644 | API call's schema otherwise lists it as being optional. | |
645 | ||
646 | `["userid-group", [ <privileges>... ], <options>...]`:: | |
470d4313 | 647 | The caller must have any of the listed privileges on `/access/groups`. In |
96942248 | 648 | addition, there are two possible checks, depending on whether the |
74936daf WB |
649 | `groups_param` option is set: |
650 | + | |
651 | * `groups_param` is set: The API call has a non-optional `groups` parameter | |
652 | and the caller must have any of the listed privileges on all of the listed | |
653 | groups. | |
654 | * `groups_param` is not set: The user passed via the `userid` parameter | |
655 | must exist and be part of a group on which the caller has any of the listed | |
656 | privileges (via the `/access/groups/<group>` path). | |
657 | ||
658 | `["userid-param", "self"]`:: | |
659 | The value provided for the API call's `userid` parameter must refer to the | |
96942248 DW |
660 | user performing the action (usually in conjunction with `or`, to allow |
661 | users to perform an action on themselves, even if they don't have elevated | |
662 | privileges). | |
74936daf WB |
663 | |
664 | `["userid-param", "Realm.AllocateUser"]`:: | |
665 | The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with | |
470d4313 | 666 | `<realm>` referring to the realm of the user passed via the `userid` |
74936daf WB |
667 | parameter. Note that the user does not need to exist in order to be |
668 | associated with a realm, since user IDs are passed in the form of | |
669 | `<username>@<realm>`. | |
670 | ||
671 | `["perm-modify", <path>]`:: | |
7d48940b DM |
672 | The `path` is a templated parameter (see |
673 | <<pveum_templated_paths,Objects and Paths>>). The user needs either the | |
96942248 | 674 | `Permissions.Modify` privilege or, |
74936daf WB |
675 | depending on the path, the following privileges as a possible substitute: |
676 | + | |
677 | * `/storage/...`: additionally requires 'Datastore.Allocate` | |
678 | * `/vms/...`: additionally requires 'VM.Allocate` | |
679 | * `/pool/...`: additionally requires 'Pool.Allocate` | |
680 | + | |
681 | If the path is empty, `Permission.Modify` on `/access` is required. | |
682 | ||
3c8533f2 DM |
683 | Command Line Tool |
684 | ----------------- | |
685 | ||
686 | Most users will simply use the GUI to manage users. But there is also | |
87ba80b0 | 687 | a fully featured command line tool called `pveum` (short for ``**P**roxmox |
4f6e7e05 WB |
688 | **VE** **U**ser **M**anager''). Please note that all Proxmox VE command |
689 | line tools are wrappers around the API, so you can also access those | |
87ba80b0 | 690 | functions through the REST API. |
3c8533f2 | 691 | |
96942248 | 692 | Here are some simple usage examples. To show help, type: |
3c8533f2 DM |
693 | |
694 | [source,bash] | |
695 | pveum | |
696 | ||
697 | or (to show detailed help about a specific command) | |
698 | ||
699 | [source,bash] | |
9135e321 | 700 | pveum help user add |
3c8533f2 DM |
701 | |
702 | Create a new user: | |
703 | ||
704 | [source,bash] | |
9135e321 | 705 | pveum user add testuser@pve -comment "Just a test" |
3c8533f2 | 706 | |
96942248 | 707 | Set or change the password (not all realms support this): |
3c8533f2 DM |
708 | |
709 | [source,bash] | |
710 | pveum passwd testuser@pve | |
711 | ||
712 | Disable a user: | |
713 | ||
714 | [source,bash] | |
9135e321 | 715 | pveum user modify testuser@pve -enable 0 |
3c8533f2 DM |
716 | |
717 | Create a new group: | |
718 | ||
719 | [source,bash] | |
9135e321 | 720 | pveum group add testgroup |
3c8533f2 DM |
721 | |
722 | Create a new role: | |
723 | ||
724 | [source,bash] | |
9135e321 | 725 | pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console" |
3c8533f2 DM |
726 | |
727 | ||
728 | Real World Examples | |
729 | ------------------- | |
730 | ||
5eba0743 | 731 | |
3c8533f2 DM |
732 | Administrator Group |
733 | ~~~~~~~~~~~~~~~~~~~ | |
734 | ||
96942248 DW |
735 | It is possible that an administrator would want to create a group of users with |
736 | full administrator rights (without using the root account). | |
3c8533f2 | 737 | |
96942248 | 738 | To do this, first define the group: |
3c8533f2 DM |
739 | |
740 | [source,bash] | |
9135e321 | 741 | pveum group add admin -comment "System Administrators" |
3c8533f2 | 742 | |
96942248 | 743 | Then assign the role: |
3c8533f2 DM |
744 | |
745 | [source,bash] | |
9135e321 | 746 | pveum acl modify / -group admin -role Administrator |
3c8533f2 | 747 | |
96942248 | 748 | Finally, you can add users to the new 'admin' group: |
3c8533f2 DM |
749 | |
750 | [source,bash] | |
9135e321 | 751 | pveum user modify testuser@pve -group admin |
3c8533f2 DM |
752 | |
753 | ||
754 | Auditors | |
755 | ~~~~~~~~ | |
756 | ||
757 | You can give read only access to users by assigning the `PVEAuditor` | |
758 | role to users or groups. | |
759 | ||
96942248 | 760 | Example 1: Allow user `joe@pve` to see everything |
3c8533f2 DM |
761 | |
762 | [source,bash] | |
9135e321 | 763 | pveum acl modify / -user joe@pve -role PVEAuditor |
3c8533f2 | 764 | |
96942248 | 765 | Example 2: Allow user `joe@pve` to see all virtual machines |
3c8533f2 DM |
766 | |
767 | [source,bash] | |
9135e321 | 768 | pveum acl modify /vms -user joe@pve -role PVEAuditor |
3c8533f2 | 769 | |
5eba0743 | 770 | |
3c8533f2 DM |
771 | Delegate User Management |
772 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
773 | ||
96942248 | 774 | If you want to delegate user management to user `joe@pve`, you can do |
3c8533f2 DM |
775 | that with: |
776 | ||
777 | [source,bash] | |
9135e321 | 778 | pveum acl modify /access -user joe@pve -role PVEUserAdmin |
3c8533f2 | 779 | |
96942248 DW |
780 | User `joe@pve` can now add and remove users, and change other user attributes, |
781 | such as passwords. This is a very powerful role, and you most | |
782 | likely want to limit it to selected realms and groups. The following | |
783 | example allows `joe@pve` to modify users within the realm `pve`, if they | |
8c1189b6 | 784 | are members of group `customers`: |
3c8533f2 DM |
785 | |
786 | [source,bash] | |
9135e321 TL |
787 | pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin |
788 | pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin | |
3c8533f2 | 789 | |
0abc65b0 | 790 | NOTE: The user is able to add other users, but only if they are |
96942248 | 791 | members of the group `customers` and within the realm `pve`. |
8c1189b6 | 792 | |
96942248 | 793 | Limited API Token for Monitoring |
181db098 FG |
794 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
795 | ||
a13a971d DW |
796 | Permissions on API tokens are always a subset of those of their corresponding |
797 | user, meaning that an API token can't be used to carry out a task that the | |
798 | backing user has no permission to do. This section will demonstrate how you can | |
799 | use an API token with separate privileges, to limit the token owner's | |
800 | permissions further. | |
801 | ||
802 | Give the user `joe@pve` the role PVEVMAdmin on all VMs: | |
181db098 FG |
803 | |
804 | [source,bash] | |
9135e321 | 805 | pveum acl modify /vms -user joe@pve -role PVEVMAdmin |
181db098 FG |
806 | |
807 | Add a new API token with separate privileges, which is only allowed to view VM | |
96942248 | 808 | information (for example, for monitoring purposes): |
181db098 FG |
809 | |
810 | [source,bash] | |
811 | pveum user token add joe@pve monitoring -privsep 1 | |
9135e321 | 812 | pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor |
181db098 FG |
813 | |
814 | Verify the permissions of the user and token: | |
815 | ||
816 | [source,bash] | |
817 | pveum user permissions joe@pve | |
818 | pveum user token permissions joe@pve monitoring | |
3c8533f2 | 819 | |
23b447be DW |
820 | Resource Pools |
821 | ~~~~~~~~~~~~~~ | |
3c8533f2 | 822 | |
23b447be DW |
823 | An enterprise is usually structured into several smaller departments, and it is |
824 | common that you want to assign resources and delegate management tasks to each | |
825 | of these. Let's assume that you want to set up a pool for a software development | |
96942248 | 826 | department. First, create a group: |
3c8533f2 DM |
827 | |
828 | [source,bash] | |
9135e321 | 829 | pveum group add developers -comment "Our software developers" |
3c8533f2 | 830 | |
96942248 | 831 | Now we create a new user which is a member of that group: |
3c8533f2 DM |
832 | |
833 | [source,bash] | |
9135e321 | 834 | pveum user add developer1@pve -group developers -password |
3c8533f2 | 835 | |
96942248 | 836 | NOTE: The "-password" parameter will prompt you for a password |
3c8533f2 | 837 | |
96942248 | 838 | Then we create a resource pool for our development department to use: |
23b447be DW |
839 | |
840 | [source,bash] | |
9135e321 | 841 | pveum pool add dev-pool --comment "IT development pool" |
23b447be | 842 | |
96942248 | 843 | Finally, we can assign permissions to that pool: |
3c8533f2 DM |
844 | |
845 | [source,bash] | |
9135e321 | 846 | pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin |
3c8533f2 | 847 | |
96942248 | 848 | Our software developers can now administer the resources assigned to |
3c8533f2 DM |
849 | that pool. |
850 | ||
851 | ||
852 | ifdef::manvolnum[] | |
853 | include::pve-copyright.adoc[] | |
854 | endif::manvolnum[] | |
855 |