Configuring TOTP Authenticator

Configuring user claims

1. Download the WSO2 Identity Server from here and run it.
2. Sign in to the Management Console by entering your username and password.
3. In the Main menu, click Add under Claims.

4. Click Add Local Claim. This displays the Add Local Claim screen.

   Note

   If you are using WSO2 Identity Server version 5.1.0 or 5.2.0, click Add New Claim. This displays the Add New Claim screen. On the Add New Claim screen, select http://wso2.org/claims as the Dialect.

5. Specify the following claim details in the appropriate fields:

   Claim URI	http://wso2.org/claims/identity/secretkey
   Display Name	Secret Key
   Description	Claim to store the secret key
   Mapped Attribute	stateOrProvinceName
   Supported by Default	selected

   

Deploying TOTP artifacts

1. Download the required TOTP artifacts from WSO2 Store. 

   If you are using WSO2 Identity Server version 5.5.0 or older, follow the steps below to manually add the commons-codec_1.4.0.wso2v1.jar file to WSO2 Identity Server:

   1. Create a directory with the name of the patch (for example, patch001) in the <IS_HOME>/repository/components/patches directory.
   2. Copy the commons-codec_1.4.0.wso2v1.jar file from the downloaded other_artifacts directory to the directory that you created in the above step.
2. Place the totpauthenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory.

3. Place the org.wso2.carbon.extension.identity.authenticator.totp.connector-x.x.x.jar into the <IS_HOME>/repository/components/dropins directory.

   If you want to upgrade the TOTP Authenticator that is available in your existing WSO2 Identity Server distribution, see the upgrade instructions.

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

   <AuthenticatorConfig name="totp" enabled="true">
               <Parameter name="encodingMethod">Base32</Parameter>
               <Parameter name="timeStepSize">30</Parameter>
               <Parameter name="windowSize">3</Parameter>
               <Parameter name="authenticationMandatory">true</Parameter>
               <Parameter name="enrolUserInAuthenticationFlow">true</Parameter>
               <Parameter name="usecase">local</Parameter>
               <Parameter name="secondaryUserstore">primary</Parameter>
               <Parameter name="TOTPAuthenticationEndpointURL">totpauthenticationendpoint/totp.jsp</Parameter>
               <Parameter name="TOTPAuthenticationEndpointErrorPage">totpauthenticationendpoint/totpError.jsp</Parameter>
               <Parameter name="TOTPAuthenticationEndpointEnableTOTPPage">totpauthenticationendpoint/enableTOTP.jsp</Parameter>
               <Parameter name="Issuer">WSO2</Parameter>
               <Parameter name="UseCommonIssuer">true</Parameter>
           </AuthenticatorConfig>

   The following table describes the definition of the parameters and the various values you can configure for federated authentication.

   Field	Description
   usecase	This field can take one of the following values: local, association, userAttribute, subjectUri. If you do not specify any usecase, the default value is local. If you have chosen userAttribute as the usecase, add the following parmeter to specify the user attribute. <Parameter name="userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
   encodingMethod	The encoding method which is used to generate the TOTP.
   authenticationMandatory	If this value is true, the TOTP authentication will be enforced as a second step.
   timeStepSize	The time step size, which is used to validate the TOTP.
   windowSize	The window size, which is used to validate the TOTP.
   enrolUserInAuthenticationFlow	If this value is true, it will ask the user to enable the TOTP authenticator in the authentication flow.
   secondaryUserstore	The user store configuration is maintained per tenant as comma separated values. For example, <Parameter name="secondaryUserstore">jdbc, abc, xyz</Parameter>.
   TOTPAuthenticationEndpointURL	This is the endpoint of the UI which is used to gather the TOTP.
   TOTPAuthenticationEndpointErrorPage	This is the endpoint of the error page.
   TOTPAuthenticationEndpointEnableTOTPPage	This is the endpoint of the TOTPauthenticator enrollment page.
   Issuer	This is the issuer name which will be shown the Mobile Application. If not configured, tenant domain will be shown.
   UseCommonIssuer	If true, the issuer name defined in application-authentication.xml will be used as the issuer for all the tenants.

5. Place the authenticator parameters as above into the <IS_HOME>/repository/conf/identity/application-authentication.xml file.  An admin can activate the feature to enable the TOTP authenticator in the authentication flow by changing the enrolUserInAuthenticationFlow values (true or false). 

   1. If you specify that the user can enable TOTP in the authentication flow (<Parameter name="enrolUserInAuthenticationFlow">true</Parameter>) and the TOTP is not enabled to the user's profile, you will be asked to enable TOTP in the in the authentication flow. If you don't enable it at this stage, the TOTP error page appears. 
   2. If you specify that the user can't enable TOTP in the authentication flow (<Parameter name="enrolUserInAuthenticationFlow">false</Parameter>) and the TOTP is not enabled to the user's profile, the TOTP error page appears. 
