Overview

Let's analyse one of the most common methods for multi-factor authentication (MFA), which is Time-based One Time Password (TOTP).

Why TOTP?

One of the main disadvantages of SMS OTP is that it has transaction fees. Every time a user receives a text message to confirm her identity, someone is paying for the delivery of that text message. Usually, the service provider has set up an SMS gateway from a mobile operator and is paying recurring costs for every transaction.

SMS OTP also has a attritional impact, for instance one wants to confirm a payment and the one-time code never arrives to the phone or gets delayed which forces people to try again. There are attrition rates associated with SMS of between 10% and 30%.

An alternative is TOTP.

In this lab, you will learn the whole process required to enable TOTP for users. There are three main parts:

1. Enable TOTP on the Identity Platform

2. Enroll users to TOTP method

3. Authenticate using TOTP as second factor authentication

Open

A few steps must be done on the Identity Platform side, and then the user will also do configurations before we can see the authentication.

Instructions

Let’s get started.

Part 1. Enable TOTP on the Identity Platform

In real projects, this Part 1 is done by the system integrator prior to launching the 2FA to production.

Step 1: Configure TOTP API

TOTP API has to be activated and configured according to instructions in TOTP API configuration - SSO

1. Copy the file server.xml from C:\Program Files\Ubisecure\ubilogin-sso\tomcat\conf to C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat
   
   

2. Find the line below and un-comment it.
   
   

   <Context path="/totp" docBase="${catalina.base}/webapps/totp" />

    

3. Update Tomcat. Open the command prompt and execute these two commands:
   
   

   cd "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config\tomcat" update.cmd

    

4. To verify that TOTP API has successfully started, check the logs. Confirm that no unexpected errors have occurred since the previous restart.
   
   

5. First, on the SSO diag log file you should find these two lines:
   
   C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\logs\sso_diag.YYYY-MM-DD.log

   YYYY-MM-DD hh:mm:ss,SSS init Ubilogin Authentication Server X.X.X started YYYY-MM-DD hh:mm:ss,SSS tech ping: the system is alive

    

6. On the same file log file you should find this line:
   
   C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\logs\sso_diag.YYYY-MM-DD.log

    

7. If the system does not start, you may find more information in these log files: C:\Program Files\Ubisecure\ubilogin-sso\tomcat\logs\catalina.YYYY-MM-DD.log or C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\logs\sso_diag.YYYY-MM-DD.log
   
   

8. Import certificates. As TOTP API connects to the SSO OAuth 2.0 endpoints, the issuer of the TLS certificate on those endpoints must be trusted by the Java installation. As you must remember, we’re using self-signed certificates.

9. Open the command prompt.

10. First, go where keytool is located
    
    

     

11. Next, execute:
    
    

     

12. If the command was successfully executed, you will see the response below.
    
    

    Open

    

Step 2: Get access to the API

Now that the TOTP API has been activated, we can start using it.

TOTP API will help you (1) initialise users for a specific TOTP method, (2) generate the secret for a user, as well as (3) modify the TOTP status of a user.

First of all, we need to create a user that will be authorized to perform all TOTP API calls. Let’s call it totp-api-user.

1. Open SSO Management Console and go to Site Navigator / System / TOTP API / Users. Click on “New User…” button that is at the bottom.

2. Create a user using “totp-api-user” as both Name and Username.

3. Enable user.

4. Set a password, for instance: Password1
   
   

5. Also create a group “TOTP API Users” under System site / TOTP API as seen below.
   
   

    

6. Add the user totp-api-user to this new group.
   
   Obs: Do not use TOTP API application credentials. Do not use or expose TOTP API application secrets to integrate with TOTP API. The TOTP API application secret is meant for internal use in SSO.
   
   

7. You need to create a new OAuth 2.0 client. Go to System / TOTP API / Applications.

8. Click on “New Application” and on the pop up window, select “OAuth 2.0” as the application type. Give it a name such as “New TOTP API client” and enable it.
   
   

    

9. Once the application is created, open it and in “Upload” copy the following text:
   
   

    

10. Then, activate the client. This will generate a client_id and client_secret.

11. Save the file on your Desktop.
    
    

12. Go to “Allowed methods” and enable Password (password.1) method.

13. Go to “Allowed to” and add the “TOTP API Users” group.

