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 TOTP API - SSO

The example commands have been tested with Ubisecure SSO 8.8.1.

Prerequisites:

TOTP API has been activated and configured according to instructions in TOTP API configuration - SSO
- 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 TOTP Authentication Method
- 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

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": false,
    "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": false,
    "generateSecret": false
}

Activate the user’s TOTP

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,
    "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,
    "generateSecret": false
}

Delete the user’s TOTP

curl --location --request DELETE 'https://test.ubisecure.com/totp/api/v1/methods/test.totp.1' \
--header 'Authorization: Bearer eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJB....M.d4vVZ1e3icLEqFLUSt6lrA' \
--header 'Content-Type: application/json' \
--data-raw '{
    "login": "test.user@example.com"
}'
Status: 204 No Content

Knowledge Base

How to use TOTP API to initialize and maintain users