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.
* 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
~~~~~~~~~~~~~~~~~~~~
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
---------------------
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/<realmname>.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
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]]
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.
* `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.
* `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.
* `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
~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
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):
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
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
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
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
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`.
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:
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.
projects / pve-docs.git / blobdiff