From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dietmar@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256)
(No client certificate requested)
by lists.proxmox.com (Postfix) with ESMTPS id 085CE722BA
for <pve-devel@lists.proxmox.com>; Thu, 1 Jul 2021 10:55:21 +0200 (CEST)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
by firstgate.proxmox.com (Proxmox) with ESMTP id EF7AB228B2
for <pve-devel@lists.proxmox.com>; Thu, 1 Jul 2021 10:55:20 +0200 (CEST)
Received: from dev7.proxmox.com (unknown [94.136.29.99])
by firstgate.proxmox.com (Proxmox) with ESMTP id 586A4228A9
for <pve-devel@lists.proxmox.com>; Thu, 1 Jul 2021 10:55:20 +0200 (CEST)
Received: by dev7.proxmox.com (Postfix, from userid 0)
id 3B82F809A4; Thu, 1 Jul 2021 10:55:14 +0200 (CEST)
From: Dietmar Maurer <dietmar@proxmox.com>
To: pve-devel@lists.proxmox.com
Date: Thu, 1 Jul 2021 10:55:11 +0200
Message-Id: <20210701085511.3662505-1-dietmar@proxmox.com>
X-Mailer: git-send-email 2.30.2
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results: 0
AWL -0.350 Adjusted score from AWL reputation of From: address
BAYES_00 -1.9 Bayes spam probability is 0 to 1%
KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
RDNS_NONE 0.793 Delivered to internal network by a host with no rDNS
SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record
SPF_PASS -0.001 SPF: sender matches SPF record
VFY_ACCT_NORDNS 1.784 Verify your account to a poorly-configured MTA -
probable phishing
Subject: [pve-devel] [PATCH pve-docs] add OpenId Connect docu
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>,
<mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Thu, 01 Jul 2021 08:55:21 -0000
---
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.
+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
+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
+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
+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 guarrantee its
+uniqueness.
+
+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.
+
+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
~~~~~~~~~~~~~~~~~~~~~~~~~
--
2.30.2