/
Lab 3.5: Multi-factor authentication with TOTP

Lab 3.5: Multi-factor authentication with TOTP

Purpose

The purpose of this module is to learn

  • Basics of TOTP

  • How to configure TOTP on Ubisecure Identity Platform

 

Requirements

  • SSO

  • CustomerID

  • A TOTP authenticator app such as Authy

 

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

A few steps must be completed on the Identity Platform side, and then the user must also configure the account before we can see the authentication.

Instructions

 

Let’s get started.

Part 1. Enable TOTP on the Identity Platform


In real projects, the system integrator completes Part 1 before launching the 2FA into production.

Step 1: Configure TOTP API

TOTP API has to be activated and configured according to the 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. Check the logs to verify that the TOTP API has successfully started. 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. In the same file log file, you should find this line:

    C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\logs\sso_diag.YYYY-MM-DD.log

    YYYY-MM-DD hh:mm:ss,SSS totp init INFO TOTP application X.X.X started

     

  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 the TOTP API connects to the SSO OAuth 2.0 endpoints, the Java installation must trust the issuer of the TLS certificate on those endpoints. As you must remember, we’re using self-signed certificates. NOTE: In the training environment, this procedure has been done. You can skip to Step 2: Get access to the API.

  9. Open the command prompt.

  10. First, go where the keytool is located

    cd C:\Program Files\OpenJDK11U-jdk_x64_windows_hotspot_11.0.25_9\jdk-11.0.25+9\bin

     

  11. Next, execute:

    keytool -exportcert -keystore "C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\tomcat\keystore.pfx" -alias tomcat -storepass changeit | keytool -importcert -cacerts -storepass changeit -alias ubisecure-sso-servercert -noprompt

     

  12. You will see a similar response below if the command was successfully executed.

 

Step 2: Get access to the API

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

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

 

First, we must create a user authorized to make all TOTP API calls. Let’s call it totp-api-user.

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

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

  3. Enable user.

image-20250324-141138.png

  1. Set a password, for instance: Password1

image-20250324-141248.png

  1. Also, create a group called “TOTP API Users” under the SmartPlan site, as seen below.

    image-20250324-140008.png

  2. Add the user totp-api-user to this new group. Choose the group: Home - SmartPlan - Groups - TOTP API Users - Users - Add button. Choose the totp-api-user: System - TOTP API - totp-api-user - OK button.

    image-20250324-141624.png


    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.

  3. You need to create a new OAuth 2.0 client. Go to SmartPlan - Applications.

  4. Click on “New Application,” and in 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.

    image-20250324-135606.png

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

  6. Save the file on your Desktop.

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

    { "allowed_methods": [ "password" ], "client_id": "<copy_the_client_id_value_from_the_saved_file>" }

     

image-20250327-102403.png

  1. Add the password.1 as the site method for the SmartPlan site. SmartPlan - Site Methods - Add Method button - Password - OK button.

image-20250324-142224.png

  1. Go to SmartPlan - Applications - New TOTP API client - Allowed methods and enable Password (password.1) method for the New TOTP API client application.

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

