MFA (Multi-factor authentication)


Multi-factor authentication (MFA) is a mechanism which requires multiple factors (ways of proving of users' declared identity) in order to grant them access to protected resources. This greatly improves the security of the system at a cost of increased user discomfort (MFA setup and multiple steps of logging in). Further details about the concept of MFA can be found in the glossary.

General concept

Under normal circumstances, user’s passwords can easily end up in the wrong hands. Attacks like phishing require a relatively small amount of effort, target large groups of people and manage to steal formidable amounts of users' passwords.

One effective defense against these increasingly common attacks is requiring multiple factors of authentication. Typically, the first factor is the user’s password - some secret the user knows. The second factor is usually tied to user’s device like smartphone or physical token. Physical token represents something that the user has. For example, it can be a security key like YubiKey using WebAuthn authentication standard. Nowadays, more and more smartphones provide ways of authentication using biometrics like user’s fingerprint or face. These techniques are also supported by the WebAuthn standard as ways of verifying users. Users can also install TOTP applications which allow them to authenticate using single-use passwords.

Requiring password followed by another form of authentication like proving the possession of a physical token or having access to an app using biometric characteristics makes it much more difficult for potential attackers to gain access to user’s account.

Example of MFA flow

Implementation in ProxyIdP

Multi-factor authentication can be performed at the Identity Provider of user’s home organization (upstream IdP) if it is supported. In case it is not supported by the upstream IdP, it can be handled by ProxyIdP. The implementation of MFA in ProxyIdP uses simpleSAMLphp to perform the initial step of authentication and privacyIDEA to handle the second factor.

Using ProxyIdP for MFA comes with multiple configuration options which determine when and how it should be enforced. Further information about the available options can be found on the MFA enforcement page.

The diagram below shows the components used in ProxyIdP to achieve integration between simpleSAMLphp and privacyIDEA. This is one possible configuration out of several options. For example, it is possible to integrate privacyIDEA with ShibbolethIdP using the Shibboleth 2FA plugin. More IdP products and software integrations supported by privacyIDEA can be found on the privacyIDEA website.

Components of MFA implementation in ProxyIdP

ProxyIdP uses custom fork of simpleSAMLphp as an identity provider. In order to connect simpleSAMLphp with privacyIDEA, a plugin is needed. Stock version is available directly from the developers of privacyIDEA in their GitHub repository. Custom version with the same basic functionality and improved UX can be found in the Perun Proxy AAI GitLab repository. Any of those two variants can be used for MFA integration.

Furthermore, the basic configuration using simpleSAMLphp plugin automatically enables MFA for all users coming form simpleSAMLphp IdP at all times. Authswitcher is an additional plugin which allows for a more fine-grained approach. It adds the option to enable or disable MFA for individual users or groups.

Customized version of privacyIDEA used by ProxyIdP features an improved UI to help guide users through the token registration process. The simplest way to set up this custom privacyIDEA instance is to use the provided Ansible role which automates the configuration of a Docker container with preconfigured instance of privacyIDEA.

Technical configuration

PrivacyIDEA supports a wide array of modifications ranging from visual changes to complex policy management of users' tokens. ProxyIdP incorporates several functional and visual modifications in order to strike balance between the security of the final product and ease of use. These changes were subjected to several rounds of user testing to refine the flow of token registration process according to the users' needs.


PrivacyIDEA supports numerous token types, the complete list is can be found on their website. ProxyIdP works with three types of tokens chosen for their particular properties and modified to suit the needs of organizations implementing MFA and their users. These three token types in conjunction provide a reasonable baseline for large-scale MFA implementation. They offer a sufficiently secure, low barrier option for the vast majority of users (TOTP), advanced version with improved security (WebAuthn) and a way of recovery in case of a lost primary token (Backup code tokens).

  • Time-based one-time password (TOTP) has the lowest bar for entry. Most users already own smartphones and they are at least slightly familiar with the general concept according to our surveys. The process of token enrollment is fairly familiar and easy to perform for a wide variety of users when a step by step wizard is provided. This token type has not undergone any significant changes for ProxyIdP. It is not as secure as WebAuthn, however the potential for wide adoption makes it a good candidate for large-scale MFA implementation.

  • WebAuthn is less known among users, although it is supported by frequently used authentication tools like Apple’s FaceID/TouchID or Microsoft’s Windows Hello as well as security keys like YubiKey. It is considered more secure than TOTP, however fewer devices support this mode of authentication. Adoption of physical keys creates obstacles in form of added cost, distribution and replacement of lost tokens. That is why ProxyIdP allows, but does not enforce using WebAuthn as a second factor of authentication. Vanilla privacyIDEA supports only Packed and FIDO U2F attestation formats when attestations are required. Therefore, Android, Apple or Windows devices were not able to use any of their built-in WebAuthn means of authentication to provide an attestation and users had to mainly rely on security keys. The customized privacyIDEA used in ProxyIdP is equipped with a more capable library, py_webauthn, which supports all FIDO2-compliant authenticators. This way ProxyIdP supports all the available attestation types.

  • Backup codes are built upon TAN and Paper tokens from vanilla privacyIDEA. It is simply a list of single-use tokens exportable to a PDF which is supposed to be placed on a separate secure device or printed on paper and stored in a physically secure location. Compared to the Paper token in privacyIDEA, the single-use Backup code tokens have configurable length and character sets which allow for longer codes with bigger variability of characters. The number of generated tokens or the length of a token can be easily configured in the code and the backup codes can be used in any order.

Appearance and user experience

The customized privacyIDEA works with altered token enrollment flow devised from user research. Token enrollment wizard is enabled in ProxyIdP’s privacyIDEA policy configuration. This system can detect if the user does not have any usable tokens yet and initializes the first token enrollment flow. This comprises of five basic steps:

  • User selects a token to enroll from the supported token types (the initial enrollment supports only TOTP to enforce universal adoption of this token type among all users).

  • User is prompted to confirm they have a TOTP application on their mobile device. The system directly recommends two TOTP apps, Raivo OTP for iOS and Aegis Authenticator for Android together with QR codes for easy download. These are not the only options, just recommendations for less experienced users who are not using any TOTP apps already and do not feel the need to further research information about this topic.

  • User scans the generated QR code (or manually copies the necessary enrollment information to their application) and inputs the activation TOTP code to privacyIDEA. This enrolls the initial token. (Enrolling the initial token triggers requests that automatically update Perun’s information about user’s active token types and enforce the use of MFA on every service behind our login).

  • Backup code token is automatically generated for the user and proceeding further requires the user to either initialize printing process or save a PDF with the backup codes. This enforces that the user has access to at least two independent second factors of authentication before finishing the enrollment process.

  • In the end, the user can either register another token (this time TOTP, WebAuthn and Backup codes are all available), log out of the application (thus concluding the MFA activation process) or continue to a preconfigured MFA management site. There, the user can manage which applications will require MFA when logging in. In Perun IdM, the MFA enforcement for individual services is managed in user profile.

More comprehensive details about the MFA setup can be found in the MFA user manual. Details regarding the token enrollment process are located in the user documentation.

The entire flow of both initial and subsequent enrollment has been visually tweaked to better adhere to the basic UI and UX principles. Users can easily see which step of the process they are going through, the buttons, images and text placements are consistent across the process and unnecessary information is hidden until explicitly requested by the user.



Customizations of privacyIDEA include a new logging module which is used in cooperation with the original audit logging system. Provided Docker image is configured to use the container audit principle from vanilla privacyIDEA. This stores the regular audit info from original privacyIDEA in an SQL database. This includes information about users' actions with their tokens (enrollments, revocations, usage for authentication etc.) which can be viewed by the administrators as well as users in the privacyIDEA GUI.

On top of that, there is a new logger class which monitors actions like token enrollment, revocation, deletion, enabling and disabling which could potentially lead to the users “locking themselves out” by revoking, deleting or disabling all the usable tokens for MFA (distinction between these terms can be consulted in the privacyIDEA documentation). This custom audit module can be configured to send the logging information to several outputs. Base configuration in the attached Docker image sends the logs to the output stream and a database. Storing the logs in the database is necessary to make them visible in the privacyIDEA GUI. The Docker image’s GitLab page contains more detailed information about the custom logging and other configuration options.

Ansible role

Ansible role which automatically installs a preconfigured Docker container based on the image below

Docker image

Docker image with a custom fork of privacyIDEA with pre-prepared example configs.

GitLab repository

Custom fork of privacyIDEA with custom features described in this document. This code is launched in the Docker container provided above.