From fc70b84c59f4bc028867c1ef45c1b5275327400d Mon Sep 17 00:00:00 2001 From: Stoiko Ivanov Date: Thu, 27 Feb 2025 11:26:24 +0100 Subject: [PATCH] add basic docs for realms and OIDC 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 Signed-off-by: Thomas Lamprecht --- pmgconfig.adoc | 130 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/pmgconfig.adoc b/pmgconfig.adoc index f8b338c..7308c88 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 Oauth 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. +{pmg} 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[]