2. Configuration

The MSUI configuration is done through files in YAML format:

msui.yaml (MSUI service configuration)
msui-history.yaml (History logging component)

Note

Example configuration files can be found in /opt/halon/msui/share/examples/ and copied to /etc/halon/ which is the default path for the configuration files. These files is a good starting point to start configure the MSUI service.

The following configuration examples helps you define the basic settings for MSUI, such as the listener and port, database connection information and credentials, and which authentication methods that should be enabled. For settings related to email tracking and statistics, check out the history logging section. Most of the settings are optional but exist to give a high degree of customization for any given setup, to make it easier to get started the minimal requirements to get started have been listed below. Other settings that are more specific to individual setups can be found at additional settings.

2.1. Minimal configuration

Start by configure the following settings after your requirements:

Specify the listener host/port
Specify the MySQL database connection information and credentials
Set up the authentication method for logging into MSUI (local/remote/ldap)
Activate history logging (optional but highly recommended)

2.1.1. Listener configuration

Below is a basic listener configuration, it specifies which port MSUI should listen on. Multiple servers[] can be used in cases where different authentication methods are needed.

servers:
  - [...]
    server:
      port: 80

2.1.2. Database configuration

A MySQL or MariaDB database is required to store various data in MSUI such as domains and settings. In order for MSUI to connect to the database, update the host, port, database name, and user credentials to what you specified during the initial setup.

servers:
  - [...]
    database:
      client: "mysql"
      connection:
        host: 127.0.0.1
        port: 3306
        database: "db_name"
        user: "db_user"
        password: "db_user_password"

2.1.3. Basic authentication

The most basic form of authentication are local users defined directly in the configuration file.

servers:
  - [...]
    auth:
      source:
        users:
          - username: "admin"
            password: ""

For local users the password needs to be stored as an encrypted password, follow these instructions how to generate a password.

More detailed examples of different auth can be found further down in this chapter.

2.2. Authentication methods

There are several ways to authenticate users in MSUI. It is possible to specify local users directly in the configuration, forwarded header or check against an LDAP server. For all authentication methods except local users, the username has to be an valid email address.

Note that using forwarded header cannot be combined with database, ldap or local users.

2.2.1. Local users and database example

This example combines two types of authentication methods, local users and database.

servers:
  - [...]
    auth:
      source:
        users:
          - username: "admin"
            password: ""
        database:
          password:
            minlength: 6
            complexity:
              enabled: true
              strength: "medium"
            lockout: 10
      session:
        maxage: 3600
      ratelimit:
        enabled: true
        max: 5
        windowMs: 120000

2.2.2. Forwarded header example

This authentication method will trust the provided headers set by a reverse proxy infront of MSUI. The fieldname HTTP header should be an email address that can be mapped to a username in MSUI.

Note

This option can be used as single sign-on for MSUI where the reverse proxy web server handles the session validation.

auth:
  source:
    header:
      fieldname: "x-forwarded-user"
      alias:
        fieldname: "x-forwarded-user-alias"
        split:
          separator: ","

2.2.3. LDAP example

You can use multiple LDAP sources for authentication.

auth:
  source:
    ldap:
      - name: "example"
        domain:
          - "example.com"
        identifier: "mail"
        options:
          server:
          url: "ldaps://ldapserver.example.com"
          bindDN: "CN=ldapuser,CN=Users,DC=example,DC=com"
          bindCredentials: "badsecret"
          searchBase: "DC=example,DC=com"
          searchFilter: "(&(objectcategory=person)(objectclass=user)(mail={{username}}))"
          tlsOptions:
            rejectUnauthorized: true

2.3. Additional settings

MSUI offers a lot of customizability, a lot of the settings are optional but available if needed. Below are the different directives that are available within msui.yaml.

2.3.1. Server directives

The server directives specify the connection to the server running the MSUI instance.

servers[].server: The server settings for backend and frontend.

servers[].server.host: Specify a IPv4/IPv6 address that the server should bind to, if empty/missing it will bind to 0.0.0.0.

servers[].server.port: The server port.

servers[].server.apikey: A secret key that must be included as a header (X-API-Key) for all /api requests.

servers[].server.healthcheck: API healthcheck (disabled by default).

servers[].server.healthcheck.enabled: Enable or disable the healthcheck.

servers[].server.healthcheck.apikey: Set the api key required for healthcheck.

servers[].server.certfile: Path to public certificate.

servers[].server.keyfile: Path to private key.

servers[].server.proxy: Enable when running behind a proxy, e.g. NGINX, https://expressjs.com/en/guide/behind-proxies.html.

