How to secure n8n with basic auth?

To secure n8n with Basic Authentication, you need to set environment variables that enable authentication and define credentials. This provides a simple way to restrict access to your n8n instance, requiring users to enter a username and password before accessing the interface or API.

 

Step 1: Understanding Basic Authentication in n8n

 

Basic Authentication is a simple authentication method that requires a username and password to access a protected resource. In n8n, you can enable Basic Authentication by setting specific environment variables. When enabled, users will be prompted to enter credentials before they can access the n8n interface or API.

 

Step 2: Setting Up Basic Authentication Using Environment Variables

 

The simplest way to enable Basic Authentication in n8n is by setting environment variables before starting the n8n service. There are two essential environment variables you need to set:

N8N_BASIC_AUTH\_ACTIVE=true
N8N_BASIC_AUTH\_USER=username
N8N_BASIC_AUTH\_PASSWORD=password

Replace "username" and "password" with your desired credentials. These environment variables can be set in different ways depending on how you're running n8n.

 

Step 3: Setting Up Basic Authentication for Docker Installations

 

If you're running n8n in a Docker container, you can pass the environment variables when starting the container:

docker run -it --rm \\
  --name n8n \\
  -p 5678:5678 \\
  -e N8N_BASIC_AUTH\_ACTIVE=true \\
  -e N8N_BASIC_AUTH\_USER=myusername \\
  -e N8N_BASIC_AUTH\_PASSWORD=mysecurepassword \\
  n8nio/n8n

For Docker Compose, add these environment variables to your docker-compose.yml file:

version: '3'

services:
  n8n:
    image: n8nio/n8n
    ports:
    - "5678:5678"
    environment:
    - N8N_BASIC_AUTH\_ACTIVE=true
    - N8N_BASIC_AUTH\_USER=myusername
    - N8N_BASIC_AUTH\_PASSWORD=mysecurepassword
    volumes:
    - ~/.n8n:/home/node/.n8n

 

Step 4: Setting Up Basic Authentication for npm Installations

 

If you installed n8n using npm, you can set the environment variables before starting n8n:

For Linux/Mac:

export N8N_BASIC_AUTH\_ACTIVE=true
export N8N_BASIC_AUTH\_USER=myusername
export N8N_BASIC_AUTH\_PASSWORD=mysecurepassword
n8n start

For Windows Command Prompt:

set N8N_BASIC_AUTH\_ACTIVE=true
set N8N_BASIC_AUTH\_USER=myusername
set N8N_BASIC_AUTH\_PASSWORD=mysecurepassword
n8n start

For Windows PowerShell:

$env:N8N_BASIC_AUTH\_ACTIVE="true"
$env:N8N_BASIC_AUTH\_USER="myusername"
$env:N8N_BASIC_AUTH\_PASSWORD="mysecurepassword"
n8n start

 

Step 5: Making Basic Authentication Persistent

 

To make your Basic Authentication settings persistent across restarts, you can:

Option 1: Create a .env file in your n8n root directory:

N8N_BASIC_AUTH\_ACTIVE=true
N8N_BASIC_AUTH\_USER=myusername
N8N_BASIC_AUTH\_PASSWORD=mysecurepassword

Option 2: For systemd service:

If you're running n8n as a systemd service, edit the service file:

sudo nano /etc/systemd/system/n8n.service

Add the environment variables to the [Service] section:

[Service]
Environment="N8N_BASIC_AUTH\_ACTIVE=true"
Environment="N8N_BASIC_AUTH\_USER=myusername"
Environment="N8N_BASIC_AUTH\_PASSWORD=mysecurepassword"

Then reload and restart the service:

sudo systemctl daemon-reload
sudo systemctl restart n8n

 

Step 6: Setting Up Multiple User Accounts

 

For multiple user accounts, you can use the N8N_BASIC_AUTH_HASH environment variable with bcrypt hashed passwords. First, generate bcrypt hashes for your passwords:

npm install -g bcrypt-cli
bcrypt-cli 'user1password' 10
bcrypt-cli 'user2password' 10

Then set the environment variable with multiple user:hash pairs, separated by colons:

