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 a device with which a TOTP-code can be generated. There are multiple solutions, like 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 Ok in the notification and you are logged in.

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

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 a KeyHub administrator 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. Stap 2: Setup Two-factor authentication

The second step in the registration process is to setup two-factor authentication (2FA). For this step a smartphone is required with a 2FA-app compatible for the TOTP-protocol. 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

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 6. 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 7. 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 8. Activation code

After submitting the activation code the account details are displayed.

Activation
Figure 9. 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 a 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 themselved on the login-screen using the option I cannot use 2FA anymore.

Clicking that specific button leads to the following page:

Resetting 2FA
Figure 10. Resetting 2FA

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

A user can reconfigure the 2FA using the reconfigure 2FA option which is available under the Profile-section in Topicus KeyHub. To do this, the user should still be able to generate the current 2FA-code before reconfiguring it. In the case of users who have a new smartphone and still possess the old one, they can reconfigure 2FA themselves.

1.4. Password forgotton

For users who lost their passwords, the option I lost my password is available on the login-screen. This option triggers a reset-password-request of which the Topicus KeyHub administrators will be notified. If the request is granted, the password will be reset and the user will receive a new password by e-mail. This e-mail contains an <scr-activatiecode,activatiecode>>.

It is only possible to reset the Topicus KeyHub password of users which are created in the socalled internal directory. Users who are managed in other directories like LDAP or Active Directory are not able to receive a password reset in Topicus KeyHub. The reason for this is simple: Topicus KeyHub does not manage these passwords but the directory does. In these cases a password reset should be requested at the owner of the directory.
Password reset
Figure 11. Reset 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 safe 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 5 for more information about password usage and this three-step process.

Invalid password
Figure 12. Invalid password

1.6. 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 13. 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 14. Application denied

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.

Dashboard
Figure 15. Dashboard

2.1. Group activation

To gain access to the linked systems of a group, that group has to be activated. Click on a group to activate the user’s account(s) for one hour by default. After clicking a group, this duration can be extended up to 12 hours for normal groups.

Activate
Figure 16. Group activation

After the specified duration the group will be deactivated automatically. Clicking on an active group manually deactivates a group.

A group can be configured with extended access. For groups with extended access, a button for Extended access will be displayed after activating the group. Clicking this button leads to the following screen::

Request extended access
Figure 17. Request extended access

The reason for extended access can be supplied and a request will be sent to the group managers. If the request is granted, this group will be displayed on the dashboard as:

Extended access
Figure 18. Extended access

Some groups require an explicit reason before activation is possible. This reason will be part of the audit trail and can be used for reporting purposes. If a group is configured with a mandatory reaseon, the following screen will be shown after clicking the group:

Reason for activation
Figure 19. Reason for activation

2.2. Dashboard layout

Groups can be combined into folders. Activating a folder activates all groups that are part of that folder at once. Click on Manage layout…​ to create and name folders for your dashboard.

Layout
Figure 20. Dashboard layout

The screen for dashboard layout shows a list of all folders and the groups that are present within these folders. Every folder is displayed separately on the dashboard. Activating a folder activates all groups within that folder at once.

To add groups to a folder, a group can be dragged into a folder. Groups in the folder hidden groups are hidden on the dashboard. Hidden groups will not be visible by default but can be shown by pressing show all groups on the dashboard.

Click on Add folder at the top right side of the screen to create a new folder.