Authentication

MQTT Explorer supports username/password authentication for secure broker connections. This guide covers both MQTT broker authentication (connecting to brokers) and MQTT Explorer server authentication (browser mode access control).

MQTT Broker Authentication

Most production MQTT brokers require authentication to prevent unauthorized access.

Configuring Credentials

Open Connection Settings

Select your connection profile in the connection dialog.

Enter Credentials

Fill in the authentication fields:

Username: Your MQTT broker username
Password: Your MQTT broker password

These fields are marked as “Optional” because some brokers (like public test brokers) don’t require authentication.

Save and Connect

Click Save to persist the credentials, then Connect to authenticate.

Password Visibility

MQTT Explorer includes a password visibility toggle to help you verify your credentials:

Click the eye icon to show the password
Click again to hide it
Passwords are hidden by default for security

Be careful when showing passwords in shared or public environments. Passwords are stored locally in your connection profiles.

Connection Parameters

username

string

The username for authenticating with the MQTT broker.Use cases:

Basic authentication with username/password
Access control and user identification
Audit logging and connection tracking

Examples:

admin - Administrator account
device-001 - Device-specific credentials
readonly-user - Limited permissions account

password

string

The password for authenticating with the MQTT broker.

Passwords are stored locally in your connection profiles. In browser mode, they’re stored in browser localStorage. In desktop mode, they’re stored in the application’s configuration directory.

Security considerations:

Use strong, unique passwords for each broker
Rotate passwords regularly
Never share credentials or commit them to version control
Use TLS/SSL to encrypt password transmission

Auto-Connect with Credentials

When running MQTT Explorer in server/browser mode, you can configure broker credentials via environment variables for automatic connection:

# Set broker credentials
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=1883
export MQTT_AUTO_CONNECT_USERNAME=myuser
export MQTT_AUTO_CONNECT_PASSWORD=mypassword

# Optional: Set custom client ID
export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-server

# Start server
node dist/src/server.js

Never commit environment files with credentials to version control. Use .env files with .gitignore or secure secrets management.

Server Authentication (Browser Mode)

When running MQTT Explorer in browser mode, the web interface itself can be protected with authentication.

Authentication Manager

MQTT Explorer uses bcrypt password hashing and rate limiting for secure authentication:

bcrypt hashing: Passwords hashed with 10 rounds (industry standard)
Timing-safe comparison: Username comparison uses crypto.timingSafeEqual() to prevent timing attacks
Rate limiting: Maximum 5 failed attempts per IP per 15 minutes
Automatic reset: Rate limit counters reset after 15 minutes

Configuration Options

MQTT_EXPLORER_USERNAME

string

default:"auto-generated"

Username for accessing the MQTT Explorer web interface.Default behavior: If not set, a random username is generated (e.g., user-a1b2c3d4)

export MQTT_EXPLORER_USERNAME=admin

MQTT_EXPLORER_PASSWORD

string

default:"auto-generated"

Password for accessing the MQTT Explorer web interface.Default behavior: If not set, a random UUID password is generated and displayed in the console on first startup.

export MQTT_EXPLORER_PASSWORD=your_strong_password_min_12_chars

Use passwords with at least 12 characters including uppercase, lowercase, numbers, and special characters.

MQTT_EXPLORER_SKIP_AUTH

boolean

default:false

Disable authentication entirely for the web interface.

export MQTT_EXPLORER_SKIP_AUTH=true

SECURITY RISK: Only use this when MQTT Explorer is behind a secure authentication proxy (e.g., nginx with basic auth, OAuth2 proxy). Never expose an unauthenticated instance to the internet.

When enabled, you’ll see this warning on startup:

============================================================
WARNING: Authentication is DISABLED
MQTT_EXPLORER_SKIP_AUTH=true
This should only be used behind a secure authentication proxy!
============================================================

First-Time Setup

When you run MQTT Explorer in browser mode without configured credentials:

Start Server

Run node dist/src/server.js without setting authentication environment variables.

Credentials Generated

MQTT Explorer automatically generates secure random credentials:

