Versions Compared


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

This section provides the instructions to configure multi-factor authentication (MFA) using Email One Time Password (Email OTP) in WSO2 Identity Server (WSO2 IS). The Email OTP enables a one-time password (OTP) to be used at the second step of MFA. For more information on the WSO2 Identity Server Versions supported by the connector, see the IS Connector store.

Let's take a look at the tasks you need to follow to configure MFA using Email OTP:

Table of Contents

titleBefore you begin!
  • To ensure you get the full understanding of configuring Email OTP with WSO2 IS, the sample travelocity application is used in this use case. The samples run on the Apache Tomcat server and are written based on Servlet 3.0. Therefore, download Tomcat 7.x from here.
  • Install Apache Maven to build the samples. For more information, see Installation Prerequisites.

Enabling email configuration on WSO2 IS

Follow the steps below to configure WSO2 IS to send emails once the Email OTP is enabled.

  1. Shut down the server if it is running.
  2. Open the  <IS_HOME>/repository/conf/axis2/axis2.xml file, uncomment the transportSender name = "mailto" configurations, and update the following properties:

    mail.smtp.fromProvide the email address of the SMTP account.
    mail.smtp.userProvide the username of the SMTP account.
    mail.smtp.passwordProvide the password of the SMTP account.
    Code Block
    <transportSender  name="mailto"
        <parameter  name="mail.smtp.from">{SENDER'S_EMAIL_ID}</parameter>
    	<parameter  name="mail.smtp.user">{USERNAME}</parameter>
    	<parameter  name="mail.smtp.password">{PASSWORD}</parameter>
    	<parameter  name=""></parameter>
        <parameter  name="mail.smtp.port">587</parameter>
        <parameter  name="mail.smtp.starttls.enable">true</parameter>
        <parameter  name="mail.smtp.auth">true</parameter>
  3. Comment out the <module ref="addressing"/> property to avoid syntax errors.

    Code Block
    <!-- <module ref="addressing"/> -->
  4. Add the following email template to the <IS_HOME>/repository/conf/email/email-admin-config.xml.

    Code Block
    <configuration type="EmailOTP" display="idleAccountReminder" locale="en_US" emailContentType="text/html">
       <subject>WSO2 IS Email OTP</subject>
          Please use this one time password {OTPCode} to sign in to your application.
          Best Regards,
          WSO2 Identity Server Team

  5. Configure the following properties in the <PRODUCT_HOME>/repository/conf/identity/ file to true.

    Code Block
  6. Add the following configuration to the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section.

    Code Block
    <AuthenticatorConfig name="EmailOTP" enabled="true">      
          <Parameter name="EMAILOTPAuthenticationEndpointURL">https://localhost:9443/emailotpauthenticationendpoint/emailotp.jsp</Parameter>
          <Parameter name="EmailOTPAuthenticationEndpointErrorPage">https://localhost:9443/emailotpauthenticationendpoint/emailotpError.jsp</Parameter>
          <Parameter name="EmailAddressRequestPage">https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp</Parameter>
          <Parameter name="usecase">association</Parameter>
          <Parameter name="secondaryUserstore">primary</Parameter>
          <Parameter name="EMAILOTPMandatory">false</Parameter>
          <Parameter name="sendOTPToFederatedEmailAttribute">false</Parameter>
          <Parameter name="federatedEmailAttributeKey">email</Parameter>
          <Parameter name="EmailOTPEnableByUserClaim">true</Parameter>
          <Parameter name="CaptureAndUpdateEmailAddress">true</Parameter>
          <Parameter name="showEmailAddressInUI">true</Parameter>
    titleTo view the parameter definitions, click here
    ParameterDescriptionSample Values

    This parameter defines how the email ID will be retrieved. The default value is local.

    titleClick here to view the value definitions
    localThis is the default value and is based on the federated username. You must set the federated username in the local userstore . The federated username must be the same as the local username.
    associationThe federated username must be associated with the local account in advance in the end user dashboard. The local username is retrieved from the association. To associate the user, log into the  end user dashboard  and go to  Associated Account  by clicking  View details .
    subjectUriWhen configuring the federated authenticator, select the attribute in the subject identifier under the service provider section in UI, this is used as the username of the  EmailOTP authenticator.

    The name of the  federatedauthenticator'suserattribute. That is the local username that is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="EmailOTP" enabled="true">  section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file and put the value, e.g., email and screen_name, id.

    Code Block
    <Parameter name="userAttribute">email</Parameter>

    If you use OpenID Connect supported authenticators such as LinkedIn and Foursquare or in the case of multiple social login options as the first step and EmailOTP assecondstep, you need to add similar configuration for the specific authenticator in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section.



    Code Block
    <AuthenticatorConfig name="Foursquare" enabled="true">
        <Parameter name="EmailOTP-userAttribute"></Parameter>
        <Parameter name="federatedEmailAttributeKey"></Parameter>


    Code Block
    <AuthenticatorConfig name="LinkedIn" enabled="true">
        <Parameter name="EmailOTP-userAttribute"></Parameter>
        <Parameter name="federatedEmailAttributeKey"></Parameter>


    Code Block
    <AuthenticatorConfig name="FacebookAuthenticator" enabled="true">
    	<Parameter name="EmailOTP-userAttribute">email</Parameter>
    	<Parameter name="federatedEmailAttributeKey">email</Parameter>

    Likewise, you can add the Authenticator Config for Amazon, Google, Twitter, and Instagram with the relevant values.

    • local
    • association
    • userAttribute
    • subjectUri

    You can define multiple user stores per tenant as comma separated values.


    Code Block
    <Parameter name="secondaryUserstore">jdbc, abc, xyz</Parameter>

    The user store configurations are maintained per tenant:

    • If you use a super tenant, set all the parameter values into the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section.
    • If you use a tenant,
      • Upload the same XML file (application-authentication.xml) into a specific registry location (/_system/governance/EmailOTP).
      • Create the collection named EmailOTP, add the resource and upload the application-authentication. xml file into the registry.
      • While doing the authentication,thesysetmfirstcheckswhetherthereisanXML file uploaded to the registry. If that is so, it reads it from the registry but does not take the local file. If there is no file in the registry, then it only takes the property values from the local file.
      • You can use the registry or local file to get the property values.

    Thisparmeterdefineswhtherthe EmailOTP is enforced as the second step of the 2FA/MFA or not.
      • If the user is not found in the active directory where the parameter is set to true, the OTP is directly sent to the email address defined in the claims set.

      • If the user is not found in the active directory where the parameter is set to false , the authentication flow terminates at the first step of the 2FA/MFA.

    • true
    • false

    When the EMAILOTPMandatory and this parameter are set to true and the user is not found in the active directory, the OTPissetn to the mail defined in the federated authenticator claim.

    When the EMAILOTPMandatory is set to false, an error page gets displayed.

    When the EMAILOTPMandatory is set to false and the user is not found in the active directory, the authentication mechanism terminates at the first step of the 2FA/MFA. This parameter is not required in such a scenario.

    • true
    • false
    This parameter identifies the email attribute of the federated authenticator, e.g. Foursquare. Set this parameter if the sendOTPToFederatedEmailAttribute is set to true. Example:
    This parameter enables the user to overidethefunctionalitydefinedattheEMAILOTPMandatory parameter.
      • If this parameter and the EMAILOTPMandatory parameters are set to true, the user can either enable or disable the EmailOTP functionality.
      • If this parameter is set to false where the EMAILOTPMandatory parameter is set to true, the user gets redirected to an error page.
      • If this parameter and the EMAILOTPMandatory parameters are set to false, the authentication flow terminates at the first step of the 2FA/MFA.
      • If the user is not available in the active directory
    • true
    • false

    This parameter enables the user to update the email address that is used to send the OTP, at the first login where the email address is not previously set.

    • true
    • false

    This parameter enables to display a page that requests for an email address where

      • The user has not registered an email address.
      • Sending OTP is defined as the second step of 2FA/MFA.
      • The CaptureAndUpdateEmailAddress parameter is set to true.

    Example: https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp


    This parameter enables to display the email address to which the OTP is sent to on the UI.

    • true
    • false
  7. Start WSO2 IS.

Configuring the EmailOTP provider
Configuring the EmailOTP provider
Configure the Email OTP provider

You can send the One Time Password (OTP) using Gmail APIs or using SendGrid. Follow the steps given below to configure Gmail APIs as the mechanisam to send the OTP.

  1. Create a Google account at
  2. Got to and click ENABLE APIS AND SERVICES.
  3. Search for Gmail API and click on it.
  4. Click Enable to enable the Gmail APIs.

    titleWhy is this needed?

    If you do not enable the Gmail APIs, you run in to a 401 error when trying out step13.

  5. Click Credentials and click Create to create a new project.
  6. Click Credentials and click the Create credentials drop-down.

  7. Select OAuth client ID option.

  8. Click Configure consent screen.
  9. Enter the Product name that needs to be shown to users, enter values to any other fields you prefer to update, and click Save.
  10. Select the Web application option.
    Enter https://localhost:9443/commonauth as the Authorize redirect URIs text-box, and click Create.


    The client ID and the client secret are displayed.
    Copy the client ID and secret and keep it in a safe place as you require it for the next step.

  11. Anchor
    Copy the URL below and replace the <ENTER_CLIENT_ID> tag with the generated Client ID. This is required to generate the authorization code.

    Tabs Container
    Tabs Page
    Code Block<ENTER_CLIENT_ID>&
    Tabs Page
    Code Block
  12. Paste the updated URL into your browser.

    1. Select the preferred Gmail account with which you wish to proceed.

    2. Click Allow.
    3. Anchor
      Obtain the authorization code using a SAML tracer on your browser.

  13. To generate the access token, copy the following cURL command and replace the following place holders:

    1. <CLIENT-ID> : Replace this with the client ID obtained in Step 10 above.
    2. <CLIENT_SECRET> : Replace this with the client secret obtained in Step 10 above.
    3. <AUTHORIZATION_CODE> : Replace this with the authorization code obtained in Step 12 above.


    Tabs Container
    Tabs Page
    Code Block
    curl -v -X POST --basic -u <CLIENT-ID>:<CLIENT_SECRET> -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=https://localhost:9443/commonauth"
    Tabs Page
    Code Block
    curl -v -X POST --basic -u -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=4/KEDlA2KjGtib4KlyzaKzVNuDfvAmFZ10T82usT-6llY#&redirect_uri=https://localhost:9443/commonauth"
    Tabs Page
    titleSample Response
    Code Block
    > POST /oauth2/v3/token HTTP/1.1
    > Host:
    > Authorization: Basic OTk3NDE2ODczOTUwLWY4Y2N1YnJobW1ramdkYXNkNnZkZ2tzOGxoaWExcnRhLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tOkJkNlBoY3ZVWXFrM1BhdnA4ZjBZcUQtMw==
    > User-Agent: curl/7.54.0
    > Accept: */*
    > Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    > Content-Length: 127
    < HTTP/1.1 200 OK
    < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
    < Pragma: no-cache
    < Expires: Mon, 01 Jan 1990 00:00:00 GMT
    < Date: Wed, 10 Jan 2018 08:29:57 GMT
    < Vary: X-Origin
    < Content-Type: application/json; charset=UTF-8
    < X-Content-Type-Options: nosniff
    < X-Frame-Options: SAMEORIGIN
    < X-XSS-Protection: 1; mode=block
    < Server: GSE
    < Alt-Svc: hq=":443"; ma=2592000; quic=51303431; quic=51303339; quic=51303338; quic=51303337; quic=51303335,quic=":443"; ma=2592000; v="41,39,38,37,35"
    < Accept-Ranges: none
    < Vary: Origin,Accept-Encoding
    < Transfer-Encoding: chunked
     "access_token": "ya29.Gls-BbTUseE2f-Lrc9q0QtdlvIoYFTg2zkYPsXHwgob4pHAFlE66GMgJjwTHT9eHfivhVcATROzU8FaUgt0wVL1sz-7IsC2Slfpdm6i3uFcurNTFbTlABk3jKJ--",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "1/8pMBx_lrUyitknmGzzH-yOcvoPIZ1OqhPeWvcYJOd0U"

    Paste the updated cURL command in your terminal to generate the OAuth2 access token, token validity period, and the refresh token. 

  14. Update the following configurations under the  <AuthenticatorConfigs>  section in the  <IS_HOME>/repository/conf/identity/application-authentication.xml  file. 

    • If you need to send the content in a payload, you can introduce a property in a format <API> Payload and define the value. Similarly, you can define the Form Data.FormdataforSendgridAPIisgivenasan example.
    • You can use <API> URLParams, <API>AuthTokenType, <API>Failure and <API>TokenEndpoint property formats to specify the URL parameters, Authorization token type, Message to identify failure and Endpoint to get access token from refresh token respectively.
    • Value of <API> URLParams should be like; api_user=<API_USER>&api_key=<API_KEY>&data=<DATA>&list<LIST>
    GmailClientIdEnter the Client ID you got in step 10.
    GmailClientSecretEnter the client secret you got in step 10.
    Example: dj4st7_m3AclenZR1weFNo1V
    SendgridAPIKeyThis property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
    GmailRefreshTokenEnter the refresh token that you got as the response in step 12. Example: 1/YgNiepY107SyzJdgpynmf-eMYP4qYTPNG_L73MXfcbv
    GmailEmailEndpointEnter your username of your Gmail account in place of the [userId] place holder. Example:
    SendgridEmailEndpointThis property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.

    Use the default value.


    This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.

    SendgridFormData=toThis property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
    SendgridURLParamsThis property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
    GmailAuthTokenType Use the default value.
    GmailTokenEndpointUse the the deafult value.
    SendgridAuthTokenTypeThis property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
    titleClick here to see a sample configuration
    Code Block
    <AuthenticatorConfig name="EmailOTP" enabled="true">
       <Parameter name="GmailClientId"> </Parameter>
       <Parameter name="GmailClientSecret">dj4st7_m3AclenZR1weFNo1V</Parameter>
       <Parameter name="SendgridAPIKey">sendgridAPIKeyValue</Parameter>
       <Parameter name="GmailRefreshToken">1/YgNiepY107SyzJdgpynmf-eMYP4qYTPNG_L73MXfcbv</Parameter>
       <Parameter name="GmailEmailEndpoint"></Parameter>
       <Parameter name="SendgridEmailEndpoint"></Parameter>
       <Parameter name="accessTokenRequiredAPIs">Gmail</Parameter>
       <Parameter name="apiKeyHeaderRequiredAPIs">Sendgrid</Parameter>
       <Parameter name="SendgridFormData">sendgridFormDataValue</Parameter>
       <Parameter name="SendgridURLParams">sendgridURLParamsValue</Parameter>
       <Parameter name="GmailAuthTokenType">Bearer</Parameter>
       <Parameter name="GmailTokenEndpoint"></Parameter>
       <Parameter name="SendgridAuthTokenType">Bearer</Parameter>
       <Parameter name="redirectToMultiOptionPageOnFailure">false</Parameter>
       <Parameter name="usecase">association</Parameter> 
       <Parameter name="useEventHandlerBasedEmailSender">true</Parameter>	

[Back to Top]

Deploying sample
Deploying sample
Deploy the sample

Follow the steps below to deploy the sample application:

Excerpt Include
Deploying the Sample App
Deploying the Sample App

[Back to Top]

Configuring the identity provider
Configuring the identity provider
Configure the Identity Provider

Follow the steps below to add an identity provider:

  1. Click Add under Main > Identity > Identity Providers.
  2. Provide a suitable name for the identity provider.
  3. Expand the  EmailOTPAuthenticator Configuration under Federated Authenticators.
    1. Select the Enable and Default check boxes.

    2. Click Register.

    You have now added the identity provider.

[Back to Top]

Configuring the service provider
Configuring the service provider
Configure the Service Provider

Follow the steps below add a service provider:

  1. Return to the Management Console home screen.

  2. Click Add under Add under Main > Identity > Service Providers .

  3. Enter as the Service Provider Name.

  4. Click Register.

  5. Expand SAML2 Web SSO Configuration under Inbound Authentication Configuration.

  6. Click Configure.

  7. Now set the configuration as follows:


    2. Assertion Consumer URLhttp://localhost:8080/

    3. Select the following check-boxes: Enable Response Signing, Enable Single Logout, Enable Attribute Profile, and Include Attributes in the Response Always.

  8. Click Update to save the changes. Now you will be sent back to the Service Providers page.

  9. Go to Claim Configuration and select the claim.

  10. Go to Local and Outbound Authentication Configuration section.

    1. Select the Advanced configuration radio button option.

    2. Creating the first authentication step:

      1. Click Add Authentication Step.

      2. Click Add Authenticator that is under Local Authenticators of Step 1 to add the basic authentication as the first step.
        Adding basic authentication as a first step ensures that the first step of authentication will be done using the user's credentials that are configured with the WSO2 Identity Server
    3. Creating the second authentication step:

      1. Click Add Authentication Step.

      2. Click Add Authenticator that is under Federated Authenticators of Step 2 to add the SMSOTP identity provider you created as the second step.
        SMSOTP is a second step that adds another layer of authentication and security.

  11. Click Update.

    You have now added and configured the service provider.


    For more information on service provider configuration, see Configuring Single Sign-On.

[Back to Top]

Update the email address of the user

Follow the steps given below to update the user's email address.

  1. Return to the WSO2 Identity Server Management Console home screen.
  2. Click List under Add under Main > Identity > Users and Roles
    1. Click Users
    2. Click User Profile under Admin
    3. Update the email address.    
    4. Click Update.

[Back to Top]

Configuring User Claim
Configuring User Claim
Configure the user claims

Follow the steps below to map the user claims:


For more information about claims, see  Adding Claim Mapping

  1. Click Add under Main > Identity > Claims.

    1. Click Add Local Claim.
    2. Select the Dialect from the drop down provided and enter the required information.
    3. Add the following:

      1. Claim URI:
      2. Display Name: DisableEmailOTP
      3. Description: DisableEmailOTP
      4. Mapped Attribute (s): title
      5. Supported by Default: checked

    4. Click Add


      To disable this claim for the admin user, navigate to Users and Roles > List and click Users. Click on the User Profile link corresponding to admin account and then click Disable EmailOTP. This will disable the second factor authentication for the admin user.

[Back to Top]

Testing the sample
Testing the sample
Test the sample

  1. To test the sample, go to the following URL: http://localhost:8080/

  2. Click the link to log in with SAML from WSO2 Identity Server.

  3. The basic authentication page appears. Use your WSO2 Identity Server credentials.

  4. You receive a token to your email account. Enter the code to authenticate. If the authentication is successful, you are taken to the home page of the app.

[Back to Top]