IAM

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.

secure-vault-ebook

Secure Vault: What is it and how to apply it in your company

Find out how to secure your company data by adding an extra layer of security to your credentials with our guide.

Written By

Juan Carlos Montes

WSO2 Specialist