servers[].server.proxy.enabled: Enable or disable proxy.

servers[].server.proxy.ip: Set the IP of the proxy.

2.3.2. Database directives

The database directives control the connection for the database containing the MSUI settings and users.

servers[].database: The database settings.

servers[].database.client: Specify database type.

servers[].database.connection: The database connection settings.

servers[].database.connection.host: The hostname of the database server.

servers[].database.connection.port: The port used for the database server.

servers[].database.connection.database: The name of the database for MSUI.

servers[].database.connection.user: The database user.

servers[].database.connection.password: The password for the database user.

2.3.3. App directives

servers[].app: Generic settings for MSUI.

servers[].app.domain: Domain related settings.

servers[].app.domain.verification: Enables DNS based domain verification. Each new domain needs to be verified with a TXT based DNS record (msui-domain-verification=[...]).

servers[].app.domain.verification.txt: Settings for the TXT record.

servers[].app.domain.verification.txt.prefix: Change the default TXT prefix.

servers[].app.domain.verification.resolver: DNS resolver settings.

servers[].app.domain.verification.resolver.enabled: Enable or disable the resolver.

servers[].app.domain.verification.resolver.interval: Set the interval how often MSUI should check unverified domains.

2.3.4. Frontend directives

servers[].frontend: Frontend settings for MSUI.

servers[].frontend.enabled: Enable (default) or disable the frontend.

servers[].frontend.url: Set URL to be used for digest report links.

servers[].frontend.locale: Set the locale (language) for the UI. en-us, nl-nl and sv-se available.

servers[].frontend.locale.path: Override the default path (./locales) for locales.

2.3.5. Backend directives

servers[].backend: Backend settings for MSUI.

servers[].backend.xhr: Enable or disable backend requests to /xhr (frontend).

servers[].backend.xhr.enabled: Enable (default) or disable backend requests to /xhr (frontend).

servers[].backend.api: Enable or disable backend requests to /api (public API).

servers[].backend.api.enabled: Enable (default) or disable backend requests to /api (public API).

servers[].backend.api.restrict: Restrict API access for specific source IPs.

servers[].backend.api.restrict.sourceip: Restrict API access for specific source IPs.

2.3.6. Authentication directives

servers[].auth.timeout: Set the default response delay (500ms) for failed authenications.

2.3.7. User authentication directives

Static settings pertaining to user accounts for logging into MSUI.

servers[].auth.source.users[]: Local admin accounts.

servers[].auth.source.users[].username: The username. Required.

servers[].auth.source.users[].password

The hashed password.

Note

The password needs to be encrypted using bcrypt. You can run the following command to generate a password:

$ /opt/halon/msui/bin/generatepass

servers[].auth.source.users[].totp: Enable two-factor authentication.

servers[].auth.source.users[].totp.secret: GET /xhr/session/totp/generate

servers[].auth.source.users[].permissions

Permissions can be specified for any given user to limit what they are allowed to see and edit, possible values for each scope is either read or write.

users:
  - username: "localadmin"
    password: "badpassword"
    permissions:
      domains: "read"
      users: "write"
      settings: "write"
      audit: "read"

servers[].auth.source.users[].permissions.domains: Sets the permission scope for the domains.

servers[].auth.source.users[].permissions.users: Sets the permission scope for the users.

servers[].auth.source.users[].permissions.settings: Sets the permission scope for the MSUI settings.

servers[].auth.source.users[].permissions.audit: Sets the permission scope for the audit log.

2.3.8. Access token authentication directives

Access tokens can be used to authenticate a user without a valid session. Every HTTP request has to include the x-api-key header.

servers[].auth.source.accesstoken: Settings for API accesstokens. Permissions are set to the account’s permissions.

servers[].auth.source.accesstoken.enabled

true or false

auth:
  [...]
  accesstoken:
    enabled: true

2.3.9. LDAP authentication directives

servers[].auth.source.ldap[]: Configuration options for defining LDAP authentication sources.

servers[].auth.source.ldap[].name: A unique name for the LDAP source. Required.

servers[].auth.source.ldap[].domain: String matched domain, or an array to match multiple domains. Supports * to catch all domains.”. Required.

servers[].auth.source.ldap[].options: Visit https://github.com/vesse/passport-ldapauth for all available options. Required.

servers[].auth.source.ldap[].options.server: Configuration options for the LDAP server.

servers[].auth.source.ldap[].options.server.url: The URL of the LDAP server. Required.

servers[].auth.source.ldap[].options.server.bindDN: The Distinguished Name (DN) to bind to the LDAP server. Required.

