This documentation is for WSO2 Identity Server 5.3.0 . View documentation for the latest release.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


About multi-factor authentication

With the rapid growth of the internet, more and more services are available for use by enterprises and organizations. However, username and password based authentication still plays a major role in authenticating users, and it is essential to use a strong password to keep your computer, data, and accounts safe. However, if you are like most users, you will find that it is challenging to remember a strong password, especially if you have to change it once in awhileDue to increasing digital crimes and internet fraud in the world, people are highly concerned about the topic of online security. And it is obvious that traditional user ID and password login is not enough to secure the authentication. Processing speeds of CPUs have increased, so brute force attacks are a reality and dictionary attacks have become a common threat. GPGPU password cracking and rainbow tables have provided similar advantages to attackers.

Multi-factor Authentication (MFA) creates a layered defense defence and makes it more difficult for an unauthorized person to access a target such as a physical location, computing device, Web web service, network or a database. If one factor is compromised or broken, the attacker still has at least one more barrier to breach before successfully breaking into the target.

Authentication factors in MFA rely relies on two or more independent credentials of the three categories.


With a combination of two or more factors from the above three, the user is authenticated. A basic example is when withdrawing money with an ATM card; the card is the possession factor and the pin number is the knowledge factor.

MFA with WSO2 Identity Server

WSO2 Identity server allows configuring multi-step authentication where you can define an authentication chain containing different authenticators in different steps. So we can convert this chain to a Multi-factor authentication chain adding different factors of authentication to each step. For example, we can configure User-ID/ Password authentication as 1st factor (Knowledge factors) and then FIDO authentication as 2nd factor (Possession factors)

Image Added

WSO2 Identity Server has comprehensive support for multi-factor authentication, with authenticators available for SMSOTP, FIDO, MEPin and more (for a complete list on the readily available authenticators, click here). 

Configuring multi-factor authentication for WSO2


Identity Server

  1. Start the WSO2 IS server and login to the management console.
  2. Click Add under Service Providers on the Main tab. Enter a service provider name and click Register
    Since the service provider is for the WSO2 Identity Server itself, in this tutorial the service provider is referred to as 'self'. 
  3. Expand Inbound Authentication Configuration>SAML2 Web SSO Configuration and click Configure
  4. Select Manual Configuration and enter the following details. Click Register
    1. Issuer - carbonServer
    2. Assertion Consumer URLs - https://localhost:9443/acs
    3. Enable Response Signing - true
  5. Expand Local and Outbound Authentication Configuration and select Advanced Configuration to configure multi-factor authentication.
    There are two types of multi-factor authentication that you can configure here. 
    • Multi-option authentication: This can be configured by clicking Add Authenticator. Clicking this again will enable you to create another authentication option. These can be either local or federated authenticators.
    • Multi-step authentication: This is configured by clicking Add Authentication Step. Clicking this again will enable you to create another authentication step. These can be either local or federated authenticators.
  6. Click Add Authenticator to add a Local Authenticator. You can choose the type of authenticator using the dropdown. Clicking Add Authenticator again will enable you to add a second local authenticator and configure multi-option authentication using two local authenticators. Alternatively, you can click Add Authentication Step and configure a Local Authenticator in one step by selecting the local authenticator from the dropdown and clicking Add Authenticator. You can do the same for the second step.

    As an example for this scenario, basic and fido are used as the two authenticators. Basic authentication allows you to authenticate users from the enterprise user store while FIDO authenticates you externally.


    If you are adding FIDO as an authenticator, see Multi-factor Authentication using FIDO for more information and follow the instructions given in the topic to configure it.

  7. Select whether this is a Subject StepAttribute Step or both. In the case of multiple steps, you can have only one step as the subject step and one as the attribute step.
  8. Click the Update button. 
  9. This navigates you to the previous screen with your newly configured authentication steps. Click Update again to save changes. 
  10. Shutdown WSO2 IS and open the authenticators.xml file found in the <IS_HOME>/repository/conf/security folder.
  11. Enable the SAML2SSOAuthenticator by changing the disabled parameter to false

    Code Block
    <Authenticator name="SAML2SSOAuthenticator" disabled="false">
  12. Change the value of the <Priority> property found under the SAML2SSOAuthenticator to 1. 

    Code Block
  13. Save and close the authenticators.xml file.