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

[Shannon Sterz]

On Wed Feb 26, 2025 at 10:30 PM CET, Stoiko Ivanov wrote:
> 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.

hm left some comments in-line before reading this, i'll take a look at
pveum.adoc and send patch for the things i mentioned here if they are
also present there.

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

shouldn't this be OAuth 2.0? [1, 2]

[1]: https://datatracker.ietf.org/doc/html/rfc6749
[2]: https://datatracker.ietf.org/doc/html/rfc6750

> +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.

the use of "Proxmox" here is ambigous, it could be interpreted as the
company doing this, which is wrong as everything is done locally and
nothing is processed on company servers.

> ++
> +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..

extra period at the end here.

> +
> +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[]