============================================================
Generated new credentials:
Username: user-a1b2c3d4
Password: 550e8400-e29b-41d4-a716-446655440000
============================================================
Please save these credentials. They will be persisted to:
/home/user/.mqtt-explorer-credentials.json
============================================================
IMPORTANT: In production, use environment variables:
export MQTT_EXPLORER_USERNAME=<username>
export MQTT_EXPLORER_PASSWORD=<password>
============================================================

Save Credentials

Copy the username and password immediately. They’re saved to a credentials file but the password is hashed, so you can’t retrieve the plain text later.

Use the generated credentials to login to the web interface.

Credential Priority

MQTT Explorer checks for credentials in this order:

Environment variables (highest priority)
- MQTT_EXPLORER_USERNAME
- MQTT_EXPLORER_PASSWORD
Credentials file (persisted from first run)
- ~/.mqtt-explorer-credentials.json
Auto-generation (lowest priority)
- Generates new random credentials if none exist

Environment variables always take precedence. Set them in production to override any persisted credentials.

Production Deployment

Recommended Setup

For secure production deployments, follow these steps:

Set Strong Credentials

Use environment variables with strong passwords:

export MQTT_EXPLORER_USERNAME=admin
export MQTT_EXPLORER_PASSWORD=$(openssl rand -base64 32)
export NODE_ENV=production

Enable TLS

Use a reverse proxy (nginx, Apache, Caddy) with TLS certificates:

