Set up Azure AD SAML

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:

Valid values for n8n_instance_role:

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:

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

1. Expand Claim conditions and click Add condition.
2. Add conditions for each Azure AD group (in priority order):

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

• n8n SAML Setup
• n8n Okta Guide (reference)
• Azure AD Claims Customization