Gitpulse
Merged
Size
M
Change Breakdown
Feature70%
Maintenance20%
Refactor10%
#27686feat(editor): Add expression-based role mapping plumbing

Expression-based role mapping lands in SSO settings

Expression-based role mapping lands in SSO settings
CS
cstuncsik
·Apr 7, 2026

SSO administrators gain a fourth provisioning option—expression-based role mapping—that uses rules instead of IdP scopes when enabled via feature flag.

The SSO settings in n8n now support a fourth way to provision user roles: expression-based mapping. When administrators set the N8N_ENV_FEAT_ROLE_MAPPING_RULES environment variable and configure SAML or OIDC, they can select "Expression-based mapping" from the User Role Provisioning dropdown alongside the existing three options. This option toggles off scopes-based provisioning and instead relies on role mapping rules—flexible expressions that assign roles based on IdP attributes. The infrastructure for managing these rules is in place: a state composable tracks instance and project rules with dirty tracking, and an API layer handles CRUD operations and reordering. The dropdown remains unchanged for everyone else.

View Original GitHub Description

Summary

Adds the plumbing for expression-based role mapping UI behind an environment feature flag (N8N_ENV_FEAT_ROLE_MAPPING_RULES). This is PR 1 of 3 for IAM-397.

What this PR does:

  • Adds RoleMappingRuleResponse and related TypeScript types
  • Creates a mocked API layer (useRoleMappingRulesApi) with CRUD + reorder operations — single file to swap for real REST calls when backend is ready
  • Creates a state management composable (useRoleMappingRules) with dirty tracking
  • Adds a 4th option ("Expression-based mapping") to the User Role Provisioning dropdown, gated by useEnvFeatureFlag composable
  • Extends useUserRoleProvisioningForm to handle the new expression_based value

No visible UI change without the env feature flag enabled.

How to test manually

  1. Set N8N_ENV_FEAT_ROLE_MAPPING_RULES=true environment variable (or configure it in backend settings)
  2. Go to Settings → SSO → configure SAML or OIDC
  3. The "User role provisioning" dropdown should now show a 4th option: "Expression-based mapping"
  4. Without the flag, only the original 3 options appear

Key decisions for reviewers

  • Env feature flag — uses useEnvFeatureFlag().check('ROLE_MAPPING_RULES') (not PostHog), consistent with the project's EnvFeatureFlag pattern
  • Mocked API layer: useRoleMappingRulesApi.ts uses in-memory storage with 200ms simulated latency. This is the single swap point — when the backend lands, only this file changes
  • Reorder strategy: Frontend sends a full ordered ID list per type. The backend team is deciding between bulk reorder endpoint, swap endpoint, or float-based ordering. The frontend is decoupled from this choice
  • expression_based and scopes provisioning: When expression-based is selected, scopes-based provisioning flags are set to false — it uses role mapping rules instead of IdP scopes
  • Config reload: Currently getUserRoleProvisioningValueFromConfig doesn't detect expression-based from the backend config (no field exists yet). On reload it falls back to 'disabled'. Acceptable for the mock phase

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/IAM-481 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)
© 2026 · via Gitpulse