Introduction

This document guides on how to enable and start using TOTP API in Ubisecure SSO.

Enable TOTP API

TOTP API is not enabled by default in Ubisecure SSO. To enable TOTP API, update Tomcat configuration as described by the following steps.

Locate custom Tomcat configuration file

Edit your custom version of the server.xml in the following location where $UBISECURE_HOME denotes the path to the Ubisecure SSO installation:

$UBISECURE_HOME/ubilogin/custom/tomcat/server.xml

If the file does not already exist in that location, copy the Ubisecure SSO default server.xml to the custom directory. See also Custom server.xml for detailed instructions. Modifications to the files in the custom directory will be retained when a software upgrade is performed.

Define context path for TOTP API

Uncomment or add the following line to the server.xml file:

<Context path="/totp" docBase="${catalina.base}/webapps/totp" />

Update Tomcat

Copy the custom file under Tomcat and restart the service. NOTE that if the services have been stopped before executing the update script you may need to start them manually, see Starting and stopping the services.

Windows

cd /d %UBILOGIN_HOME%\ubilogin
.\config\tomcat\update.cmd

Unix

cd $UBISECURE_HOME/ubilogin
./config/tomcat/update.sh

Verify TOTP API has successfully started

Since v. 9.1.0 TOTP API logs to the shared SSO diagnostic log file: sso_diag.YYYY-MM-DD.log. Review that log file indicates successful startup. Confirm that no unexpected errors have occurred since the previous restart.

$UBISECURE_HOME/ubilogin/logs/sso_diag.YYYY-MM-DD.log

YYYY-MM-DD hh:mm:ss,SSS totp init INFO TOTP application X.X.X started
...
YYYY-MM-DD hh:mm:ss,SSS uas init INFO Ubilogin Authentication Server X.X.X started 
YYYY-MM-DD hh:mm:ss,SSS uas tech INFO ping: the system is alive

Import certificates

Like SSO Management API, also the TOTP API connects to the SSO OAuth2 endpoints. The issuer of the SSL certificate on those endpoints must be trusted by the Java installation used. By default, no publicly issued CAs are trusted and must be trusted explicitly.

If you have not yet imported the certificate, see Add Server Certificate to Java Trust Store.

Get access to the API

After a successful Ubisecure SSO installation or upgrade, System → TOTP API site and TOTP API applications are visible in SSO Management UI. The API is accessible to group named TOTP API Users. In order to access the API, a new OAuth2 application must be created and an API user needs to be defined. The following steps will guide you through these steps.

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

Creating a new OAuth2 application

Create new OAuth2 client application as instructed in Management UI Applications or alternatively use the Management API. Allow TOTP API Users to access the newly created application and enable, for example, password.1 method or your preferred method for the application.

The following OAuth2 client metadata describes a simple OAuth2 client that can request an access token using OAuth2 Resource Owner Password Credentials Grant.

{
  "client_id": "... redacted ...",
  "client_secret": "..redacted...",
  "allowed_methods": [
    "password"
  ]
}

After the application has been configure proceed with defining an API user.

Define API user

Add a user to TOTP API Users group e.g. with the Management UI. You can choose from the following options:

Create a new user with password method allowed, and add it
Add an existing user with password method allowed
Add an existing group

Any of these actions can also be performed using the Management API.

Locate API scope

In order to access the TOTP API, you need its client ID for the scope parameter of the OAuth2 Token Request. The required scope is returned in the WWW-Authenticate response header of an unauthorized request. The client ID is also visible in System → TOTP API → Applications → TOTP API as depicted here:

Verify the API works

The following examples use non-existing TOTP authentication method in SSO with name non.existing.method.

You can start testing the connection using curl. You may use the --insecure flag in case self-signed certificates are used:

$ curl \
  --request PUT 'https://<sso-base-url>/totp/api/v1/methods/non.existing.method' \
  --header 'Content-Type: application/json' \
  --data-raw '
  {
    "user": {
      "login": "any.user"
    }
  }'

An HTTP 401 status code is expected as no OAuth2 access token was provided in the request.

Get the access token e.g. with OAuth2 Password grant:

$ curl \
  --request POST 'https://<sso-base-url>/uas/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'scope=openid <totp-api-client-id>' \
  --data-urlencode 'client_id=<oauth2-client-id>' \
  --data-urlencode 'client_secret=<oauth2-client-secret>' \
  --data-urlencode 'username=<totp-api-user>' \
  --data-urlencode 'password=<totp-api-password>'

Where:

Paramater	Description
totp-api-client-id	The client_id of the TOTP API retrieved in Locate API scope section
oauth2-client-id	The client_id of your OAuth2 client application you created in Creating a new OAuth2 application section
oauth2-client-secret	The client_secret of your OAuth2 client application you created in Creating a new OAuth2 application section
totp-api-user	The username of the user you created in Define API user section
totp-api-user-password	The password of the user you created in Define API user section

Get the access token from the response and use in the TOTP API request:

$ curl \
  --verbose \
  --request PUT 'https://<sso-base-url>/totp/api/v1/methods/non.existing.method' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your access token here>' \
  --data-raw '
  {
    "user": {
      "login": "any.user"
    }
  }'

As a valid OAuth2 access token was provided, the expected status code is HTTP 404 with the following response body:

{
    "error": "not_found",
    "error_description": "Authentication method not found."
}

This indicates that the request was authorized but since a non-existent TOTP authentication method was used, an error response was returned.

Configuration options for the TOTP API application

TOTP API is a Spring Boot application embedded to the Ubisecure Tomcat server. You can configure it via the external configuration file which is included in the installation package.

TOTP API configuration file path

$UBISECURE_HOME/ubilogin/webapps/totp/WEB-INF/application.yaml

You have options to:

enable API documentation
change logging level
open up the management endpoints

If you make changes to the external configuration file, you need to update Tomcat like instructed above in this document.

Enable API documentation

Enable API documentation by removing the comment sign from the following line in the external configuration file:

spring.profiles.active: api-docs

You can navigate to the API documentation in your browser with the following URL: https://<sso-base-url>/totp/swagger-ui/

See also TOTP API main page / API documentation.

Configure diagnostic logging for TOTP API

When troubleshooting you can get some more information about the system by enabling debug level logging.

Change logging level before starting the service

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

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

Possible values are OFF, FATAL, ERROR, WARN, INFO, DEBUG and TRACE. The default level is INFO.

logging.level.com.ubisecure: DEBUG

Facilitate changing logging level at runtime

Alternatively, it is possible to deploy the application and expose an API to control the logging levels at runtime. This API can be enabled by uncommenting these lines in the external configuration file:

management.endpoints.enabled-by-default: true
management.endpoints.web.exposure.include: loggers

For the complete list of management endpoints, check Spring Boot Actuators.

When running the application, it is possible to change the logging level of com.ubisecure.sso.totp logger of the TOTP API for example using curl:

$ curl \
  --verbose \
  --request POST 'https://<sso-base-url>/totp/actuator/loggers/com.ubisecure.sso.totp' \
  --header 'Authorization: Bearer <your access token here>' \
  --header 'Content-Type: application/json' \
  --data-raw '
  {
    "configuredLevel":"DEBUG"
  }
  '

The value dictating the level is denoted by configuredLevel.

You can change the level back with the same endpoint. A restart resets the level to default value which is INFO (unless you have specified differently in the external configuration file).

Related content

Browser not supported