From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <pmg-devel-bounces@lists.proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
by lore.proxmox.com (Postfix) with ESMTPS id D45C01FF165
for <inbox@lore.proxmox.com>; Wed, 26 Feb 2025 22:31:11 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
by firstgate.proxmox.com (Proxmox) with ESMTP id 81A751D030;
Wed, 26 Feb 2025 22:31:10 +0100 (CET)
From: Stoiko Ivanov <s.ivanov@proxmox.com>
To: pmg-devel@lists.proxmox.com
Date: Wed, 26 Feb 2025 22:30:29 +0100
Message-Id: <20250226213029.597792-1-s.ivanov@proxmox.com>
X-Mailer: git-send-email 2.39.5
MIME-Version: 1.0
X-SPAM-LEVEL: Spam detection results: 0
AWL -0.135 Adjusted score from AWL reputation of From: address
BAYES_00 -1.9 Bayes spam probability is 0 to 1%
DMARC_MISSING 0.1 Missing DMARC policy
KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
POISEN_SPAM_PILL 0.1 Meta: its spam
POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes
POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes
SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record
SPF_PASS -0.001 SPF: sender matches SPF record
URIBL_SBL_A 0.1 Contains URL's A record listed in the Spamhaus SBL blocklist
[185.199.110.153, 185.199.111.153]
Subject: [pmg-devel] [PATCH pmg-docs] pmgconfig: add docs for realms and oidc
X-BeenThere: pmg-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox Mail Gateway development discussion
<pmg-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pmg-devel>,
<mailto:pmg-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pmg-devel/>
List-Post: <mailto:pmg-devel@lists.proxmox.com>
List-Help: <mailto:pmg-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel>,
<mailto:pmg-devel-request@lists.proxmox.com?subject=subscribe>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: pmg-devel-bounces@lists.proxmox.com
Sender: "pmg-devel" <pmg-devel-bounces@lists.proxmox.com>
started out as a copy from the relevant sections from pveum.adoc in
pve-docs. mostly adapted by `s///` appropriately and deleting the
sections on LDAP/AD realms.
stuck with adding it in a section of its own instead of under
user-management, as we did for the TFA documentation.
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
pmgconfig.adoc | 130 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 130 insertions(+)
diff --git a/pmgconfig.adoc b/pmgconfig.adoc
index f8b338c..38d0bca 100644
--- a/pmgconfig.adoc
+++ b/pmgconfig.adoc
@@ -109,6 +109,10 @@ Message delivery transport setup.
GUI user configuration.
+`/etc/pmg/realms.conf`::
+
+Login realm configuration.
+
`/etc/mail/spamassassin/custom.cf`::
Custom {spamassassin} setup.
@@ -1135,6 +1139,132 @@ registrations unusable!
You can configure WebAuthn directly in the 'Two Factor' panel, there's an
auto-fill button that will set the correct values for most setups.
+
+[[user_authentication_realms]]
+Authentication Realms
+---------------------
+
+As {pmg} users are just counterparts for users existing on some external
+realm, the realms have to be configured in `/etc/pmg/realms.conf`.
+The following realms (authentication methods) are available:
+
+Linux PAM Standard Authentication::
+
+Linux PAM is a framework for system-wide user authentication. These users are
+created on the host system with commands such as `adduser`.
+
+{pmg} Authentication Server::
+
+This is a Unix-like password store, which stores hashed passwords directly in
+`/etc/pmg/user.conf`. Passwords are hashed using the SHA-256 hashing
+algorithm. This is the most convenient realm for small-scale (or even
+mid-scale) installations, where users do not need access to anything outside of
+{pmg}. In this case, users are fully managed by {pmg} and are able to change
+their own passwords via the GUI.
+
+OpenID Connect::
+
+OpenID Connect is implemented as an identity layer on top of the OATH 2.0
+protocol. It allows clients to verify the identity of the user, based on
+authentication performed by an external authorization server.
+
+[[user-realms-pam]]
+Linux PAM Standard Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As Linux PAM corresponds to host system users, a system user must exist on each
+node which the user is allowed to log in on. The user authenticates with their
+usual system password. This realm is added by default and can't be removed.In
+{pmg} this realm is restricted to the `root` user.
+
+
+[[user-realms-pmg]]
+{pmg} Authentication Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {pmg} authentication server realm is a simple Unix-like password store.
+The realm is created by default.
+
+Unlike the other {pmg} realm types, users are created and authenticated entirely
+through {pmg}, rather than authenticating against another system. Hence, you are
+required to set a password for this type of user upon creation.
+
+
+[[user_oidc]]
+OpenID Connect
+~~~~~~~~~~~~~~
+
+The main OpenID Connect configuration options are:
+
+* `Issuer URL` (`issuer-url`): This is the URL of the authorization server.
+Proxmox uses the OpenID Connect Discovery protocol to automatically configure
+further details.
++
+While it is possible to use unencrypted `http://` URLs, we strongly recommend to
+use encrypted `https://` connections.
+
+* `Realm` (`realm`): The realm identifier for {pmg} users
+
+* `Client ID` (`client-id`): OpenID Client ID.
+
+* `Client Key` (`client-key`): Optional OpenID Client Key.
+
+* `Autocreate Users` (`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 {pmg} user configuration. You can either add them manually, or
+use the `autocreate` option to automatically add new users.
+
+* `Username Claim` (`username-claim`): OpenID claim used to generate the unique
+username (`subject` or `username`).
+
+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 {pmg} usernames, by simple adding
+`@` and the realm name: `${subject}@${realm}`.
+
+Unfortunately, most OpenID servers use random strings for `subject`, like
+`DGH76OKH34BNG3245SB`, so a typical username would look like
+`DGH76OKH34BNG3245SB@yourrealm`. While unique, it is difficult for
+humans to remember such random strings, making it quite impossible to
+associate real users with this.
+
+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 guarantees its
+uniqueness.
+
+As {pmg} currently forbids `@` in usernames the option to use `email` is not
+possible..
+
+Examples
+^^^^^^^^
+
+Here is an example of creating an OpenID realm using Google. You need to
+replace `--client-id` and `--client-key` with the values
+from your Google OpenID settings.
+
+----
+pmgsh create /access/auth-realm --realm myrealm1 --type oidc --issuer-url https://accounts.google.com --client-id XXXX --client-key YYYY --username-claim username
+----
+
+The above command uses `--username-claim username`, so that the usernames on the
+{pmg} side look like `example.user@myrealm1`.
+
+Keycloak (https://www.keycloak.org/) is a popular open source Identity
+and Access Management tool, which supports OpenID Connect. In the following
+example, you need to replace the `--issuer-url` and `--client-id` with
+your information:
+
+----
+pmgsh create /access/auth-realm --realm myrealm2 --type oidc --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
+----
+
+WARNING: You need to ensure that the user is not allowed to edit
+the username setting themselves (on the Keycloak server).
+
ifdef::manvolnum[]
include::pmg-copyright.adoc[]
endif::manvolnum[]
--
2.39.5
_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel