Dashboard Security

This page is intended for administrators and operators who configure and secure access to EMQX Dashboard. It covers first login, local-user authentication methods, token-based login, password management, account lockout, HTTPS, and role-based access control.

First Login

For a fresh EMQX installation, open the Dashboard at http://localhost:18083/ and log in with the default credentials: username admin, password public.

After the first login, the system detects that you are using the default credentials and forces a password change before you can proceed. The new password must differ from the original, and using public again is not recommended.

Configure Authentication Methods for Local Dashboard Users

Starting from EMQX 6.3.1, EMQX provides SCRAM-SHA-256 challenge-response endpoints for local Dashboard users. SCRAM and password-based login authenticate the same local user credentials and issue Dashboard bearer tokens. With SCRAM, a client proves that it knows the password without sending the password in an HTTP request body.

Choose an Authentication Mode

Set dashboard.password_login to select the accepted authentication methods:

• both: Accept SCRAM-SHA-256 and the password-based POST /api/v5/login request. This is the default value.
• scram_only: Accept only SCRAM-SHA-256. The password-based endpoint returns HTTP 403 with the error code PASSWORD_LOGIN_DISABLED.

Prepare for SCRAM-Only Mode

Keep both during a rolling upgrade. Set scram_only only after all EMQX nodes and clients that sign in with local Dashboard user credentials support SCRAM. Scripts and third-party clients that obtain bearer tokens with local Dashboard user credentials must migrate to POST /api/v5/login/challenge and POST /api/v5/login/verify. Programs that only call the EMQX management REST API can use API keys instead.

If EMQX reports in the server logs that a local user's password must be migrated, reset the user's password before enabling scram_only.

The embedded API Spec Explorer login page uses SCRAM by default. For its secure-context requirements, see Browser Access. For the complete SCRAM flow, see Obtain a Bearer Token with SCRAM-SHA-256.

For configuration details, see Dashboard Configuration.

Token-Based Login via URL

Starting from EMQX 5.6.0, the Dashboard supports token-based login by embedding authentication information in the URL. This is useful for seamless redirection and integration scenarios where a user should be logged in automatically without manually entering credentials.

Token-based login uses an existing Dashboard bearer token; it is not a separate credential type.

EMQX Dashboard uses the management REST API to retrieve data and perform administrative operations. After token-based login, Dashboard uses the bearer token to authenticate these API requests.

Obtain a Dashboard Token

When dashboard.password_login is set to both, you can obtain a token from the password-based /login endpoint. Because the response does not include the username, add it manually before encoding the full JSON payload. The following command requests the token, adds the username, encodes the compact JSON as Base64 without line breaks, and percent-encodes the result for use in a URL:

curl -s -X POST "http://127.0.0.1:18083/api/v5/login" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin","password": "public"}' \
  | jq -c '.username = "admin"' \
  | base64 \
  | tr -d '\n' \
  | jq -sRr @uri

If dashboard.password_login is set to scram_only, obtain the token with SCRAM-SHA-256. Add the username to the SCRAM response, encode the resulting JSON object as Base64 without line breaks, and percent-encode it before constructing the login URL.

Construct the Login URL

Embed the percent-encoded Base64 value in the login_meta query parameter.

For EMQX versions before 5.6.0:

http://localhost:18083?login_meta=URL_ENCODED_BASE64_STRING

This redirects to the default cluster overview page.

For EMQX 5.6.0 and later:

http://localhost:18083/#/dashboard/overview?login_meta=URL_ENCODED_BASE64_STRING

This allows specifying the target page after login.

Handle the token securely and set appropriate expiration and scope limits.

Manage Passwords

Reset Password

You can reset a Dashboard user's password with the admins CLI command. For details, see CLI - admins.

./bin/emqx ctl admins passwd <Username> <Password>

Password Expiration

When a Dashboard login password has been in use longer than the configured password_expired_time, the user is prompted to set a new password at the next login. Users with the Administrator role can also update this setting via the REST API.

Example: set the password expiration time to 1 day:

curl -X 'PUT' \
  'http://admin:ppp@localhost:18083/api/v5/configs/dashboard' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"password_expired_time": "1d"}'

For the full list of password_expired_time options, see Dashboard Configuration.

Account Lockout and Unlock

The Dashboard locks a user account after 5 consecutive failed login attempts within a 5-minute window. The account remains locked for 10 minutes before it is automatically unlocked.

Users with the Administrator role can manually unlock an account at any time by resetting the user's password via the CLI:

./bin/emqx ctl admins passwd <Username> <NewPassword>

Administrators can also adjust the lockout duration and the failed-attempt threshold through the backend configuration. Refer to Dashboard Configuration for the relevant settings (unsuccessful_login_max_attempts, unsuccessful_login_lock_duration, unsuccessful_login_interval).

Enable HTTPS for Dashboard

By default, the Dashboard listens on HTTP port 18083. To serve the Dashboard over HTTPS, configure an HTTPS listener with a TLS certificate and key:

dashboard {
  listeners {
    https {
      bind = "0.0.0.0:18084"
      ssl_options {
        certfile = "${EMQX_ETC_DIR}/certs/cert.pem"
        keyfile  = "${EMQX_ETC_DIR}/certs/key.pem"
      }
    }
  }
}

To disable the HTTP listener and enforce HTTPS-only access, set the HTTP bind port to 0:

dashboard {
  listeners {
    http {
      bind = 0
    }
  }
}

For the full set of listener and TLS options, see Dashboard Configuration.

Role-Based Access Control

Starting from EMQX 5.3, Dashboard users are assigned one of two predefined roles that control what they can do. You can select a role when creating a user on the System > Users page.

Role	Permissions
Administrator	Full access to all EMQX features and resources, including client management, system configuration, API keys, and user management.
Viewer	Read-only access to all data and configurations, corresponding to all GET requests in the REST API. Cannot create, modify, or delete any data.

TIP

Dashboard usernames and passwords cannot be used directly as Basic authentication credentials for REST API requests. For programmatic access, use API keys or obtain a short-lived bearer token through a Dashboard login flow. Use API keys for long-running services and unattended automation.

For details on managing users, see System > Users.