[pmg-devel] [PATCH pmg-docs] pmgconfig: add docs for realms and oidc

[Stoiko Ivanov]

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 at 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 at 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 at 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