TOTP (Time-based One-Time Passwords)

Passportal Credentials can be configured to include a Time-based One-Time Password (TOTP).

TOTP's are a common form of 2FA (Two-Factor Authentication), generated unique numeric codes by an algorithm that uses the current time as an input. Most popular 2FA apps, such as Google Authenticator, Microsoft Authenticator, Duo, Authy, etc., support TOTP.

The generated unique codes are also time bound, and so will expire every 30 seconds.

All TOTP seed codes are encrypted at rest and stored separately from the credentials they reference in their own database on separate infrastructure.

Immediate benefit over a 3rd Party TOTP service

By configuring a Credential with a TOTP generated by Passportal, technicians and engineers no longer have to tie individual authentication accounts to their own authentication tools on their mobile devices. With the TOTP configured in the stored Credential in Passportal, all technicians with access to the Credential can use that TOTP to authenticate when accessing a clients devices or environment.

Make sure not to store your log-in credentials for Passportal in Passportal itself, especially if you have TOTP associated to that account. If your session times out on the browser extension, you will not be able to re-authenticate and you will require assistance to get this reset, potentially causing a delay in access to your Passportal account.

Time Differences between Passportal and the 2FA Secured Application

RFC6238 states that the code generator (Passportal) and the verifier (the secured application) should both be working on UTC time:

  • Passportal utilizes Hashicorp TOTP Vault to generate codes - this means that the server time on the Passportal regional host server is not used in the generation of the TOTP
  • Hashicorp TOTP Vault uses UTC time
  • In most cases, the application's 2FA verification process uses UTC time - we recommend to check with the supplier if you are unsure

This means there are no code failure issues caused by devices set to an incorrect time, incorrect or different timezones, etc.

Adding TOTP to a Credential

The Permission Password: TOTP Add/Remove is required in order to add or remove TOTP to a credential

Adding TOTP to a Credential requires the alpha-numeric code presented to you when setting up 2FA for the application or service itself, and then verifying the 2FA setup using the TOTP code generated in Passportal.

Example Scenario

A new user is setting up their 3rd party application or service 2FA security and wants to record their credentials in Passportal, including the TOTP for 2FA authentication.

  1. During the 3rd party application or service 2FA setup, when presented with the QR Code rather than scanning the QR Code Image either copy the alpha-numeric 2FA Code or create an image of the QR code

  2. Create or Edit the credential in Passportal
  3. Click +Add TOTP setup code

  4. The Add TOTP code view opens. Either
    1. Drag or paste image of QR code into the indicated section, or click Upload image, or
    2. Enter the alpha-numeric code into the Test based setup code section click Save

  5. Click Apply
  6. Passportal will then populate the TOTP code with the actual QR setup code

  7. Click Save
  8. TOTP is now configured in Passportal, view the TOTP code by clicking the eye icon to the right, or by clicking the copy to clipboard icon on the left

  9. Enter this TOTP Code into the 3rd party application or service and continue the 2FA verification

  10. Once 2FA setup is completed for the user account, the user can access Passportal to gain their 2FA code when logging into the 3rd party application or service

    11. Ensure you safely record the Recovery Key information when prompted once 2FA setup is completed - this will be needed should 2FA require a reset - some applications also require the Recovery Key in order to disable 2FA.

Best Practice: Recovery Key storage is an essential part of 2FA setup. Consider using Passportal Documentation Manager to store them in a custom Article type or in a File - and restrict access to that location using a Security Group of appropriate users.

Avoid using the Credential's Notes section to store Recovery Keys - the Notes section is not audited, and no record of who has viewed the Recovery Key is available, and can be seen by anyone with access to the Credential

The same process applies when configuring 2FA for any other 3rd party application or service - once the 2FA setup process presents the alpha-numeric code, this is entered into the Credential in Passportal and saved. The TOTP code is then viewed, and used to verify in the application's 2FA setup.

If the application is accessed by numerous technicians, the 2FA code required to login is now tied to the Passportal Credential, and therefore is usable by all technicians who have access to the Credential.

Deleting TOTP from a Credential

Before deleting the TOTP from a Credential, you must first disable 2FA in the application the credential is for

Once 2FA has been disabled in the application, there is no longer a need to have the Credential configured with a TOTP.

  1. Ensure that 2FA is disabled in the 3rd party application or service
  2. Navigate to the credential in Passportal
  3. Edit the Credential

  4. Click the red bin icon to the right of the TOTP field

  5. Read the Warning and then click Yes to continue, or Return if 2FA is still enabled in the 3rd party application or service