image-20250324-142637.png

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

  2. Here is a summary of all the data you need to invoke the API:

    scope: TOTP API client_id (Home - System -TOTP API - Applications - TOTP API - OAuth 2.0 ID)

    client_id: New TOTP API client client_id (See the value from the file saved on the Desktop on step 10)

    client_secret: New TOTP API client client_secret (See thevalue from the file saved on the Desktop on step 10)

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

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

    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password" --data "client_id=REPLACE_THIS VALUE" --data "client_secret=REPLACE_THIS VALUE" --data "username=totp-api-user" --data "password=Password1" --data "scope=openid REPLACE_THIS VALUE" "https://login.smartplan.com:8443/uas/oauth2/token" --insecure

     

  4. The result will be similar to:

    {"access_token":"eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiemlwIjoiREVGIiwiaXNzIjoiMTU0YjQ5NmUtMzY1YS00NjUyLTllYWMtNmZhMDgwZGU5OWE5In0..ltijdLBifUb8EGnThAZAeg.-4fo0qS_I-RcYSMP9irm2zWD_i2QtUv2zK0vVjBXxFwBGDMFyX0rcswGiRuKtmTqbvYoFSI4HiUYSFTa5vglS77godQcPdV5_iJAUGyCxPPoIWjOfZf_rtVOi9MSAnITwmag3ho3lOILTyYn7Z3t708TkO_1ITGio_O_ymC3mPeE7F1cnZ7VJJXciS5bNncItqqb0PHRIukXWl14pVTuWLw5v1egJ26BYyMZUMHaGqf-s3Jl9NQXyQytrSd3h9Q38FSoNvhwRWvz-nW3VWJNSqI1iEzmnOZMklOfKDIafRttBAFeUypXVl3w5f2mJCDSUbxea9btckxTSuDxXOVgdxKvdRZClcRtk_IySqtR--XXjdksQOfOA9tRYQxFAQTPDkKAvB7Jn0lugbcqMZzp-b3Dq8NfBuA3Fz7f7_QmDdI.xzrYqSsBgXldUlqdVlwbVg","scope":"openid","id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFrY1hXLVpZeVdnOTV3alpZWWZyUlgyOGZRTSJ9.eyJzdWIiOiJDTj10b3RwLXVzZXIsT1U9U3lzdGVtLENOPVViaWxvZ2luLERDPWxvZ2luLERDPXNtYXJ0cGxhbixEQz1jb20iLCJpc3MiOiJodHRwczovL2xvZ2luLnNtYXJ0cGxhbi5jb206ODQ0My91YXMiLCJhdWQiOlsiMTU0YjQ5NmUtMzY1YS00NjUyLTllYWMtNmZhMDgwZGU5OWE5Il0sImV4cCI6MTY2NjA5MzA4NCwiaWF0IjoxNjY2MDg5NDg0LCJhdXRoX3RpbWUiOjE2NjYwODk0ODQsImFtciI6WyJodHRwczovL2xvZ2luLnNtYXJ0cGxhbi5jb206ODQ0My91YXMvc2FtbDIvbmFtZXMvYWMvcGFzc3dvcmQuMSJdLCJhenAiOiIxNTRiNDk2ZS0zNjVhLTQ2NTItOWVhYy02ZmEwODBkZTk5YTkiLCJzZXNzaW9uX2luZGV4IjoiX2Q4ZDcwMWIyMmFhYjM3NDIwNDUxNzRhMWM3MTJjOTY1ZTVjYWEzMTIiLCJwYXNzd29yZC4xLmdyYW50X3R5cGUiOlsicGFzc3dvcmQiXSwicGFzc3dvcmQuMS5kbiI6WyJDTj10b3RwLXVzZXIsT1U9U3lzdGVtLENOPVViaWxvZ2luLERDPWxvZ2luLERDPXNtYXJ0cGxhbixEQz1jb20iXSwicGFzc3dvcmQuMS5sZGFwIjpbImxkYXA6Ly8vY249VWJpbG9naW4sZGM9bG9naW4sZGM9c21hcnRwbGFuLGRjPWNvbSJdfQ.WjJ8HQh9WUu05Vf0kinY8R5hnoY0FwRYTxO6T3_wn9fn2rRnD-79gs6MoV_tNUbQ9a0JUNNr0CqBq1uto8nkOWheQWJ9Rs9qJdRV64SweSe864MliFeRIMmM3-7PTNbOCvkUV5qKrfglZFy48jUck63rCnIL4nFmF4Jcy9F6MFTc5Hy2G-zGuVoA4I76RUheI7djKcDWEbqvVQNttdxgrPJJDVBLoBtxKLySd5SsGEwRoyVhq6kSZGCwEGPtFpdp-6uEdvSqeP4j54-j_m_9hRPmdQbTlLWn2wMfTRY4I58BCfB6wNds0Um47swuMtA-rVLJwLp3LNp_Gf9U-1wqTQ","token_type":"Bearer","expires_in":3600}

     

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

  6. 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 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:

    spring.profiles.active: api-docs

     

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

    logging.level.com.ubisecure.sso.totp: DEBUG

     

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

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

     

  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, just as you created SMS OTP and other methods in the previous labs. The full instructions are on the TOTP Authentication Method page.

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

  2. Create a new authentication method using 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 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 Home - Services (at the top)

     

  4. Next, select CustomerID Directory

     

  5. Go to the “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 who wants to use TOTP as a second factor must be enrolled (initialized).

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

  • A user logs in to an application and goes to self-service. This user interface offers the possibility of enabling 2FA.

  • The service provider guides the user to a webpage where 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 the steps that need to be embedded into the application individually. As a system integrator, you 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. You have already obtained an access token in Part 1, Step 2. If not, open the command prompt and execute the line below.

    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password" --data "client_id=REPLACE_THIS VALUE" --data "client_secret=REPLACE_THIS VALUE" --data "username=totp-api-user" --data "password=Password1" --data "scope=openid REPLACE_THIS VALUE" "https://login.smartplan.com:8443/uas/oauth2/token" --insecure


    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 TOTP API’s swagger page.

