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.

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

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.

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.

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.

{
  "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:

totp-api-client-id

oauth2-client-id

oauth2-client-secret

totp-api-user

totp-api-user-password

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.

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

You have options to:

• enable API documentation
• change logging level
• open up the management endpoints

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

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

• Page:
  TOTP Authentication Method
• Page:
  TOTP API configuration - SSO
• Page:
  TOTP API - SSO