n8n-nodes-web-session-manager

A custom n8n node for managing authenticated web sessions with cookie-based authentication. This node automates the login process, manages session cookies, and provides automatic session refresh capabilities.

Features

Core Features (MVP)

• ✅ Basic Login Authentication - Authenticate to websites using username/password
• ✅ Cookie Extraction and Storage - Automatically extract and store session cookies
• ✅ Authenticated Request Execution - Make HTTP requests with stored cookies
• ✅ Secure Credential Management - Store credentials securely using n8n's credential system

Enhanced Features

• ✅ Automatic Session Refresh - Detect expired sessions and automatically re-authenticate
• ✅ CSRF Token Handling - Support websites requiring CSRF tokens for login
• ✅ Cookie Persistence - Cookies persist across workflow executions
• ✅ Multiple HTTP Methods - Support GET, POST, PUT, DELETE, PATCH

Installation

For n8n Cloud

This node is not yet published to npm. For now, it must be installed on self-hosted n8n instances.

For Self-Hosted n8n

1. Clone or download this repository
2. Navigate to your n8n custom nodes directory (usually ~/.n8n/custom/)
3. Copy this entire folder to the custom nodes directory
4. Install dependencies:

   npm install

5. Build the node:

   npm run build

6. Restart n8n

Quick Start

1. Create Credentials

1. In n8n, go to Credentials → New
2. Search for Web Session Manager API
3. Fill in:
   • Login URL: The URL of the login page (e.g., https://example.com/login)
   • Username: Your username or email
   • Password: Your password
   • Username Field Name: The name of the username field (default: username)
   • Password Field Name: The name of the password field (default: password)
   • Additional Form Fields: Optional JSON object with extra form fields

2. Use the Node

1. Add a Web Session Manager node to your workflow
2. Select your credentials
3. Choose an operation:
   • Login Only: Authenticate and store cookies
   • Make Authenticated Request: Make an HTTP request with cookies
   • Clear Session: Clear stored cookies
   • Test Connection: Test if credentials are valid

3. Example Workflow

Schedule Trigger (daily at 9 AM)
  ↓
Web Session Manager (Login Only)
  ↓
Web Session Manager (Make Authenticated Request)
  ↓
Process Data

Configuration

Operations

Login Only

Authenticates to the website and stores session cookies. Use this when you only need to authenticate without making a request.

Make Authenticated Request

Makes an HTTP request to the specified URL using stored session cookies. Automatically handles authentication if needed.

Parameters:

• Request URL: The URL to request
• Method: HTTP method (GET, POST, PUT, DELETE, PATCH)
• Headers: Optional custom headers
• Body: Request body (for POST/PUT/PATCH)
• Include Response Headers: Whether to include response headers in output
• Auto Refresh Session: Automatically re-authenticate if session expires
• Max Retry Attempts: Number of retries if session expires (1-5)

Clear Session

Clears all stored cookies and resets the session state.

Test Connection

Tests if the credentials are valid and can successfully authenticate.

Advanced Options

CSRF Token Handling

Some websites require CSRF tokens for login. Enable this option to automatically fetch and include CSRF tokens.

Options:

• Enable CSRF Handling: Enable automatic CSRF token extraction
• CSRF Token Selector: Custom CSS selector or meta name (e.g., meta[name="csrf-token"])
• CSRF Token Field Name: The form field name for the CSRF token (default: _token)

The node will automatically:

1. Fetch the login page
2. Extract the CSRF token from HTML (meta tags, hidden inputs, or cookies)
3. Include the token in the login request

Auto Refresh Session

When enabled, the node will automatically detect expired sessions (via HTTP 401/403 responses) and re-authenticate before retrying the request.

Examples

Example 1: Simple Login and Request

{
  "nodes": [
    {
      "parameters": {
        "operation": "login",
        "credential": "myWebsite"
      },
      "name": "Login",
      "type": "n8n-nodes-webSessionManager"
    },
    {
      "parameters": {
        "operation": "request",
        "requestUrl": "https://example.com/api/data",
        "method": "GET"
      },
      "name": "Get Data",
      "type": "n8n-nodes-webSessionManager"
    }
  ]
}

Example 2: POST Request with Body

{
  "parameters": {
    "operation": "request",
    "requestUrl": "https://example.com/api/submit",
    "method": "POST",
    "sendBody": true,
    "bodyContentType": "json",
    "jsonBody": "{\"key\": \"value\"}"
  }
}

Example 3: With CSRF Token Handling

{
  "parameters": {
    "operation": "login",
    "enableCsrfHandling": true,
    "csrfTokenSelector": "meta[name='csrf-token']",
    "csrfTokenField": "_token"
  }
}

Troubleshooting

Authentication Fails

Problem: Login operation returns an error.

Solutions:

1. Verify the login URL is correct
2. Check username and password
3. Verify the username/password field names match the website's form
4. Enable CSRF handling if the website requires it
5. Check if the website requires additional form fields

Session Expires Quickly

Problem: Session expires immediately or after a short time.

Solutions:

1. Enable "Auto Refresh Session" in request operations
2. Check if cookies are being extracted correctly (look at the response)
3. Some websites may require specific headers or user agents

CSRF Token Not Found

Problem: CSRF token extraction fails.

Solutions:

1. Manually inspect the login page HTML to find the CSRF token location
2. Set a custom CSRF Token Selector (CSS selector or meta name)
3. Check if the token is in cookies instead of HTML
4. Disable CSRF handling if not required

Cookies Not Persisting

Problem: Cookies are lost between workflow executions.

Note: Cookies are stored in node state, which persists within a workflow execution. For persistence across executions, ensure the workflow state is saved.

Security Considerations

• ✅ Credentials are encrypted using n8n's built-in encryption
• ✅ Cookies are stored securely in node state
• ✅ No credentials are logged or exposed in error messages
• ✅ Supports HTTPS enforcement
• ✅ Respects cookie security flags (HttpOnly, Secure, SameSite)

Important: This node is intended for automating access to YOUR OWN accounts or services where you have explicit permission. Users are responsible for compliance with websites' Terms of Service and applicable laws.

Development

Project Structure

n8n-nodes-web-session-manager/
├── credentials/
│   └── WebSessionApi.credentials.ts
├── nodes/
│   └── WebSessionManager/
│       ├── WebSessionManager.node.ts
│       ├── WebSessionManager.node.json
│       ├── websession-icon.svg
│       └── utils/
│           ├── cookieParser.ts
│           ├── csrfExtractor.ts
│           └── sessionManager.ts
├── package.json
├── tsconfig.json
└── README.md

Building

# Install dependencies
npm install

# Build the node
npm run build

# Watch mode for development
npm run dev

Testing

Currently, manual testing is required. Test scenarios:

1. Login to a test website
2. Extract cookies
3. Make authenticated requests
4. Test session expiration and auto-refresh
5. Test CSRF token handling

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT

Support

• Issues: GitHub Issues
• Documentation: See this README and inline help in n8n
• Community: n8n Community Forum

Changelog

Version 1.0.0 (Initial Release)

• Basic login authentication
• Cookie extraction and storage
• Authenticated request execution
• Secure credential management
• Automatic session refresh
• CSRF token handling
• Cookie persistence

Roadmap

Version 1.1 (Planned)

• OAuth 2.0 support
• Multi-account management
• Enhanced error messages

Version 1.2 (Planned)

• JavaScript rendering support (Playwright integration)
• Session sharing across workflows
• Advanced cookie filtering

Author: Hicham Char
Version: 1.0.0
Status: Production Ready