Enterprise SSO
Relevant source files
The following files were used as context for generating this wiki page:
Enterprise SSO (Single Sign-On) in n8n is a licensed feature set designed to integrate the platform with external identity providers (IdPs). It enables centralized user management and authentication, supporting industry-standard protocols including SAML 2.0, OpenID Connect (OIDC), and LDAP. These modules are primarily located within the packages/cli/src/modules/ directory and are identified by the .ee.ts suffix, indicating they belong to the Enterprise Edition.
The system ensures that authentication flows are handled securely, using licensed decorators and enterprise-specific services to validate license compliance before allowing access to SSO configurations or authentication endpoints.
Sources: cubic.yaml:67-73, AGENTS.md:129-130
Architecture and Protocol Support
The Enterprise SSO system is built as a series of modular services, each handling a specific authentication protocol. These services interact with n8n's core authentication and user management systems to provision accounts and validate sessions.
Authentication Flow Overview
The general flow involves an initial request to an SSO endpoint, redirection to the external IdP, and a callback processing phase where n8n validates the IdP's response and authenticates the user locally.
Explanation: This diagram illustrates the high-level authentication lifecycle shared across SAML, OIDC, and LDAP integrations.
Sources: packages/cli/src/modules/sso-saml/saml.service.ee.ts, packages/cli/src/modules/sso-oidc/oidc.service.ee.ts
Supported Protocols
| Protocol | Description | Primary Service File |
|---|---|---|
| SAML 2.0 | XML-based framework for exchanging authentication and authorization data. | saml.service.ee.ts |
| OIDC | Identity layer on top of the OAuth 2.0 protocol. | oidc.service.ee.ts |
| LDAP | Protocol for accessing and maintaining distributed directory information. | ldap.service.ee.ts |
Sources: packages/cli/src/modules/sso-saml/saml.service.ee.ts, packages/cli/src/modules/sso-oidc/oidc.service.ee.ts, packages/cli/src/modules/ldap.ee/ldap.service.ee.ts
Security and License Enforcement
SSO features are strictly guarded by n8n's licensing system. Any endpoint or service related to Enterprise SSO must be validated against the active license to prevent unauthorized use of enterprise-tier features.
Security Implementation Guidelines
The project enforces specific security hygiene for enterprise modules:
- Decorator Usage: Controller endpoints in
*.ee.tsfiles must use the@Licenseddecorator. - Decorator Order: The routing decorator must come first, followed by
@Licensed, and then scope decorators (e.g.,@GlobalScope). - Vulnerability Prevention: SSO flows are reviewed for SAML/OIDC validation gaps, including OAuth 2.0 PKCE requirements and weak redirect URI validation.
Sources: cubic.yaml:61-75
Module Specifics
SAML Integration
The SAML module handles metadata exchange and assertion validation. It includes endpoints for initiating the login flow and a callback (ACS - Assertion Consumer Service) to process XML assertions signed by the IdP.
- Key Service:
SamlServicemanages the configuration and cryptographic verification of SAML responses. - Controller:
SamlControllerexposes endpoints like/loginand/callback.
Sources: packages/cli/src/modules/sso-saml/saml.service.ee.ts, packages/cli/src/modules/sso-saml/saml.controller.ee.ts
OIDC Integration
OIDC provides a modern authentication layer. The service manages client IDs, secrets, and discovery URLs to automate the retrieval of configuration from providers like Okta, Auth0, or Google.
- Key Service:
OidcServicehandles token exchange (code for access/ID tokens) and user info retrieval.
Sources: packages/cli/src/modules/sso-oidc/oidc.service.ee.ts
LDAP Integration
LDAP allows n8n to connect to directory services like Active Directory. Unlike SAML/OIDC which are often browser-redirect based, LDAP involves the n8n server directly querying the directory server to authenticate user credentials.
- Key Service:
LdapServicemanages connection pooling, user search filters, and binding.
Sources: packages/cli/src/modules/ldap.ee/ldap.service.ee.ts
Data Structures and Configuration
The SSO modules use DTOs (Data Transfer Objects) for request validation. These DTOs extend Z.class for runtime validation via Zod.
Explanation: This class diagram represents the typical configuration fields required for different Enterprise SSO protocols based on their respective service implementations.
Sources: packages/cli/src/modules/sso-saml/saml.service.ee.ts, packages/cli/src/modules/sso-oidc/oidc.service.ee.ts, cubic.yaml:144-150
Conclusion
Enterprise SSO is a critical component for large-scale deployments, providing the necessary integration with corporate identity systems. By utilizing standard protocols and enforcing strict licensing and security decorators, n8n maintains a secure environment for enterprise authentication. Management of these features is centralized in the .ee.ts modules, ensuring a clear separation between community and enterprise logic.