Authentication & SSO (Enterprise)
Relevant source files
The following files were used as context for generating this wiki page:
The authentication system in n8n manages user access and sessions. It provides a foundation for standard email/password authentication and is extended with enterprise-grade Single Sign-On (SSO) capabilities using SAML and OIDC protocols. This modular architecture centralizes session management while allowing for different authentication providers. SSO is controlled by the Saml and Oidc enterprise feature flags.
Sources: packages/frontend/editor-ui/src/constants.ts:1003-1004
Core Authentication Service
The AuthService is the central component for handling user sessions and credentials. It is used by all authentication methods, including standard login and SSO, to issue session cookies and validate users.
Sources: packages/cli/src/auth/auth.service.ts
Key Responsibilities
- Session Management: Issues secure, HTTP-only session cookies upon successful login. The
issueCookiemethod is the final step in any authentication flow. - Password Hashing: Securely hashes and verifies user passwords using
bcrypt. - User Validation: Validates user credentials against the database.
The diagram below shows the central role of AuthService.
This diagram illustrates how different authentication controllers and services rely on the central AuthService to finalize the login process by issuing a session cookie.
Sources: packages/cli/src/auth/auth.service.ts, packages/cli/src/controllers/auth.controller.ts, packages/cli/src/sso.ee/saml/routes/tests/saml.controller.ee.test.ts
Cookie Issuance
The issueCookie method is responsible for creating and setting the session cookie. A critical detail is that logins via SSO providers (SAML, OIDC) are treated as having fulfilled Multi-Factor Authentication (MFA) requirements. This is indicated by the isMfaAuthenticated parameter being set to true when issueCookie is called after a successful SSO login.
Sources: packages/cli/src/auth/auth.service.ts:51-71, packages/cli/src/sso.ee/saml/routes/tests/saml.controller.ee.test.ts:121-122
SAML Authentication (Enterprise)
n8n supports SAML 2.0 for enterprise SSO. The flow is initiated by a Service Provider (SP, n8n) or an Identity Provider (IdP). The core logic resides in the SamlService and is exposed via the SamlController.
Sources: packages/cli/src/sso.ee/saml/saml.service.ee.ts, packages/cli/src/sso.ee/saml/routes/tests/saml.controller.ee.test.ts
SAML Login Flow
The following sequence diagram illustrates the SAML login process.
User Provisioning
The handleSamlLogin method in SamlService is responsible for processing the SAML assertion. It extracts user attributes (email, firstName, lastName) and uses them to find an existing user or provision a new one (Just-In-Time provisioning).
Sources: packages/cli/src/sso.ee/saml/saml.service.ee.ts
Connection Test Flow
A special flow exists to test the SAML connection from the n8n UI. This is triggered when the RelayState in the SAML request matches a specific test URL. Instead of issuing a cookie, it renders a success or failure page with the attributes received from the IdP.
- Trigger:
RelayStateisgetServiceProviderConfigTestReturnUrl(). - Success: Renders
saml-connection-test-successview with user attributes. - Failure: Renders
saml-connection-test-failedview with an error message.
Sources: packages/cli/src/sso.ee/saml/routes/tests/saml.controller.ee.test.ts:47-90
OIDC Authentication (Enterprise)
n8n also supports OpenID Connect (OIDC) for SSO, which is built on top of OAuth 2.0. The implementation is handled by the OidcService and a corresponding controller.
Sources: packages/cli/src/sso.ee/oidc/oidc.service.ee.ts
OIDC Login Flow
The OIDC flow involves redirecting the user to the OIDC provider for authentication and then handling the callback.
User Provisioning
Similar to SAML, the handleOidcLogin method in OidcService processes the claims from the OIDC ID Token to find or create a user in n8n. It maps standard OIDC claims to n8n user properties.
Sources: packages/cli/src/sso.ee/oidc/oidc.service.ee.ts
API Endpoints
The authentication system exposes several endpoints to handle different login flows.
| Method | Path | Controller | Description |
|---|---|---|---|
POST | /auth | AuthController | Handles standard email and password login. |
GET | /auth/sso/saml | SamlController | Provides the SAML Service Provider metadata XML. |
POST | /auth/sso/saml/acs | SamlController | Assertion Consumer Service (ACS) endpoint. Receives the SAML assertion from the IdP. |
GET | /auth/sso/oidc | OidcController | Initiates the OIDC login flow by redirecting the user to the OIDC provider. |
GET | /auth/sso/oidc/callback | OidcController | Handles the callback from the OIDC provider, containing the authorization code or tokens. |
GET | /saml/onboarding | SamlController | A view for users who require onboarding after their first SAML login. |
Sources: packages/cli/src/controllers/auth.controller.ts, packages/cli/src/sso.ee/saml/routes/tests/saml.controller.ee.test.ts
Conclusion
The n8n authentication system provides a robust and flexible mechanism for user access. The core AuthService ensures consistent session management, while the dedicated SamlService and OidcService modules enable seamless integration with enterprise identity providers. A key security feature is treating all successful SSO logins as MFA-authenticated, enhancing the security posture for enterprise deployments. The system also includes thoughtful features like the SAML connection test to simplify configuration and troubleshooting.