servers[].auth.source.ldap[].options.server.bindCredentials: The credentials used to bind to the LDAP server. Required.

servers[].auth.source.ldap[].options.server.searchBase: The base DN from which to search for users in the LDAP server. Required.

servers[].auth.source.ldap[].options.server.searchfilter: The LDAP filter to use when searching for users. Required.

servers[].auth.source.ldap[].options.identifier: The attribute used to identify the username. Required.

2.3.10. Forwarded header authentication directives

servers[].auth.source.header: Remote authentication strategy. Header field values must always be set by a trusted proxy server.

servers[].auth.source.header.fieldname: Specify a header field name that should be mapped with the login username.

servers[].auth.source.header.rewrite: Rewrite login credentials (email localpart and/or domain).

servers[].auth.source.header.alias: Mapping of alias.

servers[].auth.source.header.alias.fieldname: Specify a header field name that should be mapped with alias.

servers[].auth.source.header.alias.convert: Convert existing users (by deleting) to alias if provided via the alias header.

servers[].auth.source.header.alias.convert.user: The settings for converting users to alias.

servers[].auth.source.header.alias.convert.user.enabled: Enables converting of existing users to alias.

servers[].auth.source.header.alias.convert.user.restrict: Set the restrictions for alias converting.

servers[].auth.source.header.alias.convert.user.restrict.domain: Only convert users to alias within the same domain.

servers[].auth.source.header.alias.split: Split header field value into multiple aliases.

servers[].auth.source.header.alias.split.separator: The seperator value that should be used to split the field value.

servers[].auth.source.header.alias.split.regex: The matching regex that should be used to split the field value.

servers[].auth.source.header.alias.loginas: Allow login as alias.

servers[].auth.source.header.alias.loginas.enabled: Enable or disable the login as alias feature.

servers[].auth.source.header.alias.loginas.domains: Restrict login for specific domains.

servers[].auth.source.header.restrict: Restrict access for specific domains (will be inherited by the owner value) by header field value.

2.3.11. Database password directives

Set a password policy for database users.

servers[].auth.source.database.password: Set a global password policy (requires database auth).

servers[].auth.source.database.password.minlength: Default minimum password length is 4.

servers[].auth.source.database.password.complexity: Password complexity.

servers[].auth.source.database.password.complexity.enabled: Enable password complexity.

servers[].auth.source.database.password.complexity.strength: Set the password complexity level of the database password. weak, medium or strong.

servers[].auth.source.database.password.age: The shortest/longest period of time (in days) that a password must/can be used before the user can change it.

servers[].auth.source.database.password.age.max: Maximum age in days.

servers[].auth.source.database.password.age.min: Minimum age in days.

servers[].auth.source.database.password.history: Enforce password history.

servers[].auth.source.database.password.lockout: Lock account after a number of failed login attempts.

servers[].auth.source.database.password.roles: Set an password policy per role.

2.3.12. Session directives

Configure session properties that apply to all types of authentication except access tokens.

servers[].auth.session: Settings for each authentication session.

servers[].auth.session.name: Specify a session name/prefix, default is <app-id>-session-id.

servers[].auth.session.secret: Specify a secret string that will be used to for session data, default is crypto.randomBytes.

servers[].auth.session.store: Select the data storage to be used. memorystore, filestore or redis.

servers[].auth.session.maxage: Session max age in seconds, default is 3600 seconds.

servers[].auth.session.filestore: Options for the session file store.

servers[].auth.session.filestore.path: The directory where the session files will be stored. Defaults to ./sessions.

servers[].auth.session.redis: Options for the Redis Client

servers[].auth.session.redis.options: https://www.npmjs.com/package/redis

2.3.13. Rate limit directives

Apply rate limits on failed authentications.

servers[].auth.ratelimit: https://www.npmjs.com/package/express-rate-limit for available options.

servers[].auth.ratelimit.enabled: Enable rate limit.

servers[].auth.ratelimit.max: Set amount of login attempts before getting locked out.

servers[].auth.ratelimit.windowMs: Time (in seconds) to be locked out after reaching max failed logins.

servers[].auth.ratelimit.message: Message to display in UI when locked out.

2.3.14. Audit log directives

servers[].auditlog: Settings related to the audit log.

servers[].auditlog.enabled: Enable or disable the audit log.

servers[].auditlog.logsize: Define how many items that are stored in the database.

servers[].auditlog.interval: Interval in seconds for the cleanup task.

servers[].auditlog.logging: Audit log options.

servers[].auditlog.logging.login.failed: true or false. Enable logging for all failed login attempts.