Skip to Main Content

WSO2 IS: How to use the TOTP (Time-Based One Time Password) API

What is Time-Based One Time Password (TOTP)?

TOTP means time based one-time password, and is a common form of two-factor authentication. Unique numeric passwords are generated with an algorithm that uses the current time as the input. Time-based passwords expire, and therefore offer greater security for 2FA.

In WSO2 IS, when multi-factor authentication is enabled and using the TOTP authenticator as the second authentication step, a user’s TOTP code can be validated using the TOTP API.

How to use the TOTP Service in WSO2 IS

The following is an example of how to use the Time-Based One Time Password service:

1. Enable the TOTP Management Service

On WSO2 IS, by default, the WSDL of the administration services are hidden from consumers. To enable the services you must open the file <WSO2IS_HOME>/repository/conf/carbon.xml. and change the following line:

<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>

2. Restart the WSO2 IS Service

3. Enable Time-Based One Time Password

The Time-Based One Time Password authenticator can be enabled by calling the initTOTP function provided in the TOTPAdminService as shown below:

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic <base64Encoded string of USERNAME:PASSWORD>' https://localhost:9443/services/TOTPAdminService/initTOTP -k -d 'username=<USERNAME>'

In case of the user admin, it would be as follows:

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=admin'

4. Get the user’s Secret Key

To obtain the user’s secret key, the following command must be executed:

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic <base64Encoded string of USERNAME:PASSWORD>' https://localhost:9443/services/TOTPAdminService/retrieveSecretKey -k -d 'username=<USERNAME>'

In case of the user admin, it would be as follows:

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=admin'

5. Download either of the following applications to your mobile phone:

google_auth

microsoft_auth

Select the Add an Account option and enter the password obtained in step 3: 5QFLDLKQ2ZGG7J5H

Once the key has been added, the dynamic codes will be generated

-You may also be interested in this tutorial: TWO-FACTOR AUTHENTICATION CONFIGURATION WITH TOTP –

6. Validate the TOTP Code

To validate the Time-Based One Time Password code, the following command must be executed:

curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic <base64Encoded string of USERNAME:PASSWORD>' https://localhost:9443/services/TOTPAdminService/validateTOTP -k -d 'username=<USERNAME>' -d 'verificationCode=<CODE>'

In case of the user admin, it would be as follows:

1 curl -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization:Basic YWRtaW46YWRtaW4=' https://localhost:9443/services/TOTPAdminService/validateTOTP -k -d 'username=admin' -d 'verificationCode=123456'

The answer will be false or true depending on whether the code is valid or not.