Introduction

Welcome to the Topicus KeyHub manual.

Topicus KeyHub ensures the authentication and authorisations of users. This manual describes how it works.

Topicus KeyHub principles

Topicus KeyHub works according to the principle central authentication, decentral authorisation. This means that every user authenticates against a single identity provider. After authentication that user will be granted authorisation and permissions according to the various groups of which he/she is a member. These groups are managed by various group managers, who are responsible for their group.

At Topicus KeyHub safety is key. This means that two-factor-authentication is required. Every user has to have at least one compatible two-factor-authentication method available. Topicus KeyHub supports both TOTP and WebAuthn protocols. For WebAuthn, any FIDO2 compatible device can be used. Examples are the USB security keys as sold by Yubico, Feitian and Google, among others. For TOTP there are also multiple solutions available, such as the Topicus KeyHub mobile app or the Google Authenticator-app.

Layout of this manual

This manual is devided into several parts. After the Getting Started section where many tips and tricks are described, the next part is all about the functionality for regular users. This contains chapters about registration of new accounts and the daily use of Topicus KeyHub. The section that follows is especially for KeyHub-administrators and group managers who can performed advanced tasks like setting up new single sign-on connections. Finally the last section contains information about the Open Virtual Appliance (OVA).

Getting Started

Registration