N8N_BASIC_AUTH\_HASH=user1:$2b$10$XJGm6DdVXFBaQvxLrXOQxe8YP5aRziH1JJykA7zNkvDuH2cMlFh4y:user2:$2b$10$5S0RVIiV9wP8vdHuaGgMv.qQD9epB7NqL1YMlVnNY/DPvqnLEFSLO

 

Step 7: Testing Your Basic Authentication Setup

 

After setting up Basic Authentication:

1. Restart your n8n instance
2. Access the n8n interface via browser (typically http://localhost:5678)
3. You should be prompted with a login dialog
4. Enter the username and password you configured
5. Verify you can access n8n after entering correct credentials

If you're accessing the n8n API programmatically, you'll need to include Basic Authentication headers in your requests:

curl -X GET \\
  http://localhost:5678/rest/workflows \\
  -H 'Authorization: Basic bXl1c2VybmFtZTpteXNlY3VyZXBhc3N3b3Jk'

The Authorization header contains "Basic " followed by the base64-encoded string of "username:password".

 

Step 8: Additional Security Considerations

 

While Basic Authentication provides a simple security layer, consider these additional security measures:

Use HTTPS: Basic Authentication sends credentials encoded (not encrypted). Use HTTPS to encrypt all traffic:

N8N\_PROTOCOL=https
N8N_SSL_KEY=/path/to/privkey.pem
N8N_SSL_CERT=/path/to/cert.pem

Set Up a Reverse Proxy: Use Nginx or Apache as a reverse proxy with additional security features:

Example Nginx configuration:

server {
    listen 80;
    server\_name your-n8n-domain.com;
    
    location / {
        proxy\_pass http://localhost:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote\_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

IP Restrictions: Limit access to specific IP addresses in your firewall configuration or reverse proxy settings.

 

Step 9: Securing the REST API

 

The Basic Authentication setup above also secures the REST API. However, you can additionally set a separate REST API authentication:

N8N_BASIC_AUTH\_ACTIVE=true
N8N_BASIC_AUTH\_USER=webuser
N8N_BASIC_AUTH\_PASSWORD=webpassword
N8N_API_AUTH_EXCLUDING_PASSWORD=true
N8N_API_REST\_PASSWORD=apipassword

This configuration:

• Requires username/password (webuser/webpassword) for web interface access
• Requires only a password (apipassword) for REST API access

 

Step 10: Troubleshooting Common Issues

 

Issue: Authentication not working after setup

Check that:

• Environment variables are correctly set
• n8n was restarted after setting the variables
• No typos in your username or password
• You're not using special characters that need escaping in your shell

Issue: Authentication works in browser but not with API calls

Check your Base64 encoding:

echo -n "myusername:mysecurepassword" | base64

Use this output in your Authorization header:

Authorization: Basic [base64-output]

Issue: Multiple users not working

Verify your bcrypt hashes are correctly generated and the N8N_BASIC_AUTH_HASH format is correct (user1:hash1:user2:hash2).

 

Step 11: Using Environment Variables in Production Environments

 

For production environments, consider using a secret management solution:

Docker Secrets: If using Docker Swarm:

version: '3.1'

secrets:
  n8n_basic_auth\_user:
    external: true
  n8n_basic_auth\_password:
    external: true

services:
  n8n:
    image: n8nio/n8n
    secrets:
    - n8n_basic_auth\_user
    - n8n_basic_auth\_password
    environment:
    - N8N_BASIC_AUTH\_ACTIVE=true
    - N8N_BASIC_AUTH_USER_FILE=/run/secrets/n8n_basic_auth\_user
    - N8N_BASIC_AUTH_PASSWORD_FILE=/run/secrets/n8n_basic_auth\_password

Kubernetes Secrets: If using Kubernetes:

Create a secret:

kubectl create secret generic n8n-auth \\
  --from-literal=user=myusername \\
  --from-literal=password=mysecurepassword

Reference in your deployment:

env:
- name: N8N_BASIC_AUTH\_ACTIVE
    value: "true"
- name: N8N_BASIC_AUTH\_USER
    valueFrom:
      secretKeyRef:
        name: n8n-auth
        key: user
- name: N8N_BASIC_AUTH\_PASSWORD
    valueFrom:
      secretKeyRef:
        name: n8n-auth
        key: password

By following these steps, you've successfully secured your n8n instance with Basic Authentication, providing a foundational layer of security to protect your workflows and data.