[pve-devel] [PATCH pve-docs] add OpenId Connect docu

Dietmar Maurer dietmar at proxmox.com
Thu Jul 1 10:55:11 CEST 2021

 pveum.adoc | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/pveum.adoc b/pveum.adoc
index a1adbaa..9329583 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 and OpenId Connect.
 By using the role based user- and permission management for all
 objects (VMs, storages, nodes, etc.) granular access can be defined.
@@ -194,6 +194,92 @@ Microsoft Active Directory::
 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
+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
+authentification 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
+* `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 at 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 guarrantee its
+Another option is to use `email`, which also yields to human readable
+usernames. Again, only use this setting if the server guarrantees the
+uniqueness of this attribute.
+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 at 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 at myrealm2`.
+WARNING: You need to make sure that the user is not allowed to edit
+the username setting himself (on the Keycloak server).
 Syncing LDAP-based realms

More information about the pve-devel mailing list