User Management & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/src/auth/auth.service.ts
- packages/cli/src/controllers/auth.controller.ts
- packages/db/src/entities/user.ts
- packages/cli/src/services/user.service.ts
- packages/cli/test/integration/shared/db/users.ts
- packages/testing/playwright/tests/ui/39-projects.spec.ts
- packages/testing/playwright/tests/ui/39-project-settings.spec.ts
- packages/frontend/editor-ui/src/features/collaboration/projects/components/ProjectMembersTable.test.ts
The User Management and Authentication system in n8n is responsible for handling user identity, access control, and security. It is built on a standard controller-service-repository pattern, utilizing TypeORM for database interactions. The system manages user creation, authentication via passwords or API keys, role-based access control (RBAC) at both global and project levels, and multi-factor authentication (MFA).
This document outlines the core components of this system, including the User data model, authentication flows, role management, and project-based permissions. It serves as a technical reference for developers working with or extending n8n's user-related functionalities.
Architecture Overview
The system follows a layered architecture common in Node.js applications. The AuthController handles incoming HTTP requests, which are then processed by the AuthService and UserService. These services interact with the database through repositories like UserRepository.
This diagram illustrates the high-level interaction between the main components.
User Data Model
The core of the user management system is the User entity, which is mapped to the user_entity table in the database. It stores all essential information about a user, including credentials, role, and status.
Sources: packages/db/src/entities/user.ts
ER Diagram
This diagram shows the User entity and its relationship with the Role and AuthIdentity entities.
User Entity Fields
The following table details the columns in the user_entity table.
| Field | Type | Constraints | Description |
|---|---|---|---|
id | string | Primary Key, UUID | Unique identifier for the user. |
email | string | Unique, Not Null | The user's email address, used for login. |
password | string | Nullable | Hashed password for the user. null for pending or SSO users. |
firstName | string | Not Null | User's first name. |
lastName | string | Not Null | User's last name. |
role | Role | Many-to-One | The global role assigned to the user. |
mfaEnabled | boolean | Default: false | Flag indicating if Multi-Factor Authentication is enabled. |
mfaSecret | string | Nullable | Encrypted TOTP secret for MFA. |
mfaRecoveryCodes | string | Nullable | Encrypted recovery codes for MFA. |
apiKeys | PublicApiKey[] | One-to-Many | API keys associated with the user. |
authIdentities | AuthIdentity[] | One-to-Many | Identities from external providers (e.g., LDAP). |
createdAt | datetime | Not Null | Timestamp of user creation. |
updatedAt | datetime | Not Null | Timestamp of the last update. |
Sources: packages/db/src/entities/user.ts:25-139
User Creation and Management
Users are created and managed primarily through the UserService and UserRepository. A key function is createUserWithProject, which not only creates a user but also associates them with a default personal project.
Sources: packages/cli/src/services/user.service.ts, packages/cli/test/integration/shared/db/users.ts:50-52
User Creation Flow
The sequence diagram below shows the process of creating a new user.
Password Handling
Passwords are never stored in plaintext. The system uses bcryptjs to hash passwords before saving them to the database. A pre-computed hash for the default password 'password' is available for test environments.
Sources: packages/cli/test/integration/shared/db/users.ts:29-43
External Authentication (LDAP)
The system supports external authentication providers like LDAP. When a user authenticates via LDAP, an AuthIdentity record is created to link their n8n user account to their external identity.
Sources: packages/cli/test/integration/shared/db/users.ts:54-58
Authentication
Authentication is managed by AuthService and exposed via AuthController. It supports both password-based login and API key authentication.
Sources: packages/cli/src/auth/auth.service.ts, packages/cli/src/controllers/auth.controller.ts
Multi-Factor Authentication (MFA)
Users can enable MFA for enhanced security. The implementation uses TOTP (Time-based One-Time Password).
- Secret Generation:
TOTPServicegenerates a secret which is then encrypted byMfaService. - Storage: The encrypted secret and encrypted recovery codes are stored in the
mfaSecretandmfaRecoveryCodesfields of theUserentity. - Test Utilities: A helper function
createUserWithMfaEnabledis available for creating test users with MFA pre-configured.
Sources: packages/cli/test/integration/shared/db/users.ts:60-91, packages/db/src/entities/user.ts:88-101
API Keys
Users can generate public API keys for programmatic access.
- Creation: The
PublicApiKeyServiceis used to create keys for a user. - Scopes: API keys can be created with specific scopes, which are determined by the user's role using
getApiKeyScopesForRole. - Expiration: Keys can be set to expire at a specific time.
Sources: packages/cli/test/integration/shared/db/users.ts:93-125
Roles and Permissions
n8n uses a role-based access control (RBAC) system. Roles can be global or project-specific.
Global Roles
There are three primary global roles defined in the system.
| Role Slug | Constant | Description |
|---|---|---|
owner | GLOBAL_OWNER_ROLE | The instance owner with full permissions. |
admin | GLOBAL_ADMIN_ROLE | An administrator with elevated permissions. |
member | GLOBAL_MEMBER_ROLE | A standard user with basic permissions. |
Sources: packages/cli/test/integration/shared/db/users.ts:127-137
Project-Specific Roles
In addition to global roles, users can be assigned roles within the context of a specific project. This allows for more granular control over resources like workflows and credentials.
- Project Membership: Users can be invited to projects and assigned roles like
project:editororproject:admin. - UI Management: The project settings page provides a UI for managing project members and their roles. The owner's role within a project is fixed and cannot be changed.
- Role Dropdown: In the UI, a dropdown is available to change a member's role, but it is disabled for the current user to prevent self-modification of permissions.
This diagram shows the flow for creating a project and adding a credential to it.
Conclusion
The user management and authentication system in n8n is a robust and flexible framework that provides essential security and access control features. It effectively separates concerns between controllers, services, and data entities. The system's support for global and project-specific roles, MFA, and external authentication providers like LDAP makes it adaptable to various deployment scenarios, from single-user instances to large, multi-tenant environments. The integration tests provide clear patterns for programmatic user and role management.