From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 ; 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 ; 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 ; 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 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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