Skip to content

Azure AD SAML setup#

This document provides instructions for configuring Azure AD to send role information to n8n via SAML attributes. This enables automatic role assignment based on Azure AD group membership.

Prerequisites#

You need an Azure AD account with access to Enterprise Applications, and the redirect URL and entity ID from n8n's SAML settings.

Read the Set up SAML guide first.

What n8n requires#

n8n expects a custom SAML attribute to be included in the SAML assertion:

Attribute Name Data Type Purpose
n8n_instance_role String Controls the user's global role in n8n

Valid values for n8n_instance_role:

Value Description
global:owner Full instance owner access
global:admin Administrator access
global:member Regular member access (default if not specified)
global:chatUser Restricted, non-technical role in n8n designed for securely interacting with AI agents via the Chat Hub interface

Setup#

Step 1: Configure Standard SAML Attributes

  1. In your Azure AD portal, navigate to your n8n Enterprise Application.
  2. Go to Single sign-on > Attributes & Claims.

  3. Ensure these standard attributes are configured:

    Claim Name Source Attribute
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress user.mail
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname user.givenname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname user.surname
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn user.userprincipalname

Step 2: Add the n8n_instance_role Claim

This claim uses conditional logic to emit different role values based on Azure AD group membership.

  1. In Attributes & Claims, click Add new claim.
  2. Configure the basic settings:
    • Name: n8n_instance_role
    • Namespace: leave empty
    • Source: Attribute
  3. Expand Claim conditions and click Add condition.

  4. Add conditions for each Azure AD group (in priority order):

    User Type Scoped Groups Source Value
    Members n8n-chatusers Attribute global:chatUser
    Members n8n-users Attribute global:member
    Members n8n-admins Attribute global:admin
    Members n8n-owners Attribute global:owner

Condition order

Conditions are evaluated in order. Place the most privileged group (owners) at the end.

  1. Click Save.

Testing the configuration#

  1. In n8n, go to Settings > SSO.
  2. Set Role assignment to Instance roles via SSO.
  3. Set Role mapping method to Map rules on your IdP.
  4. Click Test settings.
  5. Verify the SAML response shows the correct n8n_instance_role value.

Troubleshooting#

Claim not appearing in SAML response

  • Verify the user is a member of at least one of the configured groups.
  • Check that the groups are assigned to the Enterprise Application.
  • Ensure conditions are configured with Attribute as the source.
  • Use a browser extension plugin like 'SAML Chrome Panel' to view the application SAML response.

User gets wrong role

  • Check condition order (most privileged group should be last).

Assigning multiple project roles using app roles instead of group-based claims#

Using Azure AD group-based claim conditions for assigning multiple project roles to users often results in only the first matching group claim being sent in the SAML assertion. This means users may see access to only one project despite belonging to several groups.

To reliably assign multiple projects with their respective roles, use App Roles defined in the App Registration instead of group-based claims:

  1. In the App Registration for your n8n SAML app, define App Roles representing each project and permission combination (for example, <projectId>:<role>).
  2. Save the updated App Manifest.
  3. In the Enterprise Application, assign users or groups to these App Roles under Users and groups.
  4. Update the n8n_projects SAML claim in Single sign-on > Attributes & Claims to source from user.assignedroles. This emits all assigned roles as an array in the SAML response.

This setup ensures n8n receives all project assignments correctly, enabling appropriate access across multiple projects. While defining App Roles adds initial administrative overhead, it simplifies ongoing user-role management and guarantees complete project role sync.

When migrating from group-based claims to App Roles, adjust your role definitions and claims mapping accordingly to prevent incomplete project access.

References#

This page was