6. Replace the <IS_HOME>/repository/deployment/server/jaggeryapps/portal/gadgets/user_profile file with the corresponding user-profile provided under other_artifacts/user_profiles/.
   
   • Use 5.1.0/user_profile if you are using WSO2 Identity Server 5.1.0.
     
   • Use 5.2.0/user_profile if you are using WSO2 Identity Server 5.2.0.
     
   • Use 5.2.0/wum_update/user_profile if you are using WSO2 Identity Server 5.2.0 wum updated pack.
     
   • Use 5.3.0/user_profile if you are using WSO2 Identity Server 5.3.0.

   This step must be done since the user_profile that is shipped with the WSO2 Identity Server does not support TOTP out-of-the-box. Due to some changes in the Identity Server framework for each product release version, a different user profile is required for different versions. However, if you are using WSO2 Identity Server 5.4.0 upwards, then you do not need to replace the user_profile since WSO2 Identity Server has corresponding user_profile required out-of-the-box.

   Comment the <module ref="addressing"/> module from the <IS_HOME>/repository/conf/axis2/axis2.xml file.

7. If you use the secondary user store, enter all the user store values for the particular tenant as comma separated values. Make this configuration change in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section. For example, <Parameter name="secondaryUserstore"> jdbc, abc, xyz</Parameter>.

Deploying travelocity.com sample app

The next step is to deploy the sample app in order to use it in this scenario.

Once this is done, the next step is to configure the WSO2 Identity Server by configuring resident identity provider and service provider.

Configuring the identity provider

Now you have to configure WSO2 Identity Server.

1. Restart WSO2 Identity Server.
2. Log in to the management console as an administrator.
3. Login to the end user dashboard and go to My Profile by clicking View details.
   
4. Update your email address (this email address is used to send the token). 
5. To enable TOTP, select the Enable TOTP checkbox. 
   
6. If you want to use the Google Authenticator Application to generate the one-time passwords (tokens), click on Scan QR Code to scan the QR-Code using the Google Authenticator mobile app.
   

You have now configured TOTP.

https://localhost:9443/services/TOTPAdminService?wsdl

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic YWRtaW46YWRtaW4=' https://localhost:9443/services/TOTPAdminService/initTOTP -k -d 'username=testuser@carbon.super'

<ns:initTOTPResponse xmlns:ns="http://services.totp.authenticator.application.identity.carbon.wso2.org"><ns:return>b3RwYXV0aDovL3RvdHAvY2FyYm9uLnN1cGVyOmR1c2hhbmk/c2VjcmV0PUJGR0RFUllPU1ZSR0s3&#xd;
TE0maXNzdWVyPWNhcmJvbi5zdXBlcg==&#xd;
</ns:return></ns:initTOTPResponse>

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded'  -H 'Authorization:Basic YWRtaW46YWRtaW4=' https://localhost:9443/services/TOTPAdminService/retrieveSecretKey -k -d 'username=testuser@carbon.super'

<ns:retrieveSecretKeyResponse xmlns:ns="http://services.totp.authenticator.application.identity.carbon.wso2.org"><ns:return>4AAC2HEG7COGHQYI</ns:return></ns:retrieveSecretKeyResponse>

Configuring the Identity Server to send email