14. Now you have all the settings required to invoke the TOTP API and get an access token.
    
    

15. Here is a summary of all data you need in order to invoke the API:
    
    scope: TOTP API client_id

    client_id: TOTP client client_id

    client_secret: TOTP client client_secret

    username / password: TOTP API user credentials ( totp-api-user / Password1 )
    
    

16. Open the command prompt and execute the line below (replace the parameters in the previous table with their actual values).
    
    

     

17. The result will be similar to:
    
    

     

18. From there, you have to extract the access token value as shown below for this example.
    
    eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiemlwIjoiREVGIiwiaXNzIjoiMTU0YjQ5NmUtMzY1YS00NjUyLTllYWMtNmZhMDgwZGU5OWE5In0..ltijdLBifUb8EGnThAZAeg.-4fo0qS_I-RcYSMP9irm2zWD_i2QtUv2zK0vVjBXxFwBGDMFyX0rcswGiRuKtmTqbvYoFSI4HiUYSFTa5vglS77godQcPdV5_iJAUGyCxPPoIWjOfZf_rtVOi9MSAnITwmag3ho3lOILTyYn7Z3t708TkO_1ITGio_O_ymC3mPeE7F1cnZ7VJJXciS5bNncItqqb0PHRIukXWl14pVTuWLw5v1egJ26BYyMZUMHaGqf-s3Jl9NQXyQytrSd3h9Q38FSoNvhwRWvz-nW3VWJNSqI1iEzmnOZMklOfKDIafRttBAFeUypXVl3w5f2mJCDSUbxea9btckxTSuDxXOVgdxKvdRZClcRtk_IySqtR--XXjdksQOfOA9tRYQxFAQTPDkKAvB7Jn0lugbcqMZzp-b3Dq8NfBuA3Fz7f7_QmDdI.xzrYqSsBgXldUlqdVlwbVg
    
    

19. Now you have obtained an access token which you will use in Part 2 (enrollment of users to the TOTP method). The access token expires 60 minutes (3600 seconds) after being created, as shown in the parameter “expires_in”

Step 3. Enable TOTP API’s Swagger

As TOTP API is a Spring Boot application embedded in the Ubisecure Tomcat server, you can configure it via the external configuration file application.yaml which is included in the installation package. Its exact location is: C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\totp\WEB-INF

In this lab we will:

• Enable Swagger’s documentation for TOTP API

• Change logging level to DEBUG
  
  

1. Open C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\totp\WEB-INF\application.yaml with Notepad++.
   
   

2. Enable API documentation by removing the comment sign from the following line in the external configuration file application.yaml:
   
   

    

3. Enable debug logging for the API by removing the comment sign from the following line in the external configuration file application.yaml:
   
   

    

4. Finally, in order to make these changes in effect, update Tomcat. Open the command prompt and execute these two commands:
   
   

    

5. Now you can access Swagger API from your browser: https://login.smartplan.com:8443/totp/swagger-ui/
   
   

Step 4: Create a method in SSO

The next step is to create a TOTP authentication method in the system, the same way you created SMS OTP and other methods in the previous labs. The full instructions are on TOTP Authentication Method page.

1. In the SSO Management Console, navigate to the "Global Method Settings" and click the “New Method” button at the bottom of the page.

2. Create a new authentication method with the parameters below.
   Title: TOTP

   Name: ubikey.totp.1

   Method Type: SPI TOTP

   Directory: CustomerID Directory
   
   Obs: Choosing Method Type will populate Method Class automatically
   
   

    

3. Once the method is created, tick “Enabled” on the Status section and press the “Update” button.
   
   

    

4. Now the method has been enabled.

5. You can go to the SPI TOTP tab and please observe the values for a moment. For this exercise, we will use the default values.

Step 5: Prepare the application for using TOTP

As we will test TOTP functionality using the SmartPlan application, we have to enable the method to the application and also enable it for the groups of users that will log in.

1. Go to the SmartPlan site, and on “Site methods” add the new method.

2. Go to the eIDM Users site, and on “Site methods” add the new method.
   
   

3. On the front page of SSO Management, go to Services (at the top)
   
   

    

4. Next, select CustomerID Directory
   
   

    

5. Go to tab “Connected Methods”
   
   

    

6. Tick on the “TOTP” box and press “Update”
   
   