We’ll use Swagger.

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

     

  2. Next, on the “Value” box, copy and paste the access token.

    eyJjdHkiOiJ………..


    image-20250324-180741.png

  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: GET, PUT, and DELETE.

     

  5. A PUT call is required to generate and write the secret to the user directory.

    PUT /totp/api/v1/methods/{method} configures the TOTP method for a user

  6. Click on “PUT” to set the call's parameters. Then, press the “Try it out” button.



  7. Fill in as shown below:

    method: ubikey.totp.1

    totpMethodSettings:

    {"enabled": true, "generateSecret": true, "user": {"login": "scott.long"} }

     

     

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

    The expected response will look like this:

    { "user": { "login": "scott.long", "uniqueId": "CN=6bbab84b-a317-4dc3-a364-9b2b03be21a7,OU=Users,OU=eIDM Users,CN=Ubilogin,DC=login,DC=smartplan,DC=com" }, "method": "ubikey.totp.1", "enabled": true, "secret": "GBN73C7FGDMLWNDOLB6VQRMZCVAVPZ4E", "generateSecret": true }

     

  9. Now you have the secret that was generated for user scott.long. Copy the value. In step 3, you can use this secret to enroll in a TOTP mobile app (e.g., Authy).

 

Step 3. Generate a QR code for the secret

We use the copied secret to generate a QR code to make the enrollment more usable for regular users.

We will use the site QR Code Generator | Create Your Free QR Codes to generate QR codes. For more information about QR-codes, have a quick look at the documentation for QR codes.

 

Form the URL to create the QR code. See the values from the table below:

otpauth://totp/scott.long@smartplan.com?secret=<secret>&issuer=TOTP-API

 

The table below shows the parameters used.

Parameter

Value

Parameter

Value

chl

otpauth://totp/scott.long@smartplan.com

secret (mandatory, replace it with your own generated secret)

GBN73C7FGDMLWNDOLB6VQRMZCVAVPZ4E

issuer (optional)

TOTP-API

 

  1. Edit the secret value, then open the QR code generator, and use the URL option to paste the value to generate the QR code.

    image-20250326-130354.png



  2. The browser shows a QR code. Keep it active for the next section of this lab.

 

This QR code was created via a web service (QR Code Generator) for training purposes only. Never share any secret on a web service. In a real implementation, the application generates the QR code internally.

Part 3. Authentication using TOTP as second factor authentication


Now that the system is fully configured, let’s use Authy to enroll Scott Long in TOTP. You can also use other authenticators, such as Google or Microsoft.

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 the 6-digit code you see on the app into the browser screen.

  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 ***

Ubisecure Privacy Policy & Cookie Statement