1. Configure the <IS_HOME>/repository/conf/axis2/axis2.xml to send an email notification. Enable the mailto transport sender by adding the following configuration. Replace your sender email credentials (USER_NAME, PASSWORD, and SENDER'S_MAIL) in the configuration.

   SMTP Transport Sender

   <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
       <parameter name="mail.smtp.host">smtp.gmail.com</parameter>
       <parameter name="mail.smtp.port">587</parameter>
       <parameter name="mail.smtp.starttls.enable">true</parameter>
       <parameter name="mail.smtp.auth">true</parameter>
       <parameter name="mail.smtp.user">{USER_NAME}</parameter>
       <parameter name="mail.smtp.password">{PASSWORD}</parameter>
       <parameter name="mail.smtp.from">{SENDER'S_MAIL}</parameter>
   </transportSender>

2. Add the email template that must be sent to the user when they generate the token in the  <IS_HOME>/repository/conf/email/email-admin-config.xml file as follows.
   

   Email Template

   <configuration type="totp" display="TOTP" locale="en_US">
       <targetEpr></targetEpr>
       <subject>WSO2 Carbon - Time-Based One Time Password</subject>
       <body>
   Hi {{ user.claim.givenname}},
   Please use the token {totp-token} as the password for your login.
       </body>
       <footer>
   Best Regards,
   WSO2 Identity Server Team
   http://www.wso2.com
       </footer>
       <redirectPath></redirectPath>
   </configuration>  

Configuring the service provider

The next step is to configure the service provider.

1. Return to the management console.

2. In the Service Providers section under the Main tab, click Add.

3. Since you are using travelocityas the sample, enter travelocity.com in the Service Provider Name text box.

4. Enable " SaaS Application" if you want to open up the application for all the users of all the tenants and click Register.

5. In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.

6. Now set the configuration as follows:

   1. Issuer: travelocity.com

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

7. Selectthefollowingcheck-boxes:

   1. Enable Response Signing.

   2. Enable Single Logout.

   3. Enable Attribute Profile.

   4. Include Attributes in the Response Always.
      

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

9. Go to the Local and Outbound Authentication Configuration section.

10. Select the Advanced configuration radio button option.

11. Add basic or federated authentication as the first step and TOTP authentication as the second step and click Update to save the changes.The first step may be local authenticator (basic) or a federated authenticator (e.g., Facebook, Twitter, etc.)

    1. Select the local authenticator in the first step then select the local authenticator (e.g., basic) from the drop-down.

    2. Select the federated authenticator in the first step, then select federated authenticator (e.g., Twitter) from the drop-down.

    3. Configure the following parameter in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the  <AuthenticatorConfig name="totp" enabled="true"> section.

       <Parameter name="usecase">userAttribute</Parameter> 

       The following table includes the definition of the parameter and the various values you can choose.

       Value	Description
       usecase	This field can take one of the following values: local, association, userAttribute, and subjectUri. If you do not specify any usecase, the default value is local.
       local	This is based on the federated username. This is the default. You must set the federated username in the local user store. Basically, the federated username must be the same as the local username.
       association	Federated username must be associated with the local account in advance in the Dashboard. So local username is retrieved from the association.To associate the user, Login to the end user dashboard and go to Associated Account by clicking View details.
       userAttribute	The name of the federated authenticator's user attribute. That is, the local username which is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="totp" enabled="true">  section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file and put the value (e.g., email, screen_name, id, etc.). <Parameter name="userAttribute">email</Parameter> If you use OpenID Connect supported authenticators such as LinkedIn, Foursquare, etc., or in the case of multiple social login options as the first step and TOTP as second step, 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 as follows (the following shows the configuration for Foursquare, LinkedIn and Facebook authenticator respectively). Inside the AuthenticatorConfig (i.e., Foursquare), add the specific userAttribute with a prefix of the (current step) authenticator name (i.e.,totp-userAttribute). <AuthenticatorConfig name="Foursquare" enabled="true"> <Parameter name="totp-userAttribute">http://wso2.org/foursquare/claims/email</Parameter> </AuthenticatorConfig> <AuthenticatorConfig name="LinkedIn" enabled="true"> <Parameter name="totp-userAttribute">http://wso2.org/linkedin/claims/emailAddress</Parameter> </AuthenticatorConfig> <AuthenticatorConfig name="FacebookAuthenticator" enabled="true"> <Parameter name="totp-userAttribute">email</Parameter> </AuthenticatorConfig> Likewise, you can add the AuthenticatorConfig for Amazon, Google, Twitter and Instagram with relevant values.
       subjectUri	When 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 TOTP authenticator.

       The configuration in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section will look like the following.

       Parameter Values

       <AuthenticatorConfig name="totp" enabled="true">
           <Parameter name="encodingMethod">Base32</Parameter>
           <Parameter name="timeStepSize">30</Parameter>
           <Parameter name="windowSize">3</Parameter>
           <Parameter name="authenticationMandatory">true</Parameter>
           <Parameter name="enrolUserInAuthenticationFlow">true</Parameter>
           <Parameter name="usecase">userAttribute</Parameter>
           <Parameter name="userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
           <Parameter name="secondaryUserstore">primary</Parameter>
           <Parameter name="TOTPAuthenticationEndpointURL">https://localhost:9443/totpauthenticationendpoint/totp.jsp</Parameter>
           <Parameter name="TOTPAuthenticationEndpointErrorPage">https://localhost:9443/totpauthenticationendpoint/totpError.jsp</Parameter>
           <Parameter name="TOTPAuthenticationEndpointEnableTOTPPage">https://localhost:9443/totpauthenticationendpoint/enableTOTP.jsp</Parameter>
       </AuthenticatorConfig>

You have now added and configured the service provider.

Testing the sample

1. To test the sample, go to the following URL: http://<TOMCAT_HOST>:<TOMCAT_PORT>/travelocity.com/index.jsp. For example, this looks like http://localhost:8080/travelocity.com.
   

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

3. The basic authentication page is visible. Use your username and password to log in.
   
4. If the TOTP is not enabled toin the user's profile and the user is allowed to enable the TOTP in the authentication flow, this page will appear. You can scan either continue or cancel.
   
5. If you want to enrolthe user, click on the link to show the QR code. Scan the displayed QR code using the mobile application and continue.
6. You are redirected to the TOTP authentication page. Enter the verification code from your Google Authenticator Mobile Application to authenticate. Alternatively, you can generate the verification code by clicking on Get a Verification Code" and use the code that is sent to your email address.
   

7. If your verification is successful, you are taken to the home page of the travelocity.com app.