Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

Add a basic UI to edit group synchronization via OIDC

Jan Sandbrink86ba4312d04f
diff --git a/config/initializers/feature_decisions.rb b/config/initializers/feature_decisions.rb
index 0ed017623b8..7cc56a2daea 100644
--- a/config/initializers/feature_decisions.rb
+++ b/config/initializers/feature_decisions.rb
@@ -47,6 +47,9 @@ OpenProject::FeatureDecisions.add :built_in_oauth_applications,
OpenProject::FeatureDecisions.add :calculated_value_project_attribute,
description: "Allows the use of calculated values as a project attribute."
+OpenProject::FeatureDecisions.add :oidc_group_sync,
+ description: "Allows to synchronize groups from OpenID Connect providers"
+
OpenProject::FeatureDecisions.add :scim_api,
description: "Enables SCIM API.",
force_active: true
diff --git a/config/static_links.yml b/config/static_links.yml
index 11f3686fc78..ea4aea50a98 100644
--- a/config/static_links.yml
+++ b/config/static_links.yml
@@ -155,9 +155,11 @@ sysadmin_docs:
oidc:
href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/
oidc_acr_values:
- href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/#step-7-claims
+ href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/#step-8-claims
oidc_claims:
- href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/#step-7-claims
+ href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/#step-8-claims
+ oidc_groups:
+ href: https://www.openproject.org/docs/system-admin-guide/authentication/openid-providers/#step-7-group-mapping
saml:
href: https://www.openproject.org/docs/system-admin-guide/authentication/saml/
scim:
diff --git a/docs/system-admin-guide/authentication/openid-providers/README.md b/docs/system-admin-guide/authentication/openid-providers/README.md
index ea9f5489113..4a76b7666d7 100644
--- a/docs/system-admin-guide/authentication/openid-providers/README.md
+++ b/docs/system-admin-guide/authentication/openid-providers/README.md
@@ -7,7 +7,7 @@ keywords: OpenID providers
---
# OpenID providers (Enterprise add-on)
-> [!IMPORTANT]
+> [!IMPORTANT]
> OpenID Connect providers is an Enterprise add-on. If you do not see the button you will have to activate the Enterprise edition first.
| Topic | Content |
@@ -23,7 +23,7 @@ To activate and configure OpenID providers in OpenProject, navigate to *Administ
To add a new OpenID provider, click the green **+ OpenID provider** button.
-![OpenIDprovider selection in OpenProject administration](openproject_system-admin-guide_authentication_openid_provider_empty.png)
+![OpenIDprovider selection in OpenProject administration](openproject_system-admin-guide_authentication_openid_provider_empty.png)
@@ -84,7 +84,7 @@ After pressing **CREATE** you will see a following pop-up window.
### Step 3: Add Google as an OpenID Provider to OpenProject
1. Login as OpenProject Administrator
-2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
+2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
- **Click** the green *+ OpenID Connect provider* button
- **Choose** Choose the Option Google
- Set a **Display Name**, this is the name of the login button shown to users.
@@ -148,7 +148,7 @@ The steps are as follows:
![Azure Active Directory New Client Secret](07-client-secret.png)
-9. A secret should have been generated and will be displayed on the page.
+9. A secret should have been generated and will be displayed on the page.
> [!IMPORTANT]
> Make sure to save it because it will only be displayed once.
@@ -162,7 +162,7 @@ At the end of this step, you should have a copy of the Application client ID as
Next, you need to create the OpenID Connect provider in OpenProject:
1. Login as OpenProject Administrator
-2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
+2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
- **Click** the green *+ OpenID Connect provider* button
- **Choose** Choose the option **Microsoft Entra**
- Set display name **Microsoft Entra**. Please note that if you change this value, the redirect URI in step 1) might change. The redirect URI is shown in the side panel on the right side once you saved the configuration.
@@ -185,7 +185,7 @@ Starting with OpenProject 15.0., you can also create custom OpenID Connect provi
To start creating a custom provider, please follow these steps:
1. Login as OpenProject Administrator
-2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
+2. Navigate to *Administration* -> *Authentication* and choose -> *OpenID providers*.
- **Click** the green *+ OpenID Connect provider* button
- **Choose** the *Option* **Custom**
@@ -235,7 +235,35 @@ If you need to set some of these values, enter the attribute key used/returned i
For example: Keycloak allows you to map custom properties of the user. This allows you to specify a login with, e.g, `preferred_username` userinfo. In this case, you would fill out `Mapping for: Username` with that attribute returned in the userinfo JSON response.
-#### Step 7: Claims
+#### Step 7: Group mapping
+
+> [!IMPORTANT]
+> Group mapping is an experimental feature that's not yet intended for production usage. It must be enabled on the page for experimental
+> features of your OpenProject instance (found under `/admin/settings/experimental`). Future versions might change this feature in a breaking
+> way, as we still look for user feedback on this feature.
+
+OpenProject can optionally synchronize groups of users when they log in. If you want to enable this, you have to enable the checkbox
+"Synchronize groups". OpenProject will expect a claim with an array of group names that the user is a member of. By default this claim
+is expected to be named `groups`, but you can change this if desired.
+
+The default behaviour of OpenProject is to create a new group for each unknown group listed in this claim. It will match existing groups
+by their name before creating a new group. You can later rename groups created this way in the group management UI, they will still be linked
+to the ID with which they are referenced in OpenID Connect claims and recognized that way.
+
+##### Matching groups with regular expressions
+
+For advanced use cases, it's possible to filter which groups will be imported into OpenProject and which part of the group name will be considered.
+
+The input under "Pattern (regular expression)" expects a list of regular expressions that will be used to match against the name of a group. If
+the group name matches one of the regular expressions, it will be synchronized. If it matches none of the expressions, it will not be synchronized.
+
+The match groups inside the first matching regular expression are used to extract the name of the imported group. For example if groups in your identity
+provider are called `gA`, `gB` and `gC`, and you only want to extract the group names "A", "B" and "C", you could use a regular expression of `^g([A-Z])$`. The `^` and `$` ensure that only full group names are matched, otherwise it would also be possible to match on parts of the group name.
+
+OpenProject parses regular expressions using syntax accepted by the Ruby programming language. One good online resource to understand
+Ruby regular expressions is [Rubular](https://rubular.com/).
+
+#### Step 8: Claims
You can optionally request [claims](https://openid.net/specs/openid-connect-core-1_0-final.html#Claims) for both the id_token and userinfo endpoint. Keep in mind that currently only claims requested for the id_token returned with the authorize response are validated. That means that the authentication will fail if a requested essential claim is not returned.
@@ -374,7 +402,7 @@ OPENPROJECT_OPENID__CONNECT_OKTA_IDENTIFIER="<identifier or client id>"
Underscores in option names must be escaped by doubling them. So make sure to really do use two consecutive underscores in `DISPLAY__NAME`, `TOKEN__ENDPOINT` and so forth
-Use the following configuration as a template for your configuration.
+Use the following configuration as a template for your configuration.
> [!NOTE]
>
diff --git a/frontend/src/stimulus/controllers/dynamic/openid-connect/group-sync-form.controller.ts b/frontend/src/stimulus/controllers/dynamic/openid-connect/group-sync-form.controller.ts
new file mode 100644
index 00000000000..ede1e7993d0
--- /dev/null
+++ b/frontend/src/stimulus/controllers/dynamic/openid-connect/group-sync-form.controller.ts
@@ -0,0 +1,61 @@
+/*
+ * -- copyright
+ * OpenProject is an open source project management software.
+ * Copyright (C) the OpenProject GmbH
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License version 3.
+ *
+ * OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+ * Copyright (C) 2006-2013 Jean-Philippe Lang
+ * Copyright (C) 2010-2013 the ChiliProject Team
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * See COPYRIGHT and LICENSE files for more details.
+ * ++
+ */
+
+import { Controller } from '@hotwired/stimulus';
+
+export default class GroupSyncFormController extends Controller {
+ static targets = [
+ 'inputsWrapper',
+ 'enabledCheckbox',
+ ];
+
+ declare readonly inputsWrapperTarget:HTMLDivElement;
+ declare readonly enabledCheckboxTarget:HTMLInputElement;
+
+ connect() {
+ this.updateFormInputs();
+ }
+
+ updateFormInputs() {
+ if (this.enabledCheckboxTarget.checked) {
+ this.showGroupSyncInputs();
+ } else {
+ this.hideGroupSyncInputs();
+ }
+ }
+
+ showGroupSyncInputs() {
+ this.inputsWrapperTarget.classList.remove('d-none');
+ }
+
+ hideGroupSyncInputs() {
+ this.inputsWrapperTarget.classList.add('d-none');
+ }
+}
diff --git a/modules/openid_connect/app/components/openid_connect/providers/base_form.rb b/modules/openid_connect/app/components/openid_connect/providers/base_form.rb
index 1fc6b45e43b..754007817f4 100644
--- a/modules/openid_connect/app/components/openid_connect/providers/base_form.rb
+++ b/modules/openid_connect/app/components/openid_connect/providers/base_form.rb
@@ -33,6 +33,12 @@ module OpenIDConnect
class BaseForm < ApplicationForm
attr_reader :provider
+ class << self
+ def form_data
+ {}
+ end
+ end
+
def initialize(provider:)
super()
@provider = provider
diff --git a/modules/openid_connect/app/components/openid_connect/providers/group_mapping_form.rb b/modules/openid_connect/app/components/openid_connect/providers/group_mapping_form.rb
new file mode 100644
index 00000000000..601845d9a1a
--- /dev/null
+++ b/modules/openid_connect/app/components/openid_connect/providers/group_mapping_form.rb
@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module OpenIDConnect
+ module Providers
+ class GroupMappingForm < BaseForm
+ include Redmine::I18n
+
+ class << self
+ def form_data
+ {
+ controller: "openid-connect--group-sync-form"
+ }
+ end
+ end
+
+ form do |f|
+ f.check_box(
+ name: :sync_groups,
+ label: OpenIDConnect::Provider.human_attribute_name(:sync_groups),
+ caption: I18n.t("openid_connect.instructions.group_sync"),
+ disabled: provider.seeded_from_env?,
+ data: {
+ action: "openid-connect--group-sync-form#updateFormInputs",
+ "openid-connect--group-sync-form-target": "enabledCheckbox"
+ }
+ )
+
+ f.group(data: { "openid-connect--group-sync-form-target": "inputsWrapper" }) do |group|
+ group.text_field(
+ name: :groups_claim,
+ label: OpenIDConnect::Provider.human_attribute_name(:groups_claim),
+ caption: I18n.t("openid_connect.instructions.groups_claim"),
+ input_width: :large,
+ disabled: provider.seeded_from_env?
+ )
+
+ group.html_content do
+ render(Primer::Beta::Text.new) { I18n.t("openid_connect.instructions.group_regexes_detail").html_safe }
+ end
+
+ group.text_area(
+ name: :group_regexes,
+ rows: 5,
+ label: I18n.t("openid_connect.providers.label_group_regexes"),
+ caption: link_translate("openid_connect.instructions.group_regexes", links: {
+ docs_url: ::OpenProject::Static::Links.url_for(:sysadmin_docs, :oidc_groups)
+ }),
+ disabled: provider.seeded_from_env?,
+ required: false,
+ input_width: :large,
+ value: model.group_regexes.join("\n")
+ )
+ end
+ end
+ end
+ end
+end
diff --git a/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.html.erb b/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.html.erb
index 34ed0e91d45..292727ea5de 100644
--- a/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.html.erb
+++ b/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.html.erb
@@ -3,7 +3,8 @@
id: "openid-connect-providers-edit-form",
model: provider,
url:,
- method: form_method
+ method: form_method,
+ data: form_data
) do |form|
flex_layout do |flex|
if @heading
diff --git a/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.rb b/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.rb
index a1592a14226..f8afc277d75 100644
--- a/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.rb
+++ b/modules/openid_connect/app/components/openid_connect/providers/sections/form_component.rb
@@ -32,6 +32,8 @@ module OpenIDConnect::Providers::Sections
class FormComponent < ::Saml::Providers::Sections::SectionComponent
attr_reader :edit_state, :next_edit_state, :edit_mode, :fetch_metadata
+ delegate :form_data, to: :@form_class
+
def initialize(provider,
edit_state:,
form_class:,
diff --git a/modules/openid_connect/app/components/openid_connect/providers/view_component.html.erb b/modules/openid_connect/app/components/openid_connect/providers/view_component.html.erb
index 3509c4ec06e..2f5a23c8c06 100644
--- a/modules/openid_connect/app/components/openid_connect/providers/view_component.html.erb
+++ b/modules/openid_connect/app/components/openid_connect/providers/view_component.html.erb
@@ -240,7 +240,7 @@
provider,
form_class: OpenIDConnect::Providers::AttributeMappingForm,
edit_state:,
- next_edit_state: :claims,
+ next_edit_state: OpenProject::FeatureDecisions.oidc_group_sync_active? ? :group_mapping : :claims,
edit_mode:,
heading: nil
)
@@ -260,6 +260,33 @@
end
end
+ if OpenProject::FeatureDecisions.oidc_group_sync_active?
+ component.with_row(scheme: :default) do
+ if edit_state == :group_mapping
+ render(
+ OpenIDConnect::Providers::Sections::FormComponent.new(
+ provider,
+ form_class: OpenIDConnect::Providers::GroupMappingForm,
+ edit_state:,
+ next_edit_state: :claims,
+ edit_mode:,
+ heading: nil
+ )
+ )
+ else
+ render(
+ OpenIDConnect::Providers::Sections::ShowComponent.new(
+ provider,
+ target_state: :group_mapping,
+ view_mode:,
+ heading: t("openid_connect.providers.label_group_mapping"),
+ description: t("openid_connect.providers.section_texts.group_mapping"),
+ )
+ )
+ end
+ end
+ end
+
component.with_row(scheme: :default) do
if edit_state == :claims
render(
diff --git a/modules/openid_connect/app/services/openid_connect/providers/set_attributes_service.rb b/modules/openid_connect/app/services/openid_connect/providers/set_attributes_service.rb
index 3147619fd0a..1f1014524a3 100644
--- a/modules/openid_connect/app/services/openid_connect/providers/set_attributes_service.rb
+++ b/modules/openid_connect/app/services/openid_connect/providers/set_attributes_service.rb
@@ -46,17 +46,20 @@ module OpenIDConnect
super
- update_grant_types_supported if params.key?(:grant_types_supported)
+ update_string_list(:grant_types_supported, delimiter: " ")
+ update_string_list(:group_regexes, delimiter: "\n")
update_available_state
end
- # This is a workaround for a non-ideal UI
- # We only offer users to edit the supported grant types in a text input field,
- # though they are indeed editing a list of grants.
- def update_grant_types_supported
- return unless params[:grant_types_supported].is_a? String
+ # This is a workaround for UI where users edit a single input field or text area, but are indeed editing
+ # an array of items
+ def update_string_list(attribute, delimiter:)
+ return unless params[attribute].is_a? String
- model.grant_types_supported = params[:grant_types_supported].split
+ model.public_send(
+ "#{attribute}=",
+ params[attribute].split(delimiter)
+ )
end
def update_available_state
diff --git a/modules/openid_connect/config/locales/en.yml b/modules/openid_connect/config/locales/en.yml
index 7087d6a2eb0..f13294da788 100644
--- a/modules/openid_connect/config/locales/en.yml
+++ b/modules/openid_connect/config/locales/en.yml
@@ -13,8 +13,10 @@ en:
display_name: Display name
client_id: Client ID
client_secret: Client secret
+ groups_claim: Groups claim
secret: Secret
scope: Scope
+ sync_groups: Synchronize groups
grant_types_supported: Supported grant types
limit_self_registration: Limit self registration
authorization_endpoint: Authorization endpoint
@@ -59,6 +61,10 @@ en:
instructions:
redirect_url: This is the redirect URL that the OpenID Connect provider should use to redirect back to OpenProject after a successful login.
endpoint_url: The endpoint URL given to you by the OpenID Connect provider
+ group_regexes: One regular expression pattern per line. Please read [the documentation](docs_url) for more information on how to do this.
+ group_regexes_detail: Define patterns using regular expressions to match group names from the groups claim. For example, entering a pattern like <code>^Level1/Level2/([\w/]+)$</code> will extract the group “Groupname/SubGroup” from a response including “Level1/Level2/GroupName/SubGroup”.
+ group_sync: Automatically extract and synchronise group membership information from the identity provider.
+ groups_claim: Specify the name of the claim that's expected to indicate the group names that the user is a member of.
metadata_none: I don't have this information
metadata_url: I have a discovery endpoint URL
client_id: This is the client ID given to you by your OpenID Connect provider
@@ -103,6 +109,8 @@ en:
label_edit: Edit OpenID provider %{name}
label_empty_title: No OpenID providers configured yet.
label_empty_description: Add a provider to see them here.
+ label_group_mapping: Group mapping
+ label_group_regexes: Pattern (regular expression)
label_metadata: OpenID Connect Discovery Endpoint
label_automatic_configuration: Automatic configuration
label_optional_configuration: Optional configuration
@@ -115,6 +123,7 @@ en:
plural: OpenID providers
singular: OpenID provider
section_texts:
+ group_mapping: Map group names provided by the identity provider to groups in OpenProject.
metadata: Pre-fill configuration using an OpenID Connect discovery endpoint URL
metadata_form_banner: Editing the discovery endpoint may override existing pre-filled metadata values.
metadata_form_title: OpenID Connect Discovery endpoint
diff --git a/modules/openid_connect/spec/features/administration/oidc_custom_crud_spec.rb b/modules/openid_connect/spec/features/administration/oidc_custom_crud_spec.rb
index 7b50d22e60d..616e9a1eda2 100644
--- a/modules/openid_connect/spec/features/administration/oidc_custom_crud_spec.rb
+++ b/modules/openid_connect/spec/features/administration/oidc_custom_crud_spec.rb
@@ -40,7 +40,7 @@ RSpec.describe "OIDC administration CRUD",
login_as(user)
end
- context "with EE", with_ee: %i[sso_auth_providers] do
+ context "with EE", with_ee: %i[sso_auth_providers], with_flag: { oidc_group_sync: true } do
it "can manage OIDC providers through the UI" do
visit "/admin/openid_connect/providers"
expect(page).to have_text "No OpenID providers configured yet."
@@ -78,6 +78,20 @@ RSpec.describe "OIDC administration CRUD",
click_link_or_button "Continue"
+ # Groups
+ enabled_checkbox = page.find_by_id("openid_connect_provider_sync_groups")
+ expect(enabled_checkbox).not_to be_checked
+ expect(page).to have_no_field " Groups claim"
+ expect(page).to have_no_field "Pattern (regular expression)"
+
+ check "Synchronize groups"
+ expect(page).to have_field("Groups claim", with: "groups")
+ expect(page).to have_field("Pattern (regular expression)", with: "")
+ fill_in "Groups claim", with: "custom-groups"
+ fill_in "Pattern (regular expression)", with: "Foo\nBar"
+
+ click_link_or_button "Continue"
+
# Claims
fill_in "Claims", with: '{"foo": "bar"}'
fill_in "ACR values", with: "foo bar"
@@ -112,6 +126,9 @@ RSpec.describe "OIDC administration CRUD",
expect(provider.mapping_first_name).to eq "myName"
expect(provider.mapping_last_name).to eq "myLastName"
+ expect(provider.groups_claim).to eq("custom-groups")
+ expect(provider.group_regexes).to eq(["Foo", "Bar"])
+
click_link_or_button "Delete"
# Confirm the deletion
# Without confirmation, the button is disabled