From 2015051e587a0b7320362bec6424424978718aac Mon Sep 17 00:00:00 2001 From: Alex Petric Date: Mon, 16 Mar 2026 17:10:14 -0400 Subject: [PATCH] docs: add instance-level role support for instance groups Document the new ability to assign superadmin/devops roles to instance groups, role precedence rules, and the "Set by instance group" indicator in instance settings. Co-Authored-By: Claude Opus 4.6 --- docs/advanced/18_instance_settings/index.mdx | 4 +++- docs/core_concepts/16_roles_and_permissions/index.mdx | 11 +++++++++++ docs/core_concepts/8_groups_and_folders/index.mdx | 8 ++++++++ docs/misc/14_saml_and_scim/index.md | 11 +++++++++++ 4 files changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/advanced/18_instance_settings/index.mdx b/docs/advanced/18_instance_settings/index.mdx index 5d253d012..70c698ef2 100644 --- a/docs/advanced/18_instance_settings/index.mdx +++ b/docs/advanced/18_instance_settings/index.mdx @@ -30,6 +30,8 @@ Global Users are users of the Windmill instance. They are not associated with an From there you can manually add a user to the instance, giving an email and a password. Users can be set to User, [Devops](../../core_concepts/16_roles_and_permissions/index.mdx#devops) or Superadmin [roles](../../core_concepts/16_roles_and_permissions/index.mdx#superadmin). +When a user's role is set by an [instance group](../../core_concepts/8_groups_and_folders/index.mdx#instance-level-roles), a "Set by instance group" indicator appears next to the role toggle. You can still upgrade a user to a higher role manually (e.g. from group-assigned devops to superadmin), but demoting to "User" requires removing the user from the instance group. See [instance-level roles via instance groups](../../core_concepts/16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups) for details. + You can also enable automatic username creation from emails. Usernames will be shared accross workspaces. We recommend setting it to avoid duplicated usernames. A more common way to add users is to use [SSO/OAuth](#authoauth). @@ -518,4 +520,4 @@ When minimal telemetry is enabled, the following is sent: When minimal telemetry is disabled, the following is also collected: - job usage (language, total duration, count) -You can "Send usage" to manually send usage data to Windmill and monitor it from the [Customer portal](../../misc/7_plans_details/index.mdx#windmill-customer-portal). You can also "Download usage" to get an encrypted copy of the telemetry data as a `.enc` file. This is useful for air-gapped instances that cannot send telemetry directly — the encrypted file can be sent manually to Windmill. +You can "Send usage" to manually send usage data to Windmill and monitor it from the [Customer portal](../../misc/7_plans_details/index.mdx#windmill-customer-portal). You can also "Download usage" to get an encrypted copy of the telemetry data as a `.enc` file. This is useful for air-gapped instances that cannot send \ No newline at end of file diff --git a/docs/core_concepts/16_roles_and_permissions/index.mdx b/docs/core_concepts/16_roles_and_permissions/index.mdx index a7a0eac88..7a131c8df 100644 --- a/docs/core_concepts/16_roles_and_permissions/index.mdx +++ b/docs/core_concepts/16_roles_and_permissions/index.mdx @@ -55,6 +55,17 @@ The superadmin role has the highest level of access and can manage the entire Wi The devops role is also set at the instance level. Conceptually, it can be understood as a "readonly Superadmin". Devops users have read rights over what is usually only visible to [superadmins](#superadmin), such as [Service Logs](../36_service_logs/index.mdx) or [Critical Alerts](../37_critical_alerts/index.mdx) while keeping write operations to a minimum. Contrary to the superadmin, this role does not supersede other roles like [workspace admins](#admin). +### Instance-level roles via instance groups + +Superadmin and devops roles can also be assigned to [instance groups](../8_groups_and_folders/index.mdx#instance-groups). When an instance group has an instance role, all members of that group automatically receive that role. This is particularly useful with [SCIM](../../misc/14_saml_and_scim/index.md#scim) — for example, an "infrastructure" group in your identity provider can automatically grant devops access to all its members. + +**Role precedence rules:** +- If a user belongs to multiple instance groups with different roles, the highest role wins (superadmin > devops > user). +- Manually-set elevated roles (superadmin or devops) always take precedence over group-assigned roles. A superadmin manually promoted by another superadmin will not be demoted if their instance group only grants devops. +- To demote a user whose role is set by an instance group, the user must be removed from the group (or the group's instance role must be changed). + +In the [instance settings](../../advanced/18_instance_settings/index.mdx) users list, roles set by instance groups are indicated with a "Set by instance group" label. + ### Admin At the [workspace](#workspace) level, admins have the ability to manage a specific Windmill workspace and users within that workspace. They can see and edit all scripts, flows, apps, and other entities within the workspace. Admins have the power to create, modify, and delete entities and can manage permissions within the workspace. diff --git a/docs/core_concepts/8_groups_and_folders/index.mdx b/docs/core_concepts/8_groups_and_folders/index.mdx index a25560ed8..aefcc9b7e 100644 --- a/docs/core_concepts/8_groups_and_folders/index.mdx +++ b/docs/core_concepts/8_groups_and_folders/index.mdx @@ -83,6 +83,14 @@ Instance groups are a special type of group that are automatically managed and s 3. **User assignment**: When users are added to groups in your identity provider, they automatically gain the corresponding group membership in Windmill 4. **Permission inheritance**: Instance groups can be assigned to folders and resources just like regular groups, inheriting the same permission levels (Viewer, Writer, Admin) +### Instance-level roles + +Instance groups can be assigned an **instance-level role** (superadmin or devops). All members of the group automatically receive that role. This is configured in the instance group editor drawer, accessible from the groups page. + +When a user belongs to multiple instance groups with different instance roles, the highest role takes precedence (superadmin > devops > user). Manually elevated roles (set by a superadmin in the instance settings) always take priority over group-assigned roles. + +For more details on role precedence, see [Roles and Permissions](../16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups). + ### Benefits - **Reduced administrative overhead**: No need to manually create and manage groups in Windmill diff --git a/docs/misc/14_saml_and_scim/index.md b/docs/misc/14_saml_and_scim/index.md index c31855a3b..b449abea8 100644 --- a/docs/misc/14_saml_and_scim/index.md +++ b/docs/misc/14_saml_and_scim/index.md @@ -150,6 +150,17 @@ When SCIM is properly configured, groups from your identity provider will be aut Instance groups appear in your Windmill groups interface with a special designation, and can be assigned permissions to folders and resources just like regular groups. This eliminates the need for manual group management while maintaining full integration with Windmill's permission system. +### Instance-level roles + +Instance groups can be assigned an **instance-level role** (superadmin or devops) from the instance group editor. When set, all members of the group automatically receive that role. This allows you to manage instance-level access through your identity provider — for example, assigning devops access to an "infrastructure" group or superadmin access to a "platform-admins" group. + +Role changes propagate automatically when: +- A user is added to or removed from the group via SCIM +- The group's instance role is changed +- The group is deleted + +Manually elevated roles always take precedence — if a superadmin promotes a user manually, group changes won't demote them. For full precedence rules, see [Roles and Permissions](../../core_concepts/16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups). + ### Workspace auto-assignment Instance groups can be automatically mapped to workspaces with specific role assignments. This powerful feature allows you to: