OS4X Enterprise Webaccess multi-factor authentication

From OS4X
Jump to navigation Jump to search

Bildschirmfoto 2023-11-14 um 10.58.48.png Bildschirmfoto 2023-11-14 um 10.54.49.png


In critical environments, having users to authenticate to use OS4X Webaccess is often required to support additional means of identification. OS4X Webaccess multi-factor authentication is a functionality to support this requirement. Authenticated users then must:

  1. provide a valid username and password
  2. must have access to their user email inbox, where a dynamically created token is sent to


OS4X Webaccess MFA contains of several configuration parameters.

Global configuration

The global configuration is located in "Configuration" -> "OS4X Enterprise" -> "Webaccess" -> "Multi-factor user authentication".

Bildschirmfoto 2023-11-14 um 10.30.16.png

  • Multi-factor authentication mail template: A mail text template (which is automatically created for updated OS4X installations) containing HTML code for the email. The variable "$MFA_TOKEN" will be replaced during template rendering.
  • Mail subject: Subject of the sent email to the user, encoded as UTF-8 mail subject (so special characters can be added here as well). If unconfigured or empty, the subject text "OS4X 2FA" is being used.
  • Mail sender address: Sender of the email, given in the mail header. If unconfigured, the value "OS4X <os4x>" is used.
  • Sendmail command: command which is being executed for emailing. If unconfigured, the system's default "sendmail" command is used.

User configuration

Bildschirmfoto 2023-11-14 um 10.38.35.png

Every user requiring MFA must be enabled. There exists no global configuration to activate the feature system-wide. The default is "off", so no MFA functionality is used. If the functionality is activated, a valid email address must be configured for this user. If no email address is configured for a user, the functionality is disabled during login.


For users with enabled MFA, after each successful authentication via username and password, a prompt will be presented asking for the dynamically created token. Three attempts entering the token can be made. If the code is incorrect after these three attempts, the user session is destroyed and he must re-authenticate for a new session.

System internals

For every user requiring MFA, the OS4X client daemon is asked to send out a MFA email. The dynamic token is saved on server-side in the user session. After successful authentication with the token, the dynamic token information is removed from the user session. If a (typically malicious) web request is executed leading to a user session with a MFA token inside, the user session is destroyed, forcing the user to re-login.

The MFA email is rendered by the OS4X client daemon in its configured user context using the configured MTA.

A word about portal users

The MFA token is generated on portal server side. The OS4X portal daemon periodically fetches MFA tokens from every configured portal server, sends out the email from the internal network to the configured email address and deletes this information on portal side. This offers the functionality to be only configured on internal zone and suppresses the need for a configured MTA on DMZ side.


Bildschirmfoto 2023-11-14 um 10.41.47.png

Every sent MFA email token is being logged in OS4X's system log containing the email address and the token value.