From: Thomas Skinner <thomas@atskinner.net>
To: pve-devel@lists.proxmox.com
Cc: Thomas Skinner <thomas@atskinner.net>
Subject: [pve-devel] [PATCH docs 1/1] fix #4411: openid: add docs for openid groups support
Date: Sun, 1 Sep 2024 11:55:09 -0500 [thread overview]
Message-ID: <20240901165512.687801-2-thomas@atskinner.net> (raw)
In-Reply-To: <20240901165512.687801-1-thomas@atskinner.net>
Signed-off-by: Thomas Skinner <thomas@atskinner.net>
---
api-viewer/apidata.js | 40 ++++++++++++++++++++++++++++++++++++++++
pveum.adoc | 32 ++++++++++++++++++++++++++++++++
2 files changed, 72 insertions(+)
diff --git a/api-viewer/apidata.js b/api-viewer/apidata.js
index 8ba94e4..0edafd7 100644
--- a/api-viewer/apidata.js
+++ b/api-viewer/apidata.js
@@ -53895,6 +53895,26 @@ const apiSchema = [
"type" : "string",
"typetext" : "<string>"
},
+ "groups-claim" : {
+ "description" : "OpenID claim used to retrieve groups with.",
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "groups-overwrite" : {
+ "default" : 0,
+ "description" : "All groups will be overwritten for the user on login.",
+ "optional" : 1,
+ "type" : "boolean",
+ "typetext" : "<boolean>"
+ },
+ "groups-replace-character" : {
+ "default" : "_",
+ "description" : "Character used to replace any invalid characters in groups from provider.",
+ "optional" : 1,
+ "pattern" : "^[A-Za-z0-9\\.\\-_]$",
+ "type" : "string"
+ },
"issuer-url" : {
"description" : "OpenID Issuer Url",
"maxLength" : 256,
@@ -54233,6 +54253,26 @@ const apiSchema = [
"type" : "string",
"typetext" : "<string>"
},
+ "groups-claim" : {
+ "description" : "OpenID claim used to retrieve groups with.",
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "groups-overwrite" : {
+ "default" : 0,
+ "description" : "All groups will be overwritten for the user on login.",
+ "optional" : 1,
+ "type" : "boolean",
+ "typetext" : "<boolean>"
+ },
+ "groups-replace-character" : {
+ "default" : "_",
+ "description" : "Character used to replace any invalid characters in groups from provider.",
+ "optional" : 1,
+ "pattern" : "^[A-Za-z0-9\\.\\-_]$",
+ "type" : "string"
+ },
"issuer-url" : {
"description" : "OpenID Issuer Url",
"maxLength" : 256,
diff --git a/pveum.adoc b/pveum.adoc
index c115866..0a031cc 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -456,6 +456,16 @@ use the `autocreate` option to automatically add new users.
* `Username Claim` (`username-claim`): OpenID claim used to generate the unique
username (`subject`, `username` or `email`).
+* `Groups Claim` (`groups-claim`): OpenID claim used to retrieve the groups from
+the ID token or userinfo endpoint.
+
+* `Overwrite Groups` (`groups-overwrite`): Overwrite all groups assigned to user
+instead of appending to existing groups (default behavior).
+
+* `Groups Replacement Character` (`groups-replace-character`): Character to
+replace invalid characters in groups names from the OpenID provider. Default
+behavior is to replace each invalid character with an underscore (`'_'`).
+
Username mapping
^^^^^^^^^^^^^^^^
@@ -479,6 +489,28 @@ Another option is to use `email`, which also yields human readable
usernames. Again, only use this setting if the server guarantees the
uniqueness of this attribute.
+Groups mapping
+^^^^^^^^^^^^^^
+
+Specifying the `groups-claim` setting in the OpenID configuration enables group
+mapping functionality. The data provided in the `groups-claim` should be
+a list of strings that correspond to groups that a user should be a member of in
+{pve}. Any groups reported by the OpenID provider that do not exist in {pve} are
+ignored.
+
+By default, groups are appended to the user's existing groups. It may be
+desirable to overwrite any groups that the user is already a member in {pve}
+with those from the OpenID provider. Enabling the `groups-overwrite` setting
+removes all groups from the user in {pve} before adding the groups reported by
+the OpenID provider.
+
+In some cases, OpenID servers may send groups claims which include invalid
+characters for {pve} group IDs. By default, each invalid character is replaced
+with an underscore (`'_'`). To adjust the character used for replacement, adjust
+the `groups-replace-character` setting to any valid character for a {pve} group
+ID (i.e. includes alphanumeric characters and any of the following: `'-'`,
+`'_'`, `'.'`).
+
Examples
^^^^^^^^
--
2.39.2
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
next prev parent reply other threads:[~2024-09-02 8:05 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-09-01 16:55 [pve-devel] [PATCH SERIES openid/access-control/docs/manager] fix #4411: add support for openid groups Thomas Skinner
2024-09-01 16:55 ` Thomas Skinner [this message]
2024-09-01 16:55 ` [pve-devel] [PATCH openid 1/1] fix #4411: openid: add library code for openid groups support Thomas Skinner
2024-09-01 16:55 ` [pve-devel] [PATCH access-control 1/1] fix #4411: openid: add logic " Thomas Skinner
2024-09-01 16:55 ` [pve-devel] [PATCH manager 1/1] fix #4411: openid: add ui config " Thomas Skinner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240901165512.687801-2-thomas@atskinner.net \
--to=thomas@atskinner.net \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox