From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id DDB731FF170 for ; Mon, 2 Sep 2024 10:05:39 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id F0B15368F4; Mon, 2 Sep 2024 10:05:49 +0200 (CEST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725209724; x=1725814524; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=lqjSHfkGbmNV6a+G4VbrlyTJgiXUhxp9i6YcjfMvCdU=; b=lzAd0xZQ/hsEyhRNamlPAOxBFoRjUZmB8ubQi04T8r/wppAarF4HUdLyO8kGU7lkcW m/bFroTFqi8pkYdhHk+XMvq0oDhNI42s4iNcsqyWX9PbaQsnQSGVpNl8JTu8t8WyLUHa SlZogctDWNwx6JI7IqCiCsIW2jTEZEc+yNRWb5Vm5nZzDbjzLg+anqlSoivxt4ODcf56 bgVyywdN8yahxiagCAJswm/lc7Bz8Nwhj+YjpaZbzcuoZHX+BGSLbuTgpbDjrnWBB2f8 JnKq5YMqDDPDd9z45hk3MNO2fCEwvA17DXrWEjDbXv/fS5v4moZavrZyY95jGHSTpKIA sWQA== X-Gm-Message-State: AOJu0Ywiqp7boDwzp5NWiow1Hd+N/D2gpf37uV8SLlCrE07P4w8JlBkJ ixvEMjs1ROP3ysmQejNGALl/Q16zHnNmrKLHyJAlIX5srCWTBwZUfSr56w== X-Google-Smtp-Source: AGHT+IHTWU/fv0a8IYcy0kpNZoUQsOyoJRWcRFIMLDvHvdFLc9FDTO7m/HS7JX97efxxPS7ddaDYWg== X-Received: by 2002:a05:690c:2b12:b0:6d5:b062:4beb with SMTP id 00721157ae682-6d5b062520cmr24910527b3.16.1725209723541; Sun, 01 Sep 2024 09:55:23 -0700 (PDT) From: Thomas Skinner To: pve-devel@lists.proxmox.com Date: Sun, 1 Sep 2024 11:55:09 -0500 Message-Id: <20240901165512.687801-2-thomas@atskinner.net> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240901165512.687801-1-thomas@atskinner.net> References: <20240901165512.687801-1-thomas@atskinner.net> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.002 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 FREEMAIL_FORGED_FROMDOMAIN 0.001 2nd level domains in From and EnvelopeFrom freemail headers are different FREEMAIL_FROM 0.001 Sender email is commonly abused enduser mail provider HEADER_FROM_DIFFERENT_DOMAINS 0.25 From and EnvelopeFrom 2nd level mail domains are different KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_NONE -0.0001 Sender listed at https://www.dnswl.org/, no trust RCVD_IN_MSPIKE_H2 -0.001 Average reputation (+2) SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - X-Mailman-Approved-At: Mon, 02 Sep 2024 10:05:47 +0200 Subject: [pve-devel] [PATCH docs 1/1] fix #4411: openid: add docs for openid groups support X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Cc: Thomas Skinner Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" Signed-off-by: Thomas Skinner --- 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" : "" }, + "groups-claim" : { + "description" : "OpenID claim used to retrieve groups with.", + "optional" : 1, + "type" : "string", + "typetext" : "" + }, + "groups-overwrite" : { + "default" : 0, + "description" : "All groups will be overwritten for the user on login.", + "optional" : 1, + "type" : "boolean", + "typetext" : "" + }, + "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" : "" }, + "groups-claim" : { + "description" : "OpenID claim used to retrieve groups with.", + "optional" : 1, + "type" : "string", + "typetext" : "" + }, + "groups-overwrite" : { + "default" : 0, + "description" : "All groups will be overwritten for the user on login.", + "optional" : 1, + "type" : "boolean", + "typetext" : "" + }, + "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