Topicus KeyHub supports just-in-time account registration. Just follow the URL for your specific Topicus KeyHub instance (something like https://keyhub.<your_organisation>.com), enter your username and just follow the steps on the screen. The username is probably the same as the one you need for your corporate email.

Browser-extension

Topicus KeyHub comes with a browser extension for Google Chrome and Mozilla Firefox. With this extension applying passwords and 2FA-codes becomes even easier. Go to www.topicus-keyhub.com/browser-extensions and click on the extension for your browser.

After installing the extension, go to Topicus KeyHub and in 'Profile > Settings' you can enable the browser extension by connecting Topicus KeyHub with it.

You can test the browser extension by clicking on the icon in the top-right corner of your screen. If successfully connected, all your password vaults should become visible.

Mobile app

If your organisation uses the 2-factor authentication solution of Topicus KeyHub, you can download the Topicus KeyHub-app to your phone. You can find the app in the respective app-stores of Apple and Android. With this app installed, you will receive a push-notification when Topicus KeyHub requires it. Just click 'Login' in the notification and you are logged in.

If you do not want to install the Topicus KeyHub-app, you can also use a similar TOTP-based app like the Google Authenticator or Microsoft Authenticator as a two-factor authentication solution. Although these apps work fine themselves, you will not receive a push-notification and you are required to manually enter the 6-digit code.

Security keys

In addition to TOTP-based solutions, you can also use a FIDO2 compatible security key for 2-factor authentication. Topicus KeyHub fully supports the WebAuthn procotocol, which means that you can use any compatible hardware security key (sometimes also called a "dongle").

On some devices your operating system can even function as a software security key, which means you can use, for example, the built-in fingerprint scanner as your second factor.

Manual

Topicus KeyHub comes with this context-sensitive manual. This means that whenever you press the questionmark-symbol at the bottom-left in Topicus KeyHub, this manual opens in a new browser tab at the corresponding section.

Personal vault

Topicus KeyHub comes with a personal vault which is like your password manager. You can find this vault in the Vault-section and this safe is meant for all your personal, professional credenatials. For example your username/password for your time management, sick-leave application or all other applications you use with your personal credentials.

NOTE: You can store the recovery codes for your hard drive encryption in the personal safe as well!

Groups in Topicus KeyHub

In Topicus KeyHub all authorisations are assigned through groups. Every group could provide access to one or more single sign-on applications, servers and/or a password safe for that group. The responsibility for the access a group provides and for its members are in the hands of the group manager(s). You can request access to the groups you require. Navigate to My Groups and click on 'Request'. Now a list of all groups is shown, grouped by group name. Click on a specific group, enter an optional reason and click on the 'request access' button to request access to that group.

A group access request has to be approved by one of the respective group managers.

Passwords and group vaults

Besides your personal vault Topicus KeyHub contains group vaults as well. Every group has its own vault to store and share passwords, 2FA-codes and files with other group members. Whenever you want to store a new secret like a password in Topicus KeyHub, you decide which group this secret belongs to and create a new vault record. Topicus KeyHub offers a password generator to generate strong secrets for new or updated credentials. After saving a new vault record in a group vault, every member of that vault immediately has access to that secret.

Vault records support storing files as well. Consider storing SSL-certificates and other sensitive data in a specific vault.

Profile and settings

In Topicus KeyHub every user has its own profile settings under Settings at the bottom left of the Topicus KeyHub interface. Here you can change your language-settings, upload your SSH-key and consult your active sessions and user ids.

Changing your phone

Whenever you have to change phones, you will need to register your new device to generate 2FA-code again. If you still have your old phone in possession, you can easily reconfigure your 2FA from your Profile-page. If you lost your old phone, you can request a 2FA-reset from the Topicus KeyHub login-screen. Such requests always require another user from your organisation to approve them.

SSH-keys

Topicus KeyHub offers the possibility of uploading your SSH-key. This key is provisioned when a group is activated that grants access to a UNIX-based system. After activating the group, you can logon using your SSH-key.

Group managers

Every group should have at least one group manager, and preferrably two or more. A group manager is responsible for all members of that specific group and for all the access that group provides. Group managers can approve or decline group-access-requests and assign new group managers.

Usage

1. Registration and authentication

In order to use Topicus KeyHub an account is necessary. There are two ways of obtaining an account: by manual registration or with an activation code.

Both options are available on the login screen.

Loginscherm
Figure 1. Loginscreen

1.1. Registration

In most cases an account for Topicus KeyHub can be registrered manually. Following the Register option on the screen a three-step workflow is presented to setup your account.

1.1.1. Step 1: Create account

Every Topicus KeyHub account is validated against an existing 'user directory', most likely an LDAP or Active Directory. To create a new Topicus KeyHub account, the corresponding directory should be chosen first. In most cases only one option is available and the default selection will be the right one.

Register new account with LDAP
Figure 2. Register new account with LDAP

When registrering an account at an LDAP-directory, the username and password of the corresponding user should be entered. If these credentials are unknown: it is probably the same username and password that are used for e-mail or logging on to the network of the company.

Register new account with external directory
Figure 3. Register new account with external directory

If the account is located in an external directory, the screen displayed above will be shown. The user is required to follow the link to logon to the external directory. After authenticating against the external directory, the user will be guided back to Topicus KeyHub and the corresponding username is shown.

It is possible to enable editable usernames. In that case the user is free to change ths username to a value of his/her liking. Be cautious though, because this username will be user throughout Topicus KeyHub and this username is also to be used when logging on to linked systems. It is not possible to change the chosen username.

After the credentials are validated, the method of password usage can be chosen.

Setting password usage
Figure 4. Setting password usage

When using Topicus KeyHub against a LDAP-directory, the option exists of chosing a different password for Topicus KeyHub. This password can be different from the password with witch the authentication took place. In most cases it is not adviced to choose a different password and the default settings will suffice.

For external directories it is mandatory to choose a password for Topicus KeyHub This password will be used to encrypt the password safes and to create accounts on linked systems.

See chapter chapter 5 for more details and possibilities on password usage.

Choosing the password concludes step 1.

1.1.2. Step 2: Setup Two-factor authentication

The second step in the registration process is to setup two-factor authentication (2FA). For this step you can either use a security key, or a smartphone with a 2FA-app compatible with the TOTP-protocol. Any FIDO2-compatible security key should work. For TOTP, the Topicus KeyHub-app is recommended as this app supports push-notifications. With this app the user only needs to enter Yes or No in order to verify a logon request instead of typing a 6-digit code. Alternative apps that are supported are Google Authenticator, Duo Mobile and the Microsoft Authenticator.

If Topicus KeyHub authenticates against an external directory, it might be possible to skip step 2. This is most likely due to the fact that the external directory already enforces 2FA.

The following screen is displayed:

Setup 2FA
Figure 5. Setup 2FA

You can pick either the 2FA app or the security key option.

Security key

If you pick security key, Topicus KeyHub will automatically try to connect to a compatible security key. Your browser will likely show a notification to this effect. Simply activate your security key in the normal way to confirm you want to link it to KeyHub.

Setup WebAuthn
Figure 6. Setup WebAuthn

With physical security keys you usually have to touch a spot on the key. If your operating system functions as your security key, it should tell you how to confirm.

2FA app

If you choose 2FA app, you will next see the following screen.

Setup TOTP
Figure 7. Setup TOTP

After scanning the QR-code with the Topicus KeyHub-app, the screen will show the type of the smartphone. If the information is correct, 2FA can be enabled.

The Topicus KeyHub-app requires an internet connection to setup and receive push-notifications. If no internet connection is present, the app can generate the 6-digit code as well.

If another app is useed, this app will add the Topicus KeyHub-account after scanning the QR-code. To finalise the 2FA-setup the 6-digit verification code will have to be entered in the above screen. After entering this code, 2FA is enabled.

This concludes step 2.

1.1.3. Step 3: Request groups

The final step in the registration process is to request groups. A group grants access to the specific passwords, servers, applications and linked systems of that group.

Request groups
Figure 8. Request groups

Groups can be found by using the search field. Depending on naming conventions the groups displayed could correspond to projects, teams, products or departments.

Click on the icon on the right side of a group to request access to that group. Select all groups that apply to your role within the organisation. After access to the required groups is selected, the Next-button will continue to the next screen.

The next step is to enter a reason of your request. This reason is displayed to the group managers of the group which can help them decide whether the request is valid and should be granted. It is highly recommended to enter a brief and clear description of why access to that group is requested.

Reason of the request
Figure 9. Entering a reason for the request
Before the secrets of the group are available, the access request should be validated and granted. This means that access to a specific group is not instant but takes some time, depending on the group manager(s).

Finally the button Send and login sends out the requests and logs the user in on Topicus KeyHub.

1.2. Activation code

Registration of a Topicus KeyHub account can also occur by using a registration code. On the login-screen the option I have a registration code is available (or click on the link in the corresponding e-mail). The registration code can be entered in the next screen.

Enter activation code
Figure 10. Activation code

After submitting the activation code the account details are displayed.

Activation
Figure 11. Activation

If the account details are correct, the next step is to choose a password. This password should consist of a minimum number of characters. Be adviced that specific words or characters are considered invalid and will therefore not contribute to the total number of characters of a password.

The next step is to setup 2-factor authentication. For a detailed description see the corresponding paragraph enabling two-factor-authentication.

1.3. Resetting two-factor authentication

In some cases it is necessary to reconfigure 2FA, for example when your security key or smartphone is broken or stolen. In order to reset 2FA it is required that the 2FA is disabled for that specific account. Users can request to disable 2FA themselves on the login-screen using the option I cannot use 2FA anymore.

Clicking that specific button leads to the following page:

Resetting 2FA
Figure 12. Resetting 2FA

To reset 2FA a mandatory reason should be entered. The request to disable 2FA is then to be judged by another user in your organisation. If the request is granted, the user and the other user are notified by e-mail.

A user can reconfigure the 2FA using the options available under the Profile-section in Topicus KeyHub. Users who have multiple smartphone apps or security keys registered can simply login using another registered 2FA method. Otherwise, the user should make sure they are still able to login using their current 2FA method, either by generating the current 2FA-code or using their security key, before reconfiguring 2FA. In the case of users who have a new smartphone and still possess the old one, they can reconfigure 2FA themselves in this way.

1.4. Password lost

If the user has forgotten his or her password, a request to recover the password can be submitted via I forgot my password. The procedure for recovering a password differs per account type and depends on the options chosen for the password. The different procedures are discussed below.

1.4.1. Account from an LDAP directory

Users from an LDAP directory use the Topicus KeyHub password to open the vault. This password may be synchronized with the password from the directory. If synchronization is activated and the password in the directory is changed outside Topicus KeyHub, a password synchronization will be started. If the user has lost the old password here, a password recovery can be started. Password recovery with password synchronization will ask for the new directory password and a reason for the recovery. This password is then also used as the new Topicus KeyHub password.

Recover password - Synchronized password
Figure 13. Recover password - Synchronized password

If password synchronization is not enabled, the Topicus KeyHub password will be requested when the vault is opened. If the user has lost the password here, a password recovery can be started. The user enters the new password twice, along with a reason for the recovery.

Recover password - New password
Figure 14. Recover password - New password

After submitting the request, the account will be locked. Once the request has been approved by 2 users, the request can be completed. After completing the request, the Topicus KeyHub password of the user has been changed to the new password. The request can be cancelled by the user at any time. The old or the new password must be entered here.

Account locked
Figure 15. Account locked

1.4.2. Account from an OIDC directory

Users from an OIDC directory use the Topicus KeyHub password to open the vault. After clicking on the link I forgot my password the user will arrive at the page where a new password for Topicus KeyHub can be chosen. The user must enter the new password twice, provide a reason for the recovery, and submit the request. After this, the account will be locked until the request has been processed. Once the request has been approved by 2 users, the request can be completed. After completing the request, the Topicus KeyHub password of the user has been changed to the new password.

1.4.3. Account from an internal directory

Users from an internal directory use the Topicus KeyHub password to log in to Topicus KeyHub and to open the vault. Clicking on the I forgot my password link will take the user to the 'forgot password' page below. After entering the username, the user will receive an email with an activation code. This code allows the user to initiate the recovery procedure.

Password lost
Figure 16. Password lost

After entering the code, the screen is displayed where the user can choose a new password for Topicus KeyHub. The user must enter the new password twice, provide a reason for the recovery, and submit the request. After this, the account will be locked until the request has been processed. Once the request has been approved by 2 users, a 30 minute cooldown period will begin. The request can be completed after these 30 minutes have passed, or as soon as a 3rd user approves the request. After completing the request, the user’s password has been changed to the new password.

Account locked - Cooldown
Figure 17. Account locked - Cooldown

1.5. Mandatory password change

In some cases the following message can be displayed when signing in to Topicus KeyHub. This occurs when the password (no longer) complies to the criteria set by Topicus KeyHub. The password could be too short or the user could not yet have a personal password vault due to preliminary ending the registration wizard before. In this case the user will be guided through a three-step process in order to pick a new password. As this process is equivalent to the registration wizard, see the corresponding section in chapter 6 for more information about password usage and this three-step process.

Invalid password
Figure 18. Invalid password

1.6. Password synchronisation

A user can choose for password synchronisation between Topicus KeyHub and the directory. When the password is changed on the directory, Topicus KeyHub will detect this at logon and prompt the user for re-synchronisation. Topicus KeyHub will need the old and the new password to update the keys for vault. When the new password does not meet the password requirements set by Topicus KeyHub, the user will be asked to choose a new password.

Password synchronisation
Figure 19. Password synchronisation

1.7. Using Single Sign-On to logon to other applications

Topicus KeyHub can act as a SSO-provider as well. If such a SSO-connection is present, the login-screen of Topicus KeyHub will be displayed instead of the login-screen of the target application. The first time a SSO-connection is used, the user is asked for his/her consent.

The following screen is then displayed:

User consent
Figure 20. User consent
In most cases the application will only request the profile of the user. Granting this request will provide the application read-only rights on only the profile of the user. This profile is ofter required to verify the identity of the user.

Single Sign-On in Topicus KeyHub is provided through groups. This means that when a user tries to use SSO to an application without being a member of the corresponding group, the following screen will be displayed. This screen shows the group that the user should request in order to use SSO.

Application denied
Figure 21. Application denied

1.8. Sychronizing TOTP time-offset

If a separate device is used to generate verification codes, the internal clock of such a device can fall behind KeyHub’s system clock. KeyHub will detect such an offset and will automatically apply a compensation. In exceptional cases, the shift may be too large to automatically compensate. When that happens, KeyHub will ask the user to input two consecutively generated codes, to verify the offset.

Verifying time offset
Figure 22. Verifying time offset

2. The dashboard

The dashboard shows all relevant information for the daily use of Topicus KeyHub. On the left side all groups are displayed which can be activated. The right side of the dashboard shows the most recent events of groups you are member or manager of. Events that consider your account are displayed on the right side as well. Any pending requests are shown at the top right side where the user can grant or decline them if applicable.