7. Now the CIAM system is ready for TOTP to be used.

Part 2. Enroll users to TOTP method

Once the TOTP functionality is implemented in the CIAM system, every user that wants to use TOTP as a second factor must be enrolled (initialized).

In real life scenarios, these are common ways users enroll to TOTP as second factor:

• A user is logged in to an application and goes to self-service. This user interface offers the user the possibility to enable 2FA.

• The service provider guides the user to go to a webpage in which the enrollment process starts.

In both cases, the service provider has developed a web application allowing user enrollment.

In this lab, there is no such web application. You will execute one by one the steps that would need to be embedded into the application. You as a system integrator will develop that application based on the specific customers' needs. The steps are:

• Get an access token

• Initialize the user for TOTP and generate a secret associated with that user

• Use a secret to create a QR code that will be displayed on the screen
  
  

Let's say user Scott Long wishes to enable MFA for his account.

Step 1. Get an access token

1. In Part 1, Step 2, you have already obtained an access token. If not, open the command prompt and execute the line below.
   
   

   
   Obs: If you are familiar with Postman, you can use it instead of the curl command above.
   
   

2. From the response, extract the value of the access token.

Step 2. Generate secret and activate TOTP for user

This step can be done in three ways: via curl commands, Postman or using TOTP API’s swagger page.

We’ll use Swagger.

1. Open https://login.smartplan.com:8443/totp/swagger-ui/ and click “Authorize” green button that has a padlock icon.
   
   

    

2. Next, on the “Value:” box, write Bearer followed by one space, followed by the access token.
   
   Bearer eyJjdHkiOiJ………..
   
   
   

    

3. Press “Authorize.” Now you’re authorized to make API calls via Swagger UI.

4. Scroll down and you will see the three HTTP request methods available on TOTP API, they are: GET, PUT and DELETE.
   
   

    

5. A PUT call is required to generate the secret and write it to the user directory.
   
   PUT /totp/api/v1/methods/{method} configures the TOTP method for a user
   
   

6. Click on “PUT” and you will be able to set the parameters of the call. Press “Try it out” button.
   
   

   
   
   

7. Fill in as shown below:
   
   method: ubikey.totp.1

   totpMethodSettings:
   
   

    

    

8. Then press “Execute” (blue button).

   The expected response will look like this:
   
   

    

9. Now you have the secret that was generated for user scott.long. Copy the value. This secret can be used for enrollment in a TOTP mobile app (e.g. Authy) in step 3.

Step 3. Generate a QR code for the secret

To make the enrollment more usable for regular users, we’ll use this secret to generate a QR code.

We will use Google Charts API to generate QR codes. Have a quick look at the documentation for QR codes.

Call to Google Charts API to generate QR Code:

The table below shows the parameters used.

1. Edit the value of the secret, and then open the URL in your browser.
   
   

   
   
   

2. You can see a QR code in the browser. Keep it active for the next section of this lab.

Part 3. Authenticate using TOTP as second factor authentication

Now that system is fully configured, let’s use Authy to enroll Scott Long to TOTP.

Step 1. Create an authenticator account on Authy

1. Install Authy on your mobile: https://authy.com/download/
   
   

2. Press the "Add Account" button

    

3. Next press the "Scan QR Code" button. When the camera opens, point the camera at the QR code on your laptop.

    

4. This will create a new "authenticator account" on Authy, and a new icon labeled "scott.long@smartplan.com" will appear on the home screen.

Step 2. Authenticate with a second factor

Proceed to authenticate using TOTP as the second factor. The user authentication flow is:

1. User goes to the SmartPlan application login page

2. User first logs in with a username and password

3. Login page prompts the user to use second factor authentication with a Time-based One-Time Password (6 digits).

4. User opens Authy and completes the login process

Follow the step-by-step instructions:

1. Open SmartPlan application http://localhost:8090/smartplanapplication/

2. Press “Log in”

3. First, authenticate using scott.long@smartplan.com and password.

4. If successful the login page will look like this:
   
   

    

5. Open Authy on your mobile phone, and type on the browser screen the 6-digit code you see on the app.
   
   

6. Press the “Sign in” button and you will be logged in. Observe that the value of the “Authentication context” attribute ends with the method name you created: ubikey.totp.1

*** END OF THIS LAB ***