Manual role changes now blocked at API level when provisioning is active

Summary

Prevents manual role changes when instance or project roles are being managed automatically — either by an SSO provider via SCIM/provisioning, or by expression-based role mapping rules.

Before: The UI disabled role editing in both cases, but the underlying API endpoints (PATCH /users/:id/role and PATCH /projects/:projectId/users/:userId) accepted requests regardless, meaning anyone with API access could bypass the restriction.

After: Both endpoints return 403 Forbidden when the relevant provisioning mode is active. The UI and API are now consistent.

<img width="1850" height="941" alt="image" src="https://github.com/user-attachments/assets/8a443e6c-b6af-45b7-86b4-290b0c0f50f4" />

Changes

• provisioning.service.ee.ts — Two new public methods (isInstanceRoleManaged, isProjectRoleManaged) that combine the SSO provisioning and expression-mapping flags into a single guard check
• users.controller.ts — Guard on PATCH /users/:id/role that throws ForbiddenError when instance roles are managed
• project.controller.ts — Guard on PATCH /projects/:projectId/users/:userId that throws ForbiddenError when project roles are managed
• Frontend — SettingsUsersView.vue and ProjectSettings.vue updated to show distinct info banners for expression mapping vs SSO provider, and to disable editing for both; new i18n strings added
• provisioning.ts (rest-api-client) — scopesUseExpressionMapping added to ProvisioningConfig interface

Related Linear tickets

https://linear.app/n8n/issue/IAM-501

Testing

Prerequisites

• An n8n instance with the N8N_ENV_FEAT_ROLE_MAPPING_STRATEGY=true env var set (for expression mapping tests)
• An owner or admin account to obtain a valid auth cookie/token
• jq installed for pretty-printing JSON responses

---

UI Tests

1. Expression-based mapping — Instance roles (Settings > Users)

1. Set N8N_ENV_FEAT_ROLE_MAPPING_STRATEGY=true and ensure scopesUseExpressionMapping is enabled via PATCH /sso/provisioning/config
2. Navigate to Settings > Users
3. Expected: A blue info banner reads "Instance roles are managed automatically by expression-based role mapping rules. Manual role changes are disabled."
4. Expected: No role dropdown is visible or interactable next to any user row
5. Disable expression mapping, reload — role dropdowns should reappear

2. Expression-based mapping — Project roles (Project > Settings)

1. With expression mapping still active, open any team project and navigate to Settings > Members
2. Expected: A blue info banner reads "Project roles are managed automatically by expression-based role mapping rules. Manual role changes are disabled."
3. Expected: The member search input is disabled and no role dropdowns are editable
4. Expected: The "Add member" control is not functional

3. SSO provisioning — Instance roles (Settings > Users)

1. Disable expression mapping; enable SSO (SAML/OIDC) and set scopesProvisionInstanceRole: true via PATCH /sso/provisioning/config
2. Navigate to Settings > Users
3. Expected: Banner reads "User management and instance roles are controlled by your SSO provider..." (the existing SSO copy, not the expression mapping copy)
4. Expected: Role dropdowns are disabled

4. SSO provisioning — Project roles (Project > Settings)

1. With scopesProvisionProjectRoles: true, open a team project's Settings
2. Expected: Banner reads "User management and project roles are controlled by your SSO provider..."
3. Expected: Member role dropdowns and the add-member input are disabled

5. No provisioning active (baseline)

1. Ensure both expression mapping and SSO provisioning are disabled
2. Navigate to Settings > Users and a team project's Settings
3. Expected: No info banners shown, all role controls are interactive

---

API Tests (cURL)

Replace the placeholders:

• N8N_HOST — your instance URL, e.g. http://localhost:5678
• AUTH_COOKIE — value of the n8n-auth cookie from a logged-in owner session (grab from browser DevTools > Application > Cookies)
• TARGET_USER_ID — ID of any non-owner user (from Settings > Users URL or GET /users)
• PROJECT_ID — ID of a team project (from the project URL)
• PROJECT_MEMBER_ID — ID of a user who is a member of that project

Setup: enable expression-based mapping

curl -s -X PATCH "$N8N_HOST/rest/sso/provisioning/config" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{
    "scopesUseExpressionMapping": true,
    "scopesProvisionInstanceRole": false,
    "scopesProvisionProjectRoles": false,
    "scopesName": "",
    "scopesInstanceRoleClaimName": "",
    "scopesProjectsRolesClaimName": ""
  }' | jq .

Test A: Instance role change blocked (expression mapping)

curl -s -X PATCH "$N8N_HOST/rest/users/$TARGET_USER_ID/role" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{"newRoleName": "global:admin"}' | jq .

Expected response (403):

{
  "status": "error",
  "message": "Instance roles are managed automatically and cannot be changed manually"
}

Test B: Project role change blocked (expression mapping)

curl -s -X PATCH "$N8N_HOST/rest/projects/$PROJECT_ID/users/$PROJECT_MEMBER_ID" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{"role": "project:editor"}' | jq .

Expected response (403):

{
  "status": "error",
  "message": "Project roles are managed automatically and cannot be changed manually"
}

Setup: switch to SSO provisioning mode

curl -s -X PATCH "$N8N_HOST/rest/sso/provisioning/config" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{
    "scopesUseExpressionMapping": false,
    "scopesProvisionInstanceRole": true,
    "scopesProvisionProjectRoles": true,
    "scopesName": "",
    "scopesInstanceRoleClaimName": "",
    "scopesProjectsRolesClaimName": ""
  }' | jq .

Test C: Instance role change blocked (SSO provisioning)

curl -s -X PATCH "$N8N_HOST/rest/users/$TARGET_USER_ID/role" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{"newRoleName": "global:admin"}' | jq .

Expected response (403):

{
  "status": "error",
  "message": "Instance roles are managed automatically and cannot be changed manually"
}

Test D: Project role change blocked (SSO provisioning)

curl -s -X PATCH "$N8N_HOST/rest/projects/$PROJECT_ID/users/$PROJECT_MEMBER_ID" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{"role": "project:editor"}' | jq .

Expected response (403):

{
  "status": "error",
  "message": "Project roles are managed automatically and cannot be changed manually"
}

Test E: Role changes allowed when provisioning is disabled (baseline)

# Disable all provisioning
curl -s -X PATCH "$N8N_HOST/rest/sso/provisioning/config" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{
    "scopesUseExpressionMapping": false,
    "scopesProvisionInstanceRole": false,
    "scopesProvisionProjectRoles": false,
    "scopesName": "",
    "scopesInstanceRoleClaimName": "",
    "scopesProjectsRolesClaimName": ""
  }' | jq .

# Instance role change — should succeed
curl -s -X PATCH "$N8N_HOST/rest/users/$TARGET_USER_ID/role" \
  -H "Content-Type: application/json" \
  -H "Cookie: n8n-auth=$AUTH_COOKIE" \
  -d '{"newRoleName": "global:admin"}' | jq .

Expected response (200):

{
  "data": { "success": true }
}

---

Review / Merge checklist

• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR labeled with Backport to Beta, Backport to Stable, or Backport to v1 if urgent.