X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=fe1eb3de700cb1eb623e82d02da8a845ca9c848c;hp=7998d16706661cd081bc59d588f0fd217b86f2c5;hb=00271f41dbff6bfcce1389bd904337c823dc2d64;hpb=41c386baae06bfe151f1554df55e37324fa70a8a diff --git a/pveum.adoc b/pveum.adoc index 7998d16..fe1eb3d 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -29,7 +29,7 @@ endif::manvolnum[] Proxmox VE supports multiple authentication sources, e.g. Linux PAM, an integrated Proxmox VE authentication server, LDAP, Microsoft Active -Directory. +Directory and OpenId Connect. By using the role based user- and permission management for all objects (VMs, storages, nodes, etc.) granular access can be defined. @@ -56,6 +56,11 @@ Each user entry in this file contains the following information: * Whether this user is enabled or disabled * Optional two-factor authentication keys +CAUTION: When you disabled or delete a user, or the expiry date got set and is +in the past, this user will not be able to log in to new sessions or start new +tasks. All tasks which already have been started by this user (for example +terminal sessions) will **not** be terminated automatically by any such event. + System administrator ~~~~~~~~~~~~~~~~~~~~ @@ -100,6 +105,20 @@ To use an API token, set the HTTP header 'Authorization' to the displayed value of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or refer to your API client documentation. +[[pveum_resource_pools]] +Resource Pools +-------------- + +[thumbnail="screenshot/gui-datacenter-pool-window.png"] + +A resource pool is a set of virtual machines, containers, and storage +devices. It is useful for permission handling in cases where certain users +should have controlled access to a specific set of resources, as it allows for a +single permission to be applied to a set of elements, rather than having to +manage this on a per resource basis. Resource pools are often used in tandem +with groups so that the members of a group have permissions on a set of machines +and storage. + [[pveum_authentication_realms]] Authentication Realms --------------------- @@ -157,18 +176,109 @@ description: This is the first test user. The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user attribute would be `uid`. + -If {pve} needs to authenticate (bind) to the ldap server before being +If {pve} needs to authenticate (bind) to the LDAP server before being able to query and authenticate users, a bind domain name can be configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its password then has to be stored in `/etc/pve/priv/ldap/.pw` (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a single line containing the raw password. ++ +To verify certificates, you need to to set `capath`. You can set it either +directly to the CA certificate of your LDAP server, or to the system path +containing all trusted CA certificates (`/etc/ssl/certs`). +Additionally, you need to set the `verify` option, which can also be done over +the web interface. Microsoft Active Directory:: -A server and authentication domain need to be specified. Like with -ldap an optional fallback server, optional port, and SSL -encryption can be configured. +A server and authentication domain need to be specified. Like with LDAP, an +optional fallback server, port, and SSL encryption can be configured. + +OpenId Connect:: + +OpenID Connect allows clients to verify the identity of the user based +on the authentication performed by an external authorization +server. + + +[[pveum_openid]] +OpenId Connect +~~~~~~~~~~~~~~ + +The main OpenID Connect configuration options are: + +* `issuer-url`: This is the Url to the authorization server. Proxmox +uses the OpenID Connect Discovery protocol to automatiocally configure +further details. ++ +While it is possible to use unencrypted `http://` Urls, we strongly recommend to +use encrypted `https://` connections. + +* `client-id`: OpenID Client ID. + +* `client-key`: Optional OpenID Client Key. + +* `autocreate`: Automatically create users if they do not exist. While +authentication is done at the OpenID server, all users still need an +entry in the {pve} user configuration. You can either add them +manually, or use the `autocreate` option to automatically add new +users. + +* `username-claim`: OpenID claim used to generate the unique username + (`subject`, `username` or `email`). + +Username mapping +^^^^^^^^^^^^^^^^ + +The Openid Connect specification defines a single unique attribute +('claim' in OpenId terms) named `subject`. By default, we use the +value of this attribute to generate {pve} usernames, by simple adding +`@` and the realm name: `${subject}@${realm}`. + +Unfortunately, most OpenID server use random strings for `subject`, like +`DGH76OKH34BNG3245SB`, so a typical username would look like +`DGH76OKH34BNG3245SB@yourrealm`. While unique, it is really hard for +humans to remember such random strings, making it quite impossible to +associate real users with that. + +The `username-claim` setting allows you to use other attributes for +the username mapping. Setting it to `username` is preferred, if the +OpenId Connect server provides that attribute and guarantee its +uniqueness. + +Another option is to use `email`, which also yields to human readable +usernames. Again, only use this setting if the server guarantees the +uniqueness of this attribute. + +Examples +^^^^^^^^ + +Here is an example to create an OpenId realm using Google. You need to +replace `--client-id` and `--client-key` with the values +from your Google OpenId settings. + +---- +pveum realm add myrealm1 --type openid --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim email +---- + +Above setup uses `--username-claim email`, so the usernames at the +{pve} side looks like `example.user@google.com@myrealm1`. + +KeyCloak (https://www.keycloak.org/) is a popular Open Source Identity +and Access Management supporting OpenId Connect. In the following +example, you need to replace the `--issuer-url` and `--client-id` with +your setting: + +---- +pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username +---- + +Using `--username-claim username` yields to simple usernames on the +{pve} side, like `example.user@myrealm2`. + +WARNING: You need to make sure that the user is not allowed to edit +the username setting himself (on the Keycloak server). + [[pveum_ldap_sync]] Syncing LDAP-based realms @@ -279,7 +389,7 @@ password into the user's 'Key IDs' field. Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or -https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[host +https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server]. [[pveum_user_configured_totp]] @@ -308,8 +418,9 @@ field before pressing the 'Apply' button. Server side U2F configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To allow users to use 'U2F' authentication, the server needs to have a valid -domain with a valid https certificate. Initially an 'AppId' +To allow users to use 'U2F' authentication, it may be necessary to use a valid +domain with a valid https certificate, otherwise some browsers may print +a warning or reject U2F usage altogether. Initially an 'AppId' footnote:[AppId https://developers.yubico.com/U2F/App_ID.html] needs to be configured. @@ -389,7 +500,7 @@ of predefined roles which satisfies most needs. * `PVETemplateUser`: view and clone templates * `PVEUserAdmin`: user administration * `PVEVMAdmin`: fully administer VMs -* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management +* `PVEVMUser`: view, backup, config CD-ROM, VM console, VM power management You can see the whole set of predefined roles on the GUI. @@ -429,6 +540,7 @@ Node / System related privileges:: * `Sys.Modify`: create/remove/modify node network parameters * `Group.Allocate`: create/remove/modify groups * `Pool.Allocate`: create/remove/modify a pool +* `Pool.Audit`: view a pool * `Realm.Allocate`: create/remove/modify authentication realms * `Realm.AllocateUser`: assign user to a realm * `User.Modify`: create/remove/modify user access and details. @@ -444,7 +556,7 @@ Virtual machine related privileges:: * `VM.Audit`: view VM config * `VM.Clone`: clone/copy a VM * `VM.Config.Disk`: add/modify/delete Disks -* `VM.Config.CDROM`: eject/change CDROM +* `VM.Config.CDROM`: eject/change CD-ROM * `VM.Config.CPU`: modify CPU settings * `VM.Config.Memory`: modify Memory settings * `VM.Config.Network`: add/modify/delete Network devices @@ -517,7 +629,7 @@ What permission do I need? ~~~~~~~~~~~~~~~~~~~~~~~~~~ The required API permissions are documented for each individual -method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ +method, and can be found at https://pve.proxmox.com/pve-docs/api-viewer/ The permissions are specified as a list which can be interpreted as a tree of logic and access-check functions: @@ -587,12 +699,12 @@ Here are some simple usage examples. To show help type: or (to show detailed help about a specific command) [source,bash] - pveum help useradd + pveum help user add Create a new user: [source,bash] - pveum useradd testuser@pve -comment "Just a test" + pveum user add testuser@pve -comment "Just a test" Set or Change the password (not all realms support that): @@ -602,17 +714,17 @@ Set or Change the password (not all realms support that): Disable a user: [source,bash] - pveum usermod testuser@pve -enable 0 + pveum user modify testuser@pve -enable 0 Create a new group: [source,bash] - pveum groupadd testgroup + pveum group add testgroup Create a new role: [source,bash] - pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" + pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console" Real World Examples @@ -628,17 +740,17 @@ users with full administrator rights (without using the root account). Define the group: [source,bash] - pveum groupadd admin -comment "System Administrators" + pveum group add admin -comment "System Administrators" Then add the permission: [source,bash] - pveum aclmod / -group admin -role Administrator + pveum acl modify / -group admin -role Administrator You can finally add users to the new 'admin' group: [source,bash] - pveum usermod testuser@pve -group admin + pveum user modify testuser@pve -group admin Auditors @@ -650,12 +762,12 @@ role to users or groups. Example1: Allow user `joe@pve` to see everything [source,bash] - pveum aclmod / -user joe@pve -role PVEAuditor + pveum acl modify / -user joe@pve -role PVEAuditor Example1: Allow user `joe@pve` to see all virtual machines [source,bash] - pveum aclmod /vms -user joe@pve -role PVEAuditor + pveum acl modify /vms -user joe@pve -role PVEAuditor Delegate User Management @@ -665,7 +777,7 @@ If you want to delegate user management to user `joe@pve` you can do that with: [source,bash] - pveum aclmod /access -user joe@pve -role PVEUserAdmin + pveum acl modify /access -user joe@pve -role PVEUserAdmin User `joe@pve` can now add and remove users, change passwords and other user attributes. This is a very powerful role, and you most @@ -674,8 +786,8 @@ example allows `joe@pve` to modify users within realm `pve` if they are members of group `customers`: [source,bash] - pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin - pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin + pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin + pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin NOTE: The user is able to add other users, but only if they are members of group `customers` and within realm `pve`. @@ -686,14 +798,14 @@ Limited API token for monitoring Given a user `joe@pve` with the PVEVMAdmin role on all VMs: [source,bash] - pveum aclmod /vms -user joe@pve -role PVEVMAdmin + pveum acl modify /vms -user joe@pve -role PVEVMAdmin Add a new API token with separate privileges, which is only allowed to view VM information (e.g., for monitoring purposes): [source,bash] pveum user token add joe@pve monitoring -privsep 1 - pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor + pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor Verify the permissions of the user and token: @@ -701,35 +813,33 @@ Verify the permissions of the user and token: pveum user permissions joe@pve pveum user token permissions joe@pve monitoring -Pools -~~~~~ - -An enterprise is usually structured into several smaller departments, -and it is common that you want to assign resources to them and -delegate management tasks. A pool is simply a set of virtual machines -and data stores. You can create pools on the GUI. After that you can -add resources to the pool (VMs, Storage). - -You can also assign permissions to the pool. Those permissions are -inherited to all pool members. +Resource Pools +~~~~~~~~~~~~~~ -Lets assume you have a software development department, so we first -create a group +An enterprise is usually structured into several smaller departments, and it is +common that you want to assign resources and delegate management tasks to each +of these. Let's assume that you want to set up a pool for a software development +department. First, create a group [source,bash] - pveum groupadd developers -comment "Our software developers" + pveum group add developers -comment "Our software developers" Now we create a new user which is a member of that group [source,bash] - pveum useradd developer1@pve -group developers -password + pveum user add developer1@pve -group developers -password NOTE: The -password parameter will prompt you for a password -I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool: +Then we create a resource pool for our development department to use + +[source,bash] + pveum pool add dev-pool --comment "IT development pool" + +Finally, we can assign permissions to that pool [source,bash] - pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin + pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin Our software developers can now administrate the resources assigned to that pool.