server {
    listen 443 ssl http2;
    server_name mqtt-explorer.example.com;
    
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Configure CORS

Set allowed origins for the web interface:

export ALLOWED_ORIGINS=https://mqtt-explorer.example.com

Network Security

Add firewall rules and network-level protection:

# Only allow access from specific IPs
ufw allow from 10.0.0.0/8 to any port 3000
ufw deny 3000

Docker Deployment

FROM node:24-alpine

WORKDIR /app
COPY . .
RUN yarn install && yarn build:server

# Set production environment
ENV NODE_ENV=production

EXPOSE 3000
CMD ["node", "dist/src/server.js"]

Run with secrets:

docker run -d \
  -e MQTT_EXPLORER_USERNAME=admin \
  -e MQTT_EXPLORER_PASSWORD="$(cat /run/secrets/mqtt_explorer_password)" \
  -e MQTT_AUTO_CONNECT_HOST=mqtt.example.com \
  -e MQTT_AUTO_CONNECT_USERNAME=broker_user \
  -e MQTT_AUTO_CONNECT_PASSWORD="$(cat /run/secrets/mqtt_password)" \
  -p 3000:3000 \
  mqtt-explorer

Access Control Lists (ACL)

MQTT brokers often use ACLs to control which topics users can access. MQTT Explorer respects these restrictions.

Common ACL Patterns

Read-Only Access

User can subscribe to topics but cannot publish:

# Mosquitto ACL example
user readonly-user
topic read #

MQTT Explorer behavior:

✅ Can view all topics
✅ Can receive messages
❌ Cannot publish messages (publish will fail)

Topic-Specific Access

User can only access specific topic patterns:

# Mosquitto ACL example
user device-001
topic readwrite devices/device-001/#
topic read system/status

MQTT Explorer behavior:

✅ Can view devices/device-001/* topics
✅ Can publish to devices/device-001/*
✅ Can view system/status
❌ Cannot view or publish to other topics

Administrative Access

User has full access to all topics:

# Mosquitto ACL example
user admin
topic readwrite #
topic readwrite $SYS/#

MQTT Explorer behavior:

✅ Full access to all topics
✅ Can view broker statistics ($SYS)
✅ Can publish and subscribe anywhere

Testing ACL Permissions

To verify your user’s permissions:

Connect with your credentials
Try subscribing to various topics
Attempt to publish messages
Check broker logs for ACL denials

MQTT Explorer will show topics you have permission to view. Denied topics won’t appear in the topic tree.

Troubleshooting

Authentication failed

Symptoms: Connection refused with authentication errorCauses:

Incorrect username or password
User doesn’t exist on broker
Special characters not properly escaped

Solutions:

Verify credentials are correct (check for typos)
Check broker user database: mosquitto_passwd -U passwordfile
Test with mosquitto_sub: mosquitto_sub -h host -u user -P pass -t #
Check broker logs for authentication failures

Rate limit exceeded (Browser Mode)

Symptoms: “Too many failed login attempts” messageCauses:

5 failed login attempts within 15 minutes
Brute force protection triggered

Solutions:

Wait 15 minutes for automatic reset
Verify correct credentials
Check if credentials were changed on the server
Restart server to reset rate limits (not recommended)

Lost server credentials

Symptoms: Can’t access browser interface, don’t remember passwordSolutions:

Check server console output from first startup (if available)
Delete credentials file: rm ~/.mqtt-explorer-credentials.json

Set new credentials via environment variables:

export MQTT_EXPLORER_USERNAME=newuser
export MQTT_EXPLORER_PASSWORD=newpassword

Restart server to generate new random credentials

ACL denies access

Symptoms: Topics not appearing, publish failsCauses:

User ACL restricts topic access
Insufficient permissions

Solutions:

Check broker ACL configuration
Verify user has required permissions: read and/or write
Check broker logs for ACL denial messages
Use an admin account for full access
Request permission updates from broker administrator

Password contains special characters

Symptoms: Authentication works in some tools but not othersCauses:

Special characters need proper escaping
Different escaping rules in shells vs config files

Solutions:

Quote passwords in shell: export PASSWORD='p@$$w0rd!'
Use connection profiles instead of environment variables
Avoid characters that need escaping: $, !, backticks, quotes
Test with a simple password first to isolate the issue

Security Best Practices

Strong Passwords

Use passwords with at least 12 characters, including uppercase, lowercase, numbers, and special characters.

Unique Credentials

Use different credentials for each environment (dev, staging, production) and each user.

Regular Rotation

Rotate passwords every 90 days and immediately after suspected compromise.

TLS Required

Always use TLS/SSL when transmitting credentials to prevent interception.

Least Privilege

Grant users minimum required permissions using ACLs. Use read-only accounts when possible.

Monitor Access

Review broker logs regularly for failed authentication attempts and unusual activity.

Next Steps

TLS/SSL Configuration

Encrypt authentication credentials in transit with TLS/SSL certificates.

Environment Variables

Learn about all available environment variables for server configuration.

Connection Setup

Return to the connection setup guide for other configuration options.

Security Policy

Review the complete security policy and report vulnerabilities.

Get Started

Deployment

Features

Guides

Advanced

MQTT Broker Authentication

Configuring Credentials

Password Visibility

Connection Parameters

Auto-Connect with Credentials

Server Authentication (Browser Mode)

Authentication Manager

Configuration Options

First-Time Setup

Credential Priority

Production Deployment

Recommended Setup

Docker Deployment

Access Control Lists (ACL)

Common ACL Patterns

Testing ACL Permissions

Troubleshooting

Security Best Practices

Strong Passwords

Unique Credentials

Regular Rotation

TLS Required

Least Privilege

Monitor Access

Next Steps

TLS/SSL Configuration

Environment Variables

Connection Setup

Security Policy

Build docs developers (and LLMs) love

Get Started

Deployment

Features

Guides

Advanced

​MQTT Broker Authentication

​Configuring Credentials

​Password Visibility

​Connection Parameters

​Auto-Connect with Credentials

​Server Authentication (Browser Mode)

​Authentication Manager

​Configuration Options

​First-Time Setup

​Credential Priority

​Production Deployment

​Recommended Setup

​Docker Deployment

​Access Control Lists (ACL)

​Common ACL Patterns

​Testing ACL Permissions

​Troubleshooting

​Security Best Practices

Strong Passwords

Unique Credentials

Regular Rotation

TLS Required

Least Privilege

Monitor Access

​Next Steps

TLS/SSL Configuration

Environment Variables

Connection Setup

Security Policy

Build docs developers (and LLMs) love

MQTT Broker Authentication

Configuring Credentials

Password Visibility

Connection Parameters

Auto-Connect with Credentials

Server Authentication (Browser Mode)

Authentication Manager

Configuration Options

First-Time Setup

Credential Priority

Production Deployment

Recommended Setup

Docker Deployment

Access Control Lists (ACL)

Common ACL Patterns

Testing ACL Permissions

Troubleshooting

Security Best Practices

Next Steps