How to use TOTP API to initialize and maintain users
Introduction
Ubisecure Identity Platform provides an API for initializing and managing TOTP clients of the users. Typically, this functionality is implemented in self-service user profile management of your applications and services by utilizing the Ubisecure TOTP API. This article presents examples of TOTP API operations as CURL commands. The TOTP API is described at https://ubisecuredev.atlassian.net/wiki/spaces/IDS20213/pages/4452582106
The example commands have been tested with Ubisecure SSO 8.8.1.
Prerequisites:
TOTP API has been activated and configured according to instructions in https://ubisecuredev.atlassian.net/wiki/spaces/IDS20213/pages/4452582110
Client_id of the TOTP API is needed in the example commands.
Client_id and client_secret of the TOTP API client are needed in the example commands.
User ID and password of the TOTP API user account are needed in the example commands.
A TOTP authentication method has been configured according to instructions in https://ubisecuredev.atlassian.net/wiki/spaces/IDS20213/pages/4452582442
In this article, we use the authentication method test.totp.1.
Example API operations
Note that in the examples below, access tokens are shortened for readability reasons.
The following parameters are used:
TOTP API client_id | e8366470-032d-4eec-8994-d72b909b710e |
TOTP client client_id | de987e7e-6766-4e60-9598-bd0311c2d70a |
TOTP client client_secret | yf6sTSvV3NZn54GcPObcP8j2T-STfA7v |
TOTP API user credentials | totp-admin / HG789ghhhj43 |
Authentication method name | test.totp.1 |
Get access token
curl --location --request POST 'https://test.ubisecure.com/uas/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user 'de987e7e-6766-4e60-9598-bd0311c2d70a:yf6sTSvV3NZn54GcPObcP8j2T-STfA7v' \
--data-urlencode 'username=totp-admin' \
--data-urlencode 'password=HG789ghhhj43' \
--data-urlencode 'scope=openid e8366470-032d-4eec-8994-d72b909b710e' \
--data-urlencode 'grant_type=password'
Status: 200 OK
{
"access_token": "eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJB....M.d4vVZ1e3icLEqFLUSt6lrA",
"scope": "openid",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjVn....ubonxEtcL6pbLqkY9u0uretOAJcgNh8F9A",
"token_type": "Bearer",
"expires_in": 3600
}Initialize TOTP for a user
curl --location --request PUT 'https://test.ubisecure.com/totp/api/v1/methods/test.totp.1' \
--header 'Authorization: Bearer eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJB....M.d4vVZ1e3icLEqFLUSt6lrA' \
--header 'Content-Type: application/json' \
--data-raw '{
"enabled": true,
"generateSecret": true,
"user":{"login":"test.user@example.com"}
}'
Status: 200 OK
{
"user": {
"login": "test.user@example.com",
"uniqueId": "CN=2ddf5b56-b112-46b6-aa4f-f103b5495b70,OU=Users,OU=eIDM Users,CN=Ubilogin,DC=login,DC=smartplan,DC=com"
},
"method": "test.totp.1",
"enabled": true,
"secret": "DAFH4LND42A3XS3DP3M5ECLFUFU3GEL2",
"generateSecret": true
}Get the status of a user
curl --location --request GET 'https://test.ubisecure.com/totp/api/v1/methods/test.totp.1?login=test.user%40example.com' \
--header 'Authorization: Bearer eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJB....M.d4vVZ1e3icLEqFLUSt6lrA'
Status: 200 OK
{
"enabled": true
}Inactivate the user’s TOTP
Activate the user’s TOTP
Delete the user’s TOTP