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 protocol, 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 credentials. 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 preferably 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.
1.1. Registration
In most cases an account for Topicus KeyHub can be registered manually. Following the Register option on the screen a three-step workflow is presented to setup an 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.
When registering 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.
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.
When using Topicus KeyHub against a LDAP-directory, the option exists of choosing 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 advised 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 either a security key, or a smartphone with a 2FA-app compatible with the TOTP-protocol can be used 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:
A choice can be made for either the Use a 2FA app or the Use a security key option.
Security key
If the security key option is chosen, Topicus KeyHub will automatically try to connect to a compatible security key. The browser will likely show a notification to this effect. Simply activate the security key using the normal procedure for the specific security key to confirm the link with Topicus KeyHub.
With physical security keys usually there is an action needed like touching a spot on the key or scanning a fingerprint. If the operating system functions as the security key, it should prompt for confirmation.
2FA app
If a 2FA app is chosen the following screen wil be shown.
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 used, 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.
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 the role for the account that is registered. 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 for the 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.
| 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.
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 advised 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 the 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:
To reset 2FA a mandatory reason should be entered. The request to disable 2FA is then to be judged by another user in the 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 synchronised with the password from the directory. If synchronisation is activated and the password in the directory is changed outside Topicus KeyHub, a password synchronisation will be started. If the user has lost the old password here, a password recovery can be started. Password recovery with password synchronisation 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.
If password synchronisation 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.
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.
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.
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.
1.4.4. Reset password and wipe associated data
| Only choose a password reset if the recovery procedure cannot be followed. For example, if there is nobody who can approve the recovery request. |
Instead of a password recovery, a user can also opt for a password reset if the password is forgotten. To perform a password reset, the user must authenticate against the directory and use 2FA. A password reset can therefore only be performed if the user has lost the Topicus KeyHub password, but knows the password for authentication against the directory. A password reset deletes all of the user’s keys, resulting in the loss of the following access:
-
Access to the personal vault and group vaults.
-
Manager privileges of groups.
-
Membership of the KeyHub administrators group.
The password entered by the user will be set as the new Topicus KeyHub password.
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 8 for more information about password usage and this three-step process.