SSO role mapping gains project rules and save flow

cstuncsik

·Apr 8, 2026·#27689feat(editor): Add project rules, fallback role, remove mapping, save flow

n8n's SSO settings now support expression-based role mapping at the project level. Admins can assign project roles (Admin, Editor, Viewer) based on identity provider claims, with fallback defaults and a clean removal option.

Enterprise teams managing multiple n8n projects often need granular access control beyond instance-wide roles. Until now, SSO role mapping could only assign instance-level permissions.

This PR completes the expression-based role mapping UI by adding a project rules section alongside the existing instance rules. Each project rule includes an expression input, a project multi-select dropdown, and role options for Admin, Editor, or Viewer. A fallback instance role selector sets the default when no rules match.

The "Remove mapping" button allows admins to switch back to n8n's managed provisioning with a confirmation dialog. Dirty detection is integrated into both SAML and OIDC save flows, so the Save button correctly enables when rule changes are pending.

The work is part of a three-PR effort (IAM-397) to build out the full role mapping settings UI for enterprise SSO configuration.

View Original GitHub DescriptionFact Check

Summary

Completes the expression-based role mapping UI. This is PR 3 of 3 for IAM-397.

Stacked on: #27688 (instance rules editor) → #27686 (plumbing)

What this PR does:

Project role rules section — same pattern as instance rules, but with project multi-select dropdown and project-scoped role options (project:admin, project:editor, project:viewer)
Fallback instance role selector — dropdown for the default role when no instance rule matches
"Remove mapping" button with confirmation modal — switches back to "Managed in n8n" provisioning
Dirty detection integrated into both SAML and OIDC save flows — Save button enables when rules change
Save flow — calls roleMappingRuleEditor.save() alongside existing provisioning config save
RuleRow.vue extended with type and projects props for polymorphic instance/project rendering

How to test manually

Set N8N_ENV_FEAT_ROLE_MAPPING_RULES=true environment variable
Settings → SSO → SAML or OIDC → select "Expression-based mapping"
Instance rules: Add rules, set expressions and roles (Admin/Member), drag to reorder, toggle on/off, delete
Fallback role: Change the fallback instance role dropdown
Project rules: Add rules — each row has expression input + project multi-select + role dropdown (Admin/Editor/Viewer)
Save flow: Make changes → Save button becomes enabled → click Save
Remove mapping: Click "Remove mapping" → confirmation modal → confirm → switches back to "Managed in n8n"
Verify the same behavior works in both SAML and OIDC forms

Key decisions for reviewers

Env feature flag — gated by N8N_ENV_FEAT_ROLE_MAPPING_RULES via useEnvFeatureFlag composable (set in PR 1)
Mock projects list — RoleMappingRuleEditor uses a hardcoded availableProjects array. Will be replaced with a real projects API call
Polymorphic RuleRow — single component handles both instance and project rules via type prop. Project rules add a multi-select project dropdown before the role dropdown
Dirty detection — SAML form checks roleMappingRuleEditorRef.value?.isDirty in isSaveEnabled; OIDC form adds !roleMappingRuleEditorRef.value?.isDirty to cannotSaveOidcSettings (inverted logic matches existing pattern)
Remove mapping uses useMessage().confirm() pattern consistent with existing SSO confirmation dialogs
defineExpose — editor exposes isDirty and save() so parent forms can integrate without coupling to the composable

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/IAM-483 https://linear.app/n8n/issue/IAM-397

Review / Merge checklist

PR title and summary are descriptive. (conventions)
Docs updated or follow-up ticket created.
Tests included.
PR Labeled with release/backport (if the PR is an urgent fix that needs to be backported)