Skip to main content

TOTP (Verification)

This is a technical introduction how you can implement the Enrollment for TOTP by simply following the below steps.

What is TOTP​

TOTPs are so-called time-based one-time passwords, a few-digit code that is generated on the authenticator app for a fixed duration of time. The UI will show the box to enter the TOTP. The user should get the TOTP from the authenticator app on their personalised device (mobile) and enter it. On successful verification, we can proceed with the authentication.

You can integrate it in any app, even your own apps, the user is already using and equip it to an Authenticator.

totp-enrollment.png

When is a user able to configure TOTP​

CriteriaExampleConfiguration
User Verification SetupAs soon as user registers in cidaas authenticator app and enrolls TOTP as one of the authentication mechanism.
Allowed Verification MethodsThe verification method, the user want to setup, must be activated for your instance. It is a global setup.mfa-setup.png

Understanding the Flow and APIs​

APIDescriptionLink
Get available verification methodsTo display and allow the user to configure the available verification methods.Link to API
Enrollment InitiationThe Enrollment of a user via authenticator app, will provide the URL that is shown e.g as a QR Code in the default user profile.Link to API
Enrollment StatusThis will allow to verify the enrollment status in the User Profile, to determine when to continue the enrollment completion.Link to API
Add friendly Device NameIn case of using device authentication methods like FIDO2, you can add a user-friendly name.Link to API

Step 1: Allow TOTP in your Instance​

In your Verification Setup you need to allow that TOTP is enabled. Thereby you can change your existing setup, navigate to Multifactor Settings > Enable TOTP.

mfa-setup.png

Step 2: Present Verification Methods​

The first page for enrollment should present all verification methods available. totp-enrollment.png

Thereby you can use the below query to retrieve the available methods.

curl 'https://domain/verification-srv/config/list' \
  -H 'Authorization: Bearer eyJhbGciOiJxxx2Og' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  --compressed

The API returns all available methods as array:

[ 
  {
      "verificationType": "TOTP",
      "active":true
  },
  {
      "verificationType": "TOUCHID",
      "active": true,
  },
]

Developer Perspective​

This Implementation Guide is based on the default demo pages which is using a angular framework based on Typescript. It can be implemented in any other programming language as well.

As a first step you will be redirected to the login&security page. This Section starts to show the verification methods:

totp-enrollment.png

Step 1: Present Verification Methods​

The first page for enrollment should present all verification methods available. totp-enrollment.png

Thereby you can use the below query to retrieve the available methods.

  getMFAList(): Observable<IEnabledMFAResponse> {
    return this.http.get<IEnabledMFAResponse>(this.baseUrl+ '/verification-srv/config/list', ({headers: URLHelper.getHeaders()}));
  }

The API returns all available methods as array:

[ 
  {
      "verificationType": "TOTP",
      "active":true
  },
  {
      "verificationType": "TOUCHID",
      "active": true,
  },
]

Need Support?​

Please contact us directly on our support page