/
Configuring Email OTP
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring Email OTP

Jan 20, 2020

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.

Follow the instructions in the sections below to configure MFA using Email OTP:

Before 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. Therefore, make sure to download the samples before you begin.

  • 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.

Configure the email OTP provider

You can use WSO2 Identity Server as the email OTP provider or you can configure Gmail or SendGrid as the email OTP provider using Gmail or SendGrid APIs. Follow the instructions in one of these sections to set up the email OTP provider. 

Configure WSO2 IS as the email OTP provider

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

Alternatively, you can configure Gmail as the email OTP provider by following the instructions given in this section.

Configure Gmail as 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 mechanism to send the OTP.

Alternatively, you can configure WSO2 Identity Server as the email OTP provider by following the instructions given in this section.

  1. Create a Google account at https://gmail.com.

  2. Got to https://console.developers.google.com and click ENABLE APIS AND SERVICES.

  3. Search for Gmail API and click on it.

  4. Click Enable to enable the Gmail APIs.

  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. Copy the URL below and replace the <ENTER_CLIENT_ID> tag with the generated Client ID. This is required to generate the authorization code.

  12. Paste the updated URL into your browser.

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

    2. Click Allow.

    3. 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.

    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. 

[Back to Top]

Deploy the travelocity.com sample

Now that you have set up WSO2 IS or Gmail as the Email OTP provider, follow the steps below to deploy the travelocity.com sample application, which you can use to try out the Email OTP scenario. 

[Back to Top]

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]

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 travelocity.com 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:

    1. Issuer: travelocity.com

    2. Assertion Consumer URL: http://localhost:8080/travelocity.com/home.jsp

    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 http://wso2.org/claims/emailaddress 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.

[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]

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: http://wso2.org/claims/identity/emailotp_disabled

      2. Display Name: DisableEmailOTP

      3. Description: DisableEmailOTP

      4. Mapped Attribute (s): title

      5. Supported by Default: checked

    4. Click Add. 

[Back to Top]

Test the sample

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

  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 travelocity.com app.

[Back to Top]

What's next?

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.