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.

Figure 1. Loginscreen

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.

Figure 2. Register new account with LDAP

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.

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.

Figure 4. Setting password usage

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:

Figure 5. Setup 2FA

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.

Figure 6. Setup WebAuthn

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.

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 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.

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 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.

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.

Figure 10. Activation code

After submitting the activation code the account details are displayed.

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 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:

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 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.

Figure 13. Recover password - Synchronised 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.

Figure 14. Recover password - New password

After submitting the request, the account will be locked. During this stage the requester is informed which users are selected to process their request. Once the request has been approved by 2 users, the request can be completed.

Figure 15. Account locked - Approval pending

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.

Figure 16. Account locked - Complete recovery

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.

Figure 17. 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.

Figure 18. Account locked - Cooldown

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.

The difference between password recovery and password reset

The Topicus KeyHub password is used to encrypt the user’s data. Data in the vaults directly depends on this. These keys are also used to sign and verify group membership. With a password recovery, the most important keys remain intact. After the recovery, the user can still access the data in the vaults and sign group memberships. On the other hand, with a password reset, all keys are lost. The user loses access to all vaults. For group vault, access will have to be requested again. The contents of the personal vault are permanently lost. The user also loses the ability to sign group memberships and thus loses manager privileges to groups.

Figure 19. Password reset

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.

Figure 20. 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.

Figure 21. 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:

Figure 22. 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.

Figure 23. Application denied

1.8. Synchronising 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.

Figure 24. 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 ten most recent events of groups for which the current user account is a member or manager. Events that consider the current user 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.

Figure 25. 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.

Figure 26. Group activation

The desired end time for the activation can be set with the slider. The set activation duration will be set automatically with the next activation of the group. After the time period has expired, access to the group will be automatically deactivated. Access to a group can also be immediately deactivated by clicking on the group again. With manual deactivation of a group, the remembered activation duration is reset to the default of one hour.

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::

Figure 27. 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:

Figure 28. 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 reason, the following screen will be shown after clicking the group:

Figure 29. Reason for activation

For a group it can be configured that authorisation is required for activation. In that case the screen below will be displayed on activation. After sending the request, a member of the authorising group will review this request. If accepted, the group will be activated with an end time of one hour in the future. The user can subsequently extend the activation himself during the permitted period. The end of the period is shown with a red triangle on the timeline. When the group becomes inactive, it can be reactivated, as long as this falls within the permitted period. If authorisation is combined with a reason, the reason for the request will be mandatory and recorded in the audit trail.

Figure 30. Authorisation 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 the user dashboard.

Figure 31. 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.

Figure 32. Add folder

Each folder can be assigned a name. Pay attention to the name and choose a name that describes the purpose of the underlying groups. After clicking on Save the folder is added to the Dashboard layout and groups can be assigned to the folder. Click on the icon next to the group name to change the name.

3. The launchpad

The launchpad displays tiles that allow users to quickly navigate to certain applications. These tiles are shared through group membership. The different types of tiles are described below.

Figure 33. Launchpad

3.1. Manually created launchpad tiles

A group manager can manually add a tile to a group. For a manually added tile, the following information must be provided:

Group: The group in which to display the tile.
Logo: The logo to be displayed with the tile. An image is generated by default. By clicking on this an image can be specified.
Title: The title to display with the tile.
Link: The link that opens when the user clicks on the tile.

Figure 34. Manually created launchpad tiles

3.2. Launchpad tiles for SSO applications

A tile for an SSO application is created at the application itself by the technical manager of the application concerned. The tile is displayed for all groups that have access to the application. The name of the application is used as the title of the tile. For a tile for an SSO application, the following information must be provided:

Logo: The logo to be displayed with the tile. An image is generated by default. By clicking on this an image can be specified.
Use an IdP-initiated login: An IdP-initiated login can be used for applications that support this. This is possible with OAuth 2.0 applications where the Initiate login URI is entered or with a SAML v2.0 application. The application itself must of course support an IdP-initiated login.
Link: If the application does not support IdP-initiated login, the link that is opened when the user clicks on the tile must be entered manually.

Figure 35. Launchpad tiles for SSO applications

3.3. Launchpad tiles for vault records

A tile for a vault record is created at the vault record itself. Only managers of a group can make a vault record available as a tile on the launchpad. For the title and link of the tile, the name and link of the vault record are used. On a tile for a vault record, only the logo can be specified:

Logo: The logo to be displayed with the tile. An image is generated by default. By clicking on this an image can be specified.

Figure 36. Launchpad tiles for vault rules

4. My groups

My groups shows all groups the user has access to. The description of the group is displayed as well. Groups where the user has management privileges are indicated with a star. For managers, a dashboard is available via the menu with insight into all groups of which the user is a manager.

Figure 37. My groups

4.1. Request access

To join a group the access has to be requested by clicking the button Request on the top right corner of the screen.

Figure 38. Request groups

Every user can request access to a specific group. Each request has to be granted by at least one group manager. To speed up this process the access request can be provided with a specific reason. This reason may help the group managers decide whether or not to grant access. After access is granted, the group will be shown at My groups and on the dashboard if applicable.

4.2. Request new group

If a new group is required, a request can be send to create a new group. Click on Request new group at the top right corner of the screen to request a new group.

Figure 39. Request new group

Every user can request a new group. A clear name should be chosen for the group that meets any requirements shown in the field. In the selection box the user can choose from prefixes that are already used within the Topicus KeyHub installation. If such a request is granted the requesting user will automatically be assigned group manager of the new group.

The requests for new groups are verified by a central management group and at least one manager has to grant the request. To speed up this process the request can be provided with a reason as of why this new group is required. After submitting the request, the pending request will be shown on the dashboard.

To send the group managers an e-mail, the link mail manager can be used. To leave a group the button Leave group can be clicked. After leaving a group the user has to request access to the group again if necessary.

4.3. Group information

After opening a group, a detail screen is displayed with the following information:

Group details: The name and description of each group is shown. Depending on the options chosen for the group, more fields can be displayed here. For a complete overview of the options of a group, see group details.
Audits: The last 5 audits of a group are shown. If there are more audits, a link is shown to show them all. For more information about audits, see auditing groups.
Members: All members of the group are shown. Managers are indicated with a star. If an end date is set for the membership, it will also be shown.
Performs authorisation for: If the group performs authorization over other groups, they will be shown here. Details about the group can be get by clicking on the group. A dashboard is also available with insight into all groups over which authorization is performed.
Nested groups: Any groups nested under this group will be shown here. Details about the group can be get by clicking on the group. For more information about nesting, see nested groups.
Audit log: The group’s audit log is displayed. When clicking on more, the audit log can be searched for specific records.

For each group contact can be made with the managers of the group via mail manager. A group can also be left via Leave group. Please note that once a group is left, access must be requested and approved again in order to regain access to the group.

4.4. Manage groups

For managers of groups there are a number of extra options available for a group. For a manager of a group, it is possible to edit the properties of a group. A group consists of the following properties:

UUID: A unique identifier of a group within Topicus KeyHub.
Organisational Unit: The organisational unit to which the group belongs. Only users who are members of this organisational unit can join the group.
Name: The primary name of the group. The first word of a group name is used to group multiple groups into a category. Group names have to be unique throughout the entire application.
Classification: Groups can be divided into classifications. This classification sets policies for group settings so that the intended security can be enforced. The classification cannot be changed by the group manager. This is done by someone who has access to the auditor dashboard for groups.
Extended access: By default a group can only be activated for a maximum of 12 hours on the dashboard. With this option you can choose to allow extended access to a group with a maximum of 1 or 2 weeks. To enable this extended access on the dashboard, the user must first request approval (with the exception of the Up to 2 weeks, without approval option). Extended access may be required to perform lengthy operations on systems such as large copy operations.
Record audit-trail: When enabled, a user has to provide a reason every time this group is activated. This reason will be written to the audit log and can be useful certification purposes.
Rotating password required: If checked, the user will only be able to activate this group if the user uses a rotating password (see password use). Requiring a rotating password significantly increases the security as potentially leaked passwords are only active for 24 hours.
Private group: A private group is only visible to its members, KeyHub administrators and auditors. For all other users the group will not be visible in KeyHub or accessible in any way. This also means that they can not request access to this group, they’ll have to be added by a manager.
Hide audit trail: The audit log records for this group are not shown to regular members on the dashboard and are only visible in the audit log under 'daily use'. For large groups with many mutations, these records are less relevant and could obscure other records that are more important. The group’s audit log can still be viewed by regular members under the details of the group.
Vault recovery availability: Limit vault recovery options for vaults with highly sensitive information. With Fully available access to the vault remains available after a password recovery and the recovery key can be used as an emergency procedure to restore access. If Only with the recovery key is selected, users will lose access to the vault after password recovery, but the recovery key can still be used. Not available completely disables vault recovery and only allows members of the group to give users access. In this case, after deleting a group, it will not be possible to restore the contents of the vault.
Activation required for vault access: If enabled, activation of this group is required before passwords can be read.
Authorising group for activation: When configured, the chosen group must authorise request to activate this group.
Authorising group for membership: When configured, the chosen group must authorise adding new members and modify members' manager privileges for this group.
Group with delegated privileges: When configured, the chosen group will get delegated manager privileges for this group.
Authorising group for audits: When configured, the chosen group will have to approve an audit before it is made final. Any changes from the audit will only be applied after approval.
Technical administration: When enabled this group can create and manage applications and linked systems. Permission is required to enable this option. For more information, see the chapter about applications and the chapter about linked systems.
Access profile administration: When enabled this group can create and manage access profiles. Permission is required to enable this option.
Periodic audit months: The selection of months on which a periodic group audit must be carried out by the managers of the group. At the beginning of the month the manager will receive a notification on his dashboard. Then there is time until the second Tuesday of the month to carry out the audit. After this expiration date, the notification will change to an overdue audit.
Description: A detailed description of the access this group provides and/or the purpose of this group. This information will be shown to members of the group and users who request access to this group.

Figure 40. Edit group

A manager can also perform an audit on the group, see auditing groups. The management of the members of the group is also the responsibility of a group manager. Existing members can be edited or removed by clicking on them. Click on Add to add a new user directly to the group. In the popup, the user must also choose whether this new user becomes a manager or a standard user. When a group membership is given an end date, the user will automatically be removed from the group when the date expires.

Figure 41. Edit member of group

4.5. Auditing groups

Groups can be audited. This means that a group manager performs an audit on the group members and this audit is stored in Topicus KeyHub. An audit can be performed at any time and the event of an audit is stored in the audit trail.

Audits can be viewed via the details of a group. For managers this page also offers the possibility to start a new audit with the add button.

Every audit can contain a general description, for example with the reason of the audit. Additionally, every group member can be audited on whether the accounts is still valid for this group and possesses the correct role in the group.

Each group member can be audited by either checking the checkmark on the left. This indicates that the group member is valid. If a group member is not supposed to be part of the group, the group member can be removed from the group by checking the red cross on the right side. If a group member has the group manager role, the group manager can be reassigned to a regular group member by checking the middle, yellow icon.

For every group member an optional description can be added, for example to explain why this member was removed by this audit.

Only after saving the entire group audit are the changes put into effect. If an audit is saved as a draft, it can be further edited and saved later. Only one draft audit can exist per group. A draft is only visible to managers of the group and does not count in the audit schedule.

Figure 42. Audit a group

A group can be configured to require audits be reviewed by another group. If this is set, an audit will be put 'under review' when saved. A message will automatically be sent to the members of the reviewing group. The audit in review will be put back in draft if there is a change in membership within the group. A manager of the group will have to redo the audit and resubmit for review.

Figure 43. Audit under review

When performing a review of an audit, all actions and comments are displayed. These actions must be reviewed and then the audit must be either approved or rejected. When reviewing the audit, feedback can be given to the manager of the group.

Figure 44. Reviewing an audit

4.6. Nested groups

A group can be nested within another group. The nested group will automatically inherit the group memberships from the parent group. Changes to parent group memberships affect the nested group immediately. With a nested group, it is still possible for a user to be a member of the group directly. In the event that the user is a direct member of both the nested and parent groups, the nested group’s direct membership properties will take precedence over those of the parent group. In this way, for example, a user can be made manager of the nested group, while being a normal member of the parent group. If an end date is set to a nested direct membership, the membership will be converted to a nested membership upon reaching that date.

When requesting nesting of a group, it can be specified how to deal with existing memberships:

Retain: Existing memberships will be retained and only new, nested memberships will be added.
Convert: Existing memberships are converted to nested memberships if they exist in the parent group. Other memberships will be retained.
Remove: All current memberships will be deleted and replaced with nested memberships.

Nested groups cannot have group membership authorisation. If this is configured on the top-level group, users can still be added directly to the nested group.

Figure 45. Add nested group

4.7. Audits and nested groups

If a group is nested under another group, accounts inherited from the parent group will be hidden by default. It is possible to open these accounts and convert them to direct membership as part of an audit.

If a group has one or more nested groups under it (directly or nested under a nested group), these nested groups can be audited directly under certain conditions. All members of the nested group must originate from the nesting, and therefore not be direct. If the nested group has a designated authorizing group for audits, this should be set to the same as on the group being audited. All nested groups are displayed, and for each group it can choosen whether it will be directly included in the audit or not.

Figure 46. Nested groups and audits

4.8. Delegated manager privileges

Within a group, another group can be designated for delegation of manager privileges. All members of the designated group are granted these delegated privileges. This allows the members of this group to perform management for the group without being a member of the group themselves. It allows them to perform the following operations:

Add, remove or edit group members.
Edit group properties.
Perform audits on the members of the group.

Since they are not members of the group itself, they do not have access to:

The vault of the group.
Connected applications via SSO.
Linked systems.
Requests handled by managers or members of the group, such as requests for new members to join the group and requests arising from the group’s responsibilities.

To prevent the delegated privileges group from becoming too much of a concentration of rights, it is mandatory to set up an authorizing group for membership before delegated manager privileges can be issued. Any addition or update to the members of the group must therefore be additionally approved. It is also not possible for users to add themselves to the group.

A group that delegates its manager privileges cannot be nested or itself have nested groups.

For delegated manager privileges, the group vault key is split into two parts. The first part lives with the group with delegated manager privileges. The second part lives with the authorizing group for membership. While it is possible to designate the same group for both roles, this is strongly discouraged. This is because in such a situation the complete key will come to lie with a single group. This significantly reduces the database’s resistance to an offline attack. The same problem occurs if a user is a member of both groups. Then, the key is also only protected by a single factor.

4.9. Removing groups

Removing a group from Topicus KeyHub requires permission of a KeyHub administrator. After repeating the name and an optional reason, this request will be send to the KeyHub administrators. Until the request is approved, the group is still visible and active.

Removing a group cannot be undone.

If a group is deleted, all elements that are attached to the group are also deleted. Elements that are removed are:

All vault records of the group.
All applications that are administered by the group or for which the group is owner.
All groups on linked systems for which the group is owner.

In some cases, a group cannot be deleted because there are elements attached to it that are not (directly) removable. The non-removable elements are shown in red on the page. Elements that cannot be removed are:

Linked systems for which group is the technical administrator. For these systems, administration must be transferred or they must be removed manually.
Built-in applications from Topicus KeyHub for which the group is owner or performs administration. The responsibility and/or administration will have to be transferred to another group.
An internal LDAP application that is used by a linked system. The associated linked system will first have to be removed.
Nested groups. The group nesting will first need to be undone.

Figure 47. Delete groups

5. Vaults

This page shows all vaults the user has access to. Every group of Topicus KeyHub has its own vault and each vault consists of vault records which contain data like secrets and passwords. Besides shared group vaults, each user has its own personal vault as well.

Figure 48. Vaults

All passwords, files and TOTP-secrets are encrypted with the password of the user. Depending on the password setting and login-method of the user, the vaults are already unlocked. If not, the user needs to provide the password to unlock the vaults.

5.1. Vault records

A vault consists of one or more vault records. Clicking on the Add record-button at the top right corner opens the screen to add a new vault record.

Figure 49. Add vault record

Each vault record consists of multiple fields.

Vault: The vault where this record resides. It also indicates whether the record is shared with or from another vault.
UUID: A unique identifier for the vault record within Topicus KeyHub.
Name: The name of the vault record. This can be modified on a shared copy, doing so does not affect the original record and is only visible within the vault in which it resides.
Colour: This colour is displayed in the vault and can be used to visually group multiple records.
Launchpad tile: A records with a link can also be included as a tile on the launchpad. See the chapter about the launchpad for more information.
Link: For records that belong to a website, this website can be specified. This link is also used by the browser extension to directly find the correct records for a site. If the full domain name, including subdomain, matches, the line will be displayed at the top. Records with a different subdomain are listed below exact matches.
Username: The username associated with this vault record. This username can be filled in automatically by the browser extension.
End date: An optional end date on which the record’s validity expires. See below for more information.

The following fields are encrypted and are therefore protected against (database) breaches.

Password/secret: The password which is used to log in to a specific service or website. The 'Generate password' link can generate safe passwords for new credentials. Providing a predetermined password is also possible.
TOTP/2FA key: The secret of a 'Time-based One-Time Password' which is commonly used for two-factor authentication. This secret is used to generate the 6-digit code and this code is valid for 30 seconds. A QR code is often displayed when setting up two-factor authentication for an application. Usually the key is also shown with this QR code. After storing a vault record with a TOTP-secret, this secret is hidden and can only be overridden with a new secret.
File: A file like a SSL-certificate or a private key. This file has a size limit of 2 MB.
Remarks: Any remarks or additional information for this vault record. The remark is encrypted as well.

Any vault record can be modified by clicking on the record.

5.2. Vault records with end date

A vault record can have an optional end date. When a vault record expires though, the secrets are still valid and can still be used. Providing an expiry date is especially useful for notifying all group member of the fact that a certain secret should be renewed.

Figure 50. Warning expired vault record

This warning is displayed at the vault record page as well. Notifications of all expired vault records for the logged-in user are displayed on the dashboard.

Figure 51. Expired vault record on the dashboard

Each vault record with an end date can be assigned a notification period as well. After providing the end date, this field will be visible and can be changed when required.

Figure 52. End date and notification period

5.3. Password strength

The strength of each password in the vault is estimated. If the password is not assessed as very strong, this strength is displayed after the name of the vault record. Depending on the strength, the user is encouraged to a greater or lesser extent to change the password:

Red: The password is very weak and should be replaced with a stronger password as soon as possible.
Orange: The password has moderate strength. It is recommended to choose a stronger password, if this is acceptable for the application to which the password belongs.
Light green: The password is strong but less strong than a password generated by Topicus KeyHub. To be on the safe side, the password can be replaced.
No indicator: The password is very strong and probably generated.

A password may also contain an indication for a duplicate password. Reusing the same password for different services is unwise. If the passwords belong to different services, they should both be changed.

Topicus KeyHub has a built-in password generator. These passwords are very strong, unique and consist of a mix of uppercase letters, lowercase letters, numbers and special characters. Preferably use these generated passwords. If a password generated by KeyHub is too long for a website or application, you can shorten it to the desired length manually.

Figure 53. Password strength indication

5.4. Move, copy or share vault records

The button behind the name of the vault serves to move, copy or share the record to another vault. These actions can only be performed by the manager of the group or the owner of the personal vault. If a record is shared with one or more other vaults, any change to the original will be immediately applied in all other safes. The name of a shared copy will not be overridden, if it has been modified within the vault it resides. The shared copies can be deleted, whereby the original will remain. If the original is deleted, all shared copies will also be deleted. It is also possible to specify a time period for sharing, so that the shared copy is automatically deleted after this time period has elapsed.

Figure 54. Move, copy or share vault records

It is possible to move or copy vault records to vaults that the user cannot access. In this case, the operation cannot be undone by the user himself. Topicus KeyHub will ask for additional confirmation by means of the warning below.

Figure 55. Confirm moving or copying of a vault record

5.5. Access to vaults

Management of a vault is the responsibility of the corresponding group manager. Each new group member automatically gains access to the vault and the vault records. As the vault records are encrypted with the password of each user, a password reset of a user withdraws access to the vault records. In such an event, the user will be presented the following message:

Figure 56. No access to a vault

Here the user can request the group managers to restore access to the vault of the specific group.

5.6. Personal vault

Every user of Topicus KeyHub has its own personal password vault. This vault is only accessible to the user and it is not possible for other users to request access to a personal vault. It is possible to move vault records from the personal vault to another shared vault.

After deactivating an account in Topicus KeyHub all vault records in the personal vault of that account will no longer be accessible. When deleting an account in Topicus KeyHub the corresponding personal vault will also be deleted. Therefore it is not recommended to store non-work-related items in the personal vault. The personal vault in Topicus KeyHub is meant only for personal work-related items.

5.7. Export passwords

With the 'Export' button the contents of a vault can be exported as a CSV file. Only the personal vault or a vault of a group of which the user is a manager can be exported.

TOTP secrets and files are not exported, nor are vault records shared from other vaults. Because the export format is the same as the import format, it contains an empty column for the TOTP secrets.

Figure 57. Export passwords

6. Manage access

Manage access shows a list of all groups that the user can perform access management for. Members of groups with technical administration and managers of groups with access to systems can manage this access. For each group, the name shows which rights the user has within the group: technical administration and/or management privileges. A list of applications, linked systems, groups within these systems, internal directories and webhooks is also shown for each group.

Figure 58. Manage access

For each line within the group, the following properties are visible:

Name: The full name of the application, system, group, internal directory or webhook.
Type: The type of the application, the linked system or the internal directory.
Technical administration: The group which performs technical administration of the application or the linked system. This column is not available for a group on a linked system, an internal directory or a webhook.
Owner: The group with ownership for the application, the group on a linked system or the internal directory. This column is not available for a linked system or a webhook.
Access: If the group has access to the application or the linked group, this access can be configured or deleted here. This column is not available for a linked system, an internal directory, a webhook or if the group does not have access to the application or linked group.

6.1. Managing applications and/or linked systems

For groups where Application administration is enabled, applications and linked systems can be created and edited. The administration of an application and linked system includes the technical configuration of the application including webhooks. The technical administrator can add groups to a linked system or application, giving that group access to the system or application. This request must be approved by a person responsible for the application or linking group (see below). For more information on these topics, see the chapter on applications or the chapter on linked systems.

6.2. Responsibility of applications and groups on systems

Applications and groups on linked systems are a responsibility of the group managers of the appointed groups. Decisions on whether to grant access to a group on system or an application are the responsibility of the group managers. Transferring the technical management or the responsibility to another group is possible. This request has to be granted by a manager of the receiving group.

6.3. Access to an application

Access to an application can have two meanings, depending on the type of application and the configuration. The most common relationship is SSO: the users of the group can use SSO log on to the application. The exception is the OAuth2 client, where the application itself has access to the data of the group in Topicus KeyHub, such as its vault. It is also possible that an OAuth2 client will be granted permissions that normally belong to the members of the group.

The following property can be set with an SSO application:

Activation required: To access this application, the user must first activate the group on the dashboard.

Figure 59. Access to an application

For an OAuth2 client, the granted permissions are shown. These permissions can be revoked if desired. See the chapter on permissions for OAuth 2.0 clients for more details on these permissions.

Figure 60. Permissions of an OAuth2 client within a group

6.4. Access to a group on a linked system

The following property can be set for a group on a linked system:

Static account provisioning: If checked, this group can no longer be activated by a user. Instead the group will always be active. For all members of this group, their account with this group will remain active as long as the users remain member of this group.

Figure 61. Access to a group on a linked system

6.5. Managing accounts of an internal directory

Managers of the owning group of an internal directory can see and manage the accounts of the directory via Manage access. They can do this by opening the internal directory and navigating to accounts.

7. Manage access profiles

Access profiles are part of the identity and lifecycle management module of Topicus KeyHub. This module is currently still under development.

8. Auditlog

The audit log provides an overview of all events to which the logged in account has permissions. For all users, the events related to their own account are visible. For all users, the events related to the groups they are a member of are visible. All events are visible to members of the "Keyhub administrator" group and for members of the group with the "Auditor" role.

Figure 62. Auditlog

Each line in the audit log consists of three columns: date, time and the actual event. By scrolling, more lines appear automatically. Lines are initially shown for the last two weeks. For older events you can click on SEARCH FURTHER BACK. This option appears at the bottom of the displayed events.

8.1. Filtering events

You can filter on various criteria. After selecting the criteria, press SEARCH to list the events that match the specified criteria.

Only show my records: This option is only available to members of the "Keyhub administrators" and "Auditors" group. Checking this option will filter out events related to the user’s own account and groups of which the user is a member.
Show daily use: By checking this option, a number of record types will become available at (ALL RECORD TYPES) that are not shown by default to maintain an overview. These will then become available for selection.
All record types: Here you can choose which record types should be displayed.

By checking Show daily use extra options appear in this selection box.

Search for keywords…: Values entered here are used as a filter for the events to be displayed.
Before…: Only events older than the selected date are displayed.
Export: Generates a csv file with the filtered events. Before the export is made, a popup appears in which the date range can be adjusted. As soon as EXPORT is pressed, the csv file is generated and downloaded.

Figure 63. Export events

The csv file contains the following values:

seq,"timestamp","type","by party (UUID)","by party (name)","account (UUID)","account (name)","group (UUID)","group (name)","group2 (UUID)","group2 (name)","groupClassification (UUID)","groupClassification (name)","directory (UUID)","directory (name)","client (UUID)","client (name)","system (UUID)","system (name)","service account (UUID)","service account (name)","certificate (UUID)","certificate (name)","vault record (UUID)","vault record (name)","webhook (UUID)","webhook (name)","request (UUID)","organizational unit (UUID)","organizational unit (name)","access profile (UUID)","access profile (name)","security level","parameter 1","parameter 2","parameter 3"

9. Profile

The Profile-page is used to change preferences and show all events and activities of a user.

9.1. Account

The first page that is shown is the Account tab. This screen shows the most relevant details of the current account. Changes regarding security and interface settings can be applied here as well.

Figure 64. Account

9.1.1. Password usage

Topicus KeyHub uses passwords for various purposes. To fully understand the possibilities of passwords, it is important to know these uses. There are three different kinds of passwords used by Topicus KeyHub: the directory password, the KeyHub password and the temporary password. The different passwords have their own specific usecases:

Authentication: The directory password is the primary factor of authentication. When logging on to Topicus KeyHub, this directory password is requested and used to authenticate the user against the directory. Topicus KeyHub will asks the user for his/her directory password every four (4) hours for security purposes.
Vault encryption: The vaults of a user are encrypted with the KeyHub password. This is the password Topicus KeyHub asks for when opening a vault record. By default this is the same password as the directory password but as Topicus KeyHub is not aware of any outside changes to the directory password, these two password could go out of sync.
Linked systems: When activating accounts on linked systems, i.e. when a specific group is activated on the dashboard, the KeyHub password will be used. After activating a group, this password is supplied to the linked system and to log on to applications that are connected to that linked system, the KeyHub password should be used. If the option for rotating password is enabled, the KeyHub password is replaced by the temporary password and the temporary password is to be used to log on to a linked system.

With the link Setup passwords these passwords and their configuration can be changed. The link navigates to a three-step wizard which guides the user through choosing a secure password and the right settings for synchronisation. The first step of this wizard is to enter the current password for verification purposes. The directory password is expected here.

Depending on the specific directory the steps in this wizard could differ. For example for accounts from an external directory the current password is not requested as it is not possible to synchronise the password with the external directory.

Figure 65. Password usage step 1

During the second step the vault of the user will be opened. If the user does not have a vault yey, or the password of the vault matches the directory password, no action is required from the user. When Topicus KeyHub requests a password during this step, the KeyHub password is to be supplied.

Figure 66. Password usage stap 2

During the final step the changes are applied.

If anything is unclear about the various password options, it is recommended to contact one of the administrators for help.

Figure 67. Password usage step 3

Synchronize with directory: The password of the user within the directory is synchronised with the KeyHub password. This results in matching passwords which removes any ambiguity when using passwords. The disadvantage of this option is that the new password is also set as new password in the directory. Potentially this means that the user’s password for e-mail will be changed as well.
Choose a new password: Depending on the length of the current password, this option could be mandatory. The password that can be chosen with this option is the KeyHub password. When 'synchronize with directory' is enabled, this means that the new password will be set as the directory password as well. After saving this password the vaults of the user will be encrypted with this password as well. And if the user does not have the rotating password setting enabled, this password will also be used for linked systems.
Use rotating password: Normally the password with which linked systems are provisioned will be the KeyHub password. This means however that when this password is compromised, criminals can use this password to log on to systems after the user activated the account on the system. By choosing the rotating password option, this is no longer a thread as the password will change on a daily basis. This "password of the day" can be accessed very quickly from either the submenu on the lower left bottom of the screen or the upper right corner of the screen. With this option enabled, the rotating password is used for all linked systems and the KeyHub password is only used for unlocking the vaults in Topicus KeyHub.
Logout all sessions: This option is only visible when picking a new password and will log out all other sessions for this account after changing the password. The current session will stay logged in, but this will log the user out on all other devices or browsers, requiring them to log in again with the new password. This is generally advisable during a password change for security reasons, and this option is therefore turned on by default.

9.1.2. 2FA

Every user of Topicus KeyHub is required to have two-factor-authentication (2FA) enabled. For this, users can use either a security key or a smartphone with a specific app that supports the TOTP-protocol. Any FIDO2-compatible security key should work. For TOTP, the Topicus KeyHub-app is recommended as this will enable push notifications. With these notifications a user only has to click on Yes or No in order to log on, instead of entering the 6-digit number manually. Alternatives to the Topicus KeyHub app are Google Authenticator, Duo Mobile or Microsoft Authenticator.

Security key

After clicking on the link to add a new security key, KeyHub shows a popup and automatically tries to connect to a compatible security key. The browser will likely show a notification to this effect. The user simply has to activate their security key in the normal way to confirm they want to link it to KeyHub. KeyHub will automatically save the registered security key.

Users can add more than one security key, for example one for at the office and one for at home. It’s also possible to combine one or more security keys with a TOTP-based 2FA app.

Figure 68. Overview security keys

From this screen it is also possible to remove a security key from the account.

By default, KeyHub generates a name for the security key. Users may wish to update the name of the security key to something recognizable.

Figure 69. Edit security key

2FA app

To (re)configure TOTP-based 2FA ,a QR-code is displayed which has to be scanned by the app on the smartphone.

Figure 70. Setup 2FA

Topicus KeyHub-app

After scanning the QR-code with the Topicus KeyHub app, the screen will display the smartphone type. If this type matches the smartphone of the user, the button Activate activates 2FA. Every time the 2FA-code is required to log on to Topicus KeyHub, a push notification will be send to the smartphone.

The Topicus KeyHub-app requires an internet connection to setup and receive push notifications. After activating the app, it offers the possibility of generating a 6-digit code as well for when no internet connection is available.

Alternative apps

If an alternative app is used, scanning the QR-code will add Topicus KeyHub as an account to that app. To finalize the connection, the 6-digit verification code has to be provided to Topicus KeyHub. After Activate the 2FA will be active and every time Topicus KeyHub requests the 2FA-key, the 6-digit code has to be provided.

Lost or broken devices

It happens that smartphones or security keys get lost, break or turn unusable in any way. In these cases a user may no longer be able to log on to Topicus KeyHub.

If the user has more than one registered 2FA method (ie, multiple security keys, or at least one security key and a TOTP app) they can simply remove the one that has become unusable. However, a user can never remove their last 2FA method.

In cases where the user is unable to use any already-registered 2FA method they can request a full reset of all their 2FA methods. When the user is still logged in, there is a link under Profile to reset 2FA.

Figure 71. Reset 2FA

To reset 2FA the user has to enter a reason and the request will then be evaluated by the KeyHub administrators. If the request is granted, the user will receive an email.

When acquiring a new smartphone while the user still possesses the old smartphone, the user can reconfigure 2FA to his/her new smartphone him/herself. With the link reconfigure app the user will enter a wizard to support this process. The old smartphone is required for this step.

9.1.3. Linked systems

On the right side of the Account tab an overview is presented of all user accounts on the various linked systems. The information provided can differ between different types of systems.

9.1.4. Change language

Topicus KeyHub supports English, Dutch and German and with the link Change language the preferred language can be chosen.

Figure 72. Change language

9.1.5. Public key for SSH

For users who use SSH on a regular basis, for example to log on to Linux-based systems, it is recommended to configure the SSH-key in Topicus KeyHub. This SSH-key will be automatically provisioned to accounts on linked systems which enables logging in to those systems using the SSH-key. Copy and paste the contents of the public key-file in the corresponding input area. The value should start with ssh-rsa and end with the e-mail address.

Figure 73. Public key for SSH

Generate SSH-key on Windows

On Windows PuTTYgen can be used to generate an SSH-key. Enter the e-mail address at the Key comment and choose a strong passphrase. Select SSH-2 RSA1 with a lenght of 4096 bits. After generating the public/private key-pair, the private-key can be secured and the public-key can be copied from the upper area. Paste the public-key in the input area in Topicus KeyHub and save. In order to use the SSH-key with PuTTY, either an SSH-session can be selected or Pageant can be used.

Generating an SSH-key on Linux and MacOS

With the following command an SSH-key can be generated on Linux or MacOS"

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

After following the instructions of ssh-keygen a public/private key-pair will be stored at the selected location. The contents of the file ending with .pub are to be pasted in the input area in Topicus KeyHub

9.1.6. Browser extension

Topicus KeyHub has a browser extension which can be used to apply passwords directly from the browser. There are extensions for Mozilla Firefox, Google Chrome and Microsoft Edge. To install a browser extension go to the webstore for Google Chrome, Mozilla Firefox or Microsoft Edge. After installing the browser extension the connection between Topicus KeyHub and the extension has to be established by clicking on the corresponding link on the Profile-page in Topicus KeyHub.

9.2. Active sessions

Topicus KeyHub sessions are valid for two weeks, whether or not they are actually used. Although active, Topicus KeyHub requests the password of the user every 4 hours and the 2FA-code every week. Sessions are among other things bound to the ip-address of the user. Switching ip-address means a new session and Topicus KeyHub will asks for both the password and the 2FA.

The tab sessions provides an overview of all active sessions. For each session the browser agent, the date and the ip-address is displayed, in case these are available. Any session can be disabled on this page in order to terminate any suspicious activities. With the Logout all button every session except for the current one will be logged out.

Figure 74. Sessions

9.3. Applications with consent

When using Single Sign-On, Topicus KeyHub will ask the user for consent in order to share information from Topicus KeyHub to the SSO-application.

Every application any consent is granted to, is displayed under applications. The scope of the consent as well as which application is concerns is shown. Consent can be revoked as well. After revoking consent the application will ask the user for consent again if the user wants to use Single Sign-On.

Figure 75. Applications

10. Four eyes principle

Topicus KeyHub prevents a single person to obtain full access control to all systems and information within an organisation. The principle of decentralised authorisation is key: access rights are managed in a decentralised manner, by managers of a specific group. Sometimes however, some centralized management is required. The risks this poses is that these centralized administrators (Topicus KeyHub-users who are a member of the group KeyHub-Administrators) can obtain complete access. To prevent this Topicus KeyHub applies a four eyes principe. This principle means that any user can propose a specific action or event, and another user has to agree before this event or action can be carried out.

Figure 76. Pending request as requester

A submitted request is displayed on the dashboard of the requester. This shows the subject, reason and the users who are to verify the request. The requester can revoke the request when it is no longer required. Once a request is revoked, it will no longer be visible on the dashboard. If a request have been declined, the request and the reason of the decline will remain visible on the dashboard for a couple of days.

Figure 77. Pending request as processor

Every administrator or manager who can approve or declined a specific request will see this request on the dashboard. The buttons Approve or Decline act appropriately. After selecting one of these options, a reason can be entered in order to provide feedback to the requester or for audit trail purposes.

10.1. Types of requests

There are various types of requests within Topicus KeyHub. These various requests will be discussed below.

10.1.1. Join group

A user wants access to the group and possibly associated vault.

Submitted by: Any user within KeyHub with an active account that is not yet a member of the group.
Handled by: A manager of the relevant group.
After accepting: The user has been added to the group and immediately has access to all applications of the group and the vault.
Options when accepting: The user can immediately be made manager of the group and/or an end date can be set for the membership.

10.1.2. Join vault

A member of the group wants to (re)gain access to the group’s vault. Members of a group can lose access to the vault when resetting their password.

Submitted by: A member of the group.
Handled by: A manager of the group.
After accepting: The user will immediately have access to the group’s vault.

10.1.3. Extended access

A member of the group wants to activate the group for a longer period of time.

Submitted by: A member of the group.
Handled by: A manager of the group.
After accepting: The end time of activation of the group is set to the selected day.
Submission options: The end date for the activation.

10.1.4. Activation request

A member of group A wants to activate this group and activation is authorised by group B.

Submitted by: A member of group A.
Handled by: A member, not just managers, of group B.
After accepting: The member of group A can activate the group with the set period as the latest end time.
Options when accepting: A deadline within which the group can be activated. Adjustable between 1 hour and 2 weeks.

10.1.5. Update group membership

A manager of group A wants to add a user or update the group membership and group membership management is authorised by group B.

Submitted by: A manager from group A.
Handled by: A member, not just managers, of group B.
After accepting: The user is added to group A or the membership properties are updated.
Submission options: The user can be made manager of the group and/or an end date for the membership can be specified.

10.1.6. Review Group Audit

A manager of group A wants to have an audit reviewed by group B.

Submitted by: A manager from group A.
Handled by: A member, not just managers, of group B.
After accepting: The audit is made final and the proposed changes are applied.

10.1.7. Setup authorisation

A manager of group A wants to setup or stop additional authorisation on group B. Additional authorisation can be requested for group activation, membership management or performing audits.

Submitted by: A manager from group A.
Handled by: A manager from group B.
After accepting: The additional authorisation by group A has been setup or stopped for group B.

10.1.8. Setup nested group

A manager of group A wants to nest group B within group A, or remove this nesting.

Submitted by: A manager from group A.
Handled by: A manager from group B.
After accepting: Group B is nested within group A, or the nesting has been removed.
Submission options: Existing group memberships can be retained, converted or removed.

10.1.9. Grant permission

An administrator of an OAuth2 client wants to grant a permission to the application.

Submitted by

A member of the OAuth2 client technical administration group.

Handled by

A manager of the selected group, if selection of a group is required upon submission of the request.
A manager of the group with ownership of the selected linked system, if selection of a linked system is required upon submission of the request.
A member of the KeyHub administrators, if no selection for a group or linked system is required upon submission of the request.

After accepting

The OAuth2 client immediately gets the extra permissions.

Submission options

The type of permission. Depending on the permission, a group or a linked system.

10.1.10. Access to an application

Access for group A to an application owned by group B is requested.

Submitted by: A member of the group with technical administration of the application.
Handled by: A manager from group B.
After accepting: The members of group A immediately get access to the application.
Note: The request is automatically accepted if the user submitting the request is manager of group B.

10.1.11. Create a group on system

A member of a group with technical administration wants to create a group on system.

Submitted by: A member of a group with technical administration.
Handled by: A group manager with responsibility for the chosen linked system.
After accepting: The group on system has been created with the requesting group as owner.
Note: The request is automatically accepted if the user submitting the request is also a member of the content administrators group for the linked system.

10.1.12. Request access to a group on system

Access for group A to a group on system owned by group B is requested.

Submitted by: A manager of group A.
Handled by: A member of the content administrators group for the linked system.
After accepting: A request is sent to the managers of group B to provide access to the group on system to group A.
Note: The request is automatically accepted if the user submitting the request is also a member of the content administrators group for the linked system.

10.1.13. Access to a group on system

Access for group A to a group on system owned by group B is requested.

Submitted by: A member of the group with content administration of system.
Handled by: A manager from group B.
After accepting: The members of group A immediately get access to the group on system.
Note: This request is automatically generated upon approval of the above request. The request is automatically accepted if the user submitting the request is also a manager of group B.

10.1.14. Transfer ownership, technical administration or content administration

The ownership or technical administration of an application, linked system, group on system, service account, access profile or organisational unit, or content administration of a linked system, is transferred to another group.

Submitted by: A manager of the group with ownership.
Handled by: A manager of the selected group.
After accepting: The ownership or administration is immediately transferred to the selected group.

10.1.15. Create service account

A member of a group with technical administration wants to create a service account.

Submitted by: A member of a group with technical administration.
Handled by: A member of the content administrators group for the chosen linked system.
After accepting: The service account has been created inactive.
Submission options: The user name of the service account and the linked system on which it should be created.

10.1.16. Give service account access to a group on the linked system

A member of a group with technical administration of a service account wants to give it access to a group on the linked system.

Submitted by: A member of the technical administration group of the service account.
Handled by: A member of the content administrators group for the linked system.
After accepting: The service account will be added to the group on the linked system.
Submission options: A request is sent to the managers of group B to provide access to the group on system to the service account.
Note: The request is automatically accepted if the user submitting the request is also a member of the content administrators group for the linked system.

10.1.17. Link a group on the linked system to a service account

A member of a group with technical administration of a service account wants to give it access to a group on the linked system.

Submitted by: A member of the content administrators group for the linked system.
Handled by: A group manager with ownership for the chosen group on the linked system.
After accepting: The service account will be added to the group on the linked system.
Submission options: The group on the linked system that the service account should be given access to.
Note: The request is automatically accepted if the user submitting the request is the manager of the group with ownership for the group on the linked system.

10.1.18. Create a namespace

A member of a group with technical administration wants to create a namespace.

Submitted by: A member of a group with technical administration.
Handled by: A member of the technical administration group of the chosen base system.
After accepting: The namespace has been created with the requesting group as content administrators and owner.
Submission options: The name of the namespace
Options when accepting: The RDN for groups and for service accounts of the new namespace.

10.1.19. Delete a linked system

Another user wants to delete a linked system.

Submitted by: A member of the group with the technical administration of the linked system.
Handled by: A manager of the group with ownership of the linked system.
After accepting: The linked system and all related data are deleted.

10.1.20. Create a new group

A user wants to create a new group.

Submitted by: Any user within KeyHub with an active account.
Handled by: A member of the group configured under settings or a KeyHub administrator if unset.
After accepting: The group has been created and the user who submitted the request is the manager of the group.
Note: The request is automatically accepted if the user submitting the request is a KeyHub administrator.

10.1.21. Enable technical administration or access profile administration

A group manager wants to have technical administration or access profile administration enabled on the group.

Submitted by: A manager of the group.
Handled by: A member of the group configured under settings or a KeyHub administrator if unset.
After accepting: Technical administration or access profile administration is enabled on the group.

10.1.22. Delete a group

A manager of a group wants to delete the group.

Submitted by: A manager of the group.
Handled by: A member of the group configured under settings or a KeyHub administrator if unset.
After accepting: The group and all related data are deleted.

10.1.23. Add manager to group

Another KeyHub administrator wants to make a user manager of a group without permission from a manager within this group.

Submitted by: A KeyHub administrator.
Handled by: Another KeyHub administrator.
After accepting: The user is the manager of the group. If the user was not yet a member, it will be added. The user will not be able to access the vault if he did not already have access to it.
Note: The request is automatically accepted if the submitting user is the only KeyHub administrator besides the maintenance user keyhub.

10.1.24. Approve internal account

Another KeyHub administrator wants to add a new user to an internal directory.

Submitted by: A KeyHub administrator.
Handled by: Another KeyHub administrator.
After accepting: The user has been created in the internal directory. The user must still activate the account by means of the activation link in the email.
Note: The request is automatically accepted if the submitting user is the only KeyHub administrator besides the maintenance user keyhub.

10.1.25. Recover password

A user has lost the Topicus KeyHub password and wants to regain access with a new password.

Submitted by

Any user within KeyHub with an active account.

Handled by

Users from the KeyHub-defined recovery group:

The members of the helpdesk group, if configured.
The first 10 managers of groups commonly used by the user.
If not at least 5 managers are found in step 2, members of the group configured under settings, or KeyHub administrators if unset.

After accepting

The user can restore access to the account by entering the new password.

Note

This request must be approved by at least 2 users.

10.1.26. Disable 2FA

A user can no longer log in with 2FA and wants this disabled.

Submitted by

Any user within KeyHub with an active account.

Handled by

Users from the KeyHub-defined recovery group:

The members of the helpdesk group, if configured.
The first 10 managers of groups commonly used by the user.
If not at least 5 managers are found in step 2, members of the group configured under settings, or KeyHub administrators if unset.

After accepting

2FA for the user is disabled. The user must reconfigure 2FA himself in order to continue to use all parts of Topicus KeyHub that require 2FA.

10.1.27. Remove administration permissions

A KeyHub administrator wants to remove someone from the KeyHub Administrators group.

Submitted by: A KeyHub administrator.
Handled by: Another KeyHub administrator.
After accepting: The selected user has been removed from the KeyHub administrators group.

10.1.28. Remove an organisational unit

A KeyHub administrator wants to remove an organisational unit.

Submitted by: A KeyHub administrator.
Handled by: A manager of the group with ownership of the organisational unit.
After accepting: The organisational unit has been removed and all associated elements have been moved to the parent organisational unit.

11. Auditor role

The auditor role is configurable per organisational unit, with it being assigned to the KeyHub Administrators group by default. When this role is assigned to a group, that group will have access to the groups and users of the organisational unit and all organisational units below it. The auditor role is chosen through the settings of the organisational unit. If there is only one organisational unit, and the KeyHub Administrators are owners of this organisational unit, it is also possible to configure the role via the central settings.

If the role has been transferred to a different group and said group gets deleted, then the role will be transferred back to the KeyHub Administrators.

Members of the group with the auditor role get access to two dashboards, the groups dashboard and the accounts dashboard.

11.1. Groups dashboard

This dashboard provides an overview of all groups in Topicus KeyHub within the organisational unit and all underlying organisational units. For each group it is shown how many managers and members it has, as well as information about audits performed, audit deadlines and vault records. By clicking on the classification, the classification of the group can be changed.

It is possible to generate an extensive export of all groups, filtered by the current selection criteria.

Figure 78. Auditor groups dashboard

11.2. Group Details

By clicking on a group, more information about the group can be requested. All audits and the complete audit log of the group can be viewed. It is also possible to explicitly request an audit for the group. Managers of the group will receive this request in the email and as a notification on the dashboard. For more information about audits see the section about auditing groups.

Figure 79. Auditor group details

11.3. Classifications

Groups can be divided into classifications via the auditor dashboard. By clicking on the classification on the dashboard, the classification of the group can be changed. These classifications can be managed via the menu option Classifications.

The following fields can be set for a group classification:

UUID: A unique identifier for the group classification within Topicus KeyHub.
Name: The name of the group rating as displayed to users throughout the application.
Maximum audit interval: Indicate the maximum time allowed between audits for the periodic audit of the groups with this classification. If, according to the audit schedule, no audit is planned within this audit interval, the group managers are notified. Via this notification, the audit schedule can be automatically adjusted or navigated to the editing of the group.
Mandatory audit months: Specify that groups with this classification must always perform an audit in the selected months. If, according to the audit schedule, no audit is planned in the selected months, the group managers will be notified. Via this notification, the audit schedule can be automatically adjusted or navigated to the editing of the group.
Require "Record audit trail": Specify that the option "Record audit trail" should be activated for groups with this classification. If this option is not activated, the group managers will be notified. Via this notification the option can be activated directly or navigated to the editing of the group.
Require "Rotating password required": Specify that the option "Rotating password required" should be activated for groups with this classification. If this option is not activated, the group managers will be notified. Via this notification the option can be activated directly or navigated to the editing of the group.
Require "Activation required for vault access": Specify that the option "Activation required for vault access" should be activated for groups with this classification. If this option is not activated, the group managers will be notified. Via this notification the option can be activated directly or navigated to the editing of the group.
Require "Authorising group for activation": Specify that a group should be configured for "Authorising group for activation" for groups with this classification.
Require "Authorising group for membership": Specify that a group should be configured for "Authorising group for membership" for groups with this classification.
Require "Group with delegated privileges": Specify that a group should be configured for "Group with delegated privileges" for groups with this classification.
Require "Authorising group for audits": Specify that a group should be configured for "Authorising group for audits" for groups with this classification.
Minimum number of managers: Specify a minimum number of managers, at least 1, that a group with this classification must have. When a group has fewer managers than set here, the group managers are notified. Via this notification the user can navigate to the editing of the group to select new managers.
Description: A more detailed description of the group classification.

Figure 80. A group classification

11.4. Accounts Dashboard

This dashboard provides an overview of all accounts in Topicus KeyHub within the organisational unit and all underlying organisational units. For each account, it is shown, among other things, which directory it comes from, when it was last active and what 2FA-options it has configured.

It is possible to generate an extensive export of all accounts, filtered by the current selection criteria.

Figure 81. Auditor accounts dashboard

11.5. Account Details

After clicking on an account, it will be shown in more detail. All groups it belongs to will be shown, along with its role and the last date it used this group in any way to access something via KeyHub.

Figure 82. Auditor account details

11.6. Service accounts Dashboard

This dashboard provides an overview of all service accounts in Topicus KeyHub within the organisational unit and all underlying organisational units. For each service account is shown whether it is active, its password rotation mode and what group is administering it.

It is possible to generate an extensive export of all service accounts, filtered by the current selection criteria.

Figure 83. Auditor service accounts dashboard

11.7. Service account Details

After clicking on a service account, it will be shown in more detail. The groups on system it has access to will be shown, along with the last relevant audit records.

Figure 84. Auditor service account details

Administration

12. User accounts

An account is necessary to use Topicus KeyHub. The user accounts overview page shows a list of all registered accounts to KeyHub administrators. Besides common information about an account, the date of last usage, whether 2FA is enabled and whether the account is still valid in the corresponding directory is shown. Click on the account in order to see all details.

Figure 85. User accounts overview

12.1. Details

The properties of an account are read-only because these are copied from the directory where the account originates. The exception to this are accounts from internal directories. These properties can be found at account details. Some status properties can be edited:

Username: The username by which the account is known in Topicus KeyHub.
Enabled: Enable or disable the account. A disabled account cannot be used to log on to Topicus KeyHub.
License role: Switch the account’s license role. Business accounts have fewer capabilities than Pro accounts. KeyHub administrators can not be Business accounts.
Directory: The directory in which the account resides.
Identifier in directory: The primary identifier of the account in the directory. When this identifier changes or the account is moved to a different directory, a re-registration can be triggered. See below for more information.
Valid in directory: Shows whether the account is valid in the corresponding directory. This status is updated every 24 hours and can be updated manually by clicking on the link. Accounts that are not valid in the directory cannot be used to log on to Topicus KeyHub.
Two factor status: Shows whether 2FA is enabled for the account. Following the link disables 2FA for this account and requires a user to reconfigure 2FA.
Password and 2FA recovery status: Displays if the account has an open request for password or 2FA reset. If this is the case, this request can be rejected.
May request groups: By default every user can request access to groups. It is possible however to disable this possibility, for example for contractors and/or other accounts that require minimum access rights. Group managers should add these accounts to specific groups in order to provide access.
E-mail: The e-mail address for the account, taken from the directory.

Figure 86. Account details

12.2. Renaming or moving an account

If the identifier of an account is changed in the directory, the user can no longer log in. The same will happen when an account is moved to a different directory. To rename an account within a directory, or even move it to another directory entirely, the 'Rename/move' link is used. After marking the account for renaming, the user must reactivate the account at logon. Hereby the user is asked for his or her Topicus KeyHub password and 2FA (if enabled). After this, the user must choose a directory again and authenticate against this directory. If allowed for the directory, the user can choose a custom username, otherwise the username is taken from the directory. After re-registration, the user can log in again with the new authentication.

It is possible that the user gets a new username. This new username will also be used on linked systems.

12.3. Attributes

Any stored attributes can be viewed via the menu item Attributes. At the directory attributes that must be stored with an account can be configured.

Figure 87. Account attributes

12.4. Audit log

The menu-item Audit log leads to the audit log of the corresponding account. This audit log shows all records the user would see themselve. This means that besides all personal records, all records regarding the account itself are shown as well. Results can be filtered by using the filter at the top of the screen.

Figure 88. Audit log for a specific account

12.5. Clean up accounts

When employees leave an organisation, unused accounts will remain in Topicus KeyHub. These accounts can no longer be used once the account in the directory becomes invalid, but will continue to exist in Topicus KeyHub. KeyHub administrators can clean up these accounts in bulk. A search for accounts with different statuses, from different directories or that have been unused for a certain time, can be performed. It is also possible to manually enter the usernames of the accounts, or to copy this as a CVS export from another program. The searched or entered accounts can then be removed with a single click. If it is not possible or permitted to delete certain accounts, this will be stated with the specific accounts.

Topicus KeyHub checks the status of accounts within directories that support this (Active Directory and LDAP) once a day. This process runs around 6 o’clock in the morning. It is also possible to manually update the status of an account.

With this functionality it is possible to delete many accounts very quickly. Always review the list of accounts to deleted before actually deleting them. Deleting accounts cannot be undone.

Figure 89. To clean up accounts

12.6. Bulk editing accounts

On the bulk edit page accounts can be switched to a different license rol or be renamed in bulk. For example, all accounts in a specific group can be changed to a 'Pro' account in one go.

Accounts in the KeyHub administrator group will not be shown.

Figure 90. Bulk editing accounts

13. Service accounts

Service accounts are non-personal accounts that can be used for system processes. These accounts are managed by a group and created on a linked system. The service accounts overview page shows a list of all registered service accounts to KeyHub administrators.

Figure 91. Service accounts overview

13.1. Details

The following properties can be set on a service account:

Enabled: The service account will only be created on the linked system if it is enabled.
UUID: A unique identifier for the service account within KeyHub.
Name: The name of the service account as it is shown to users.
Technical administrators group: Members of this group perform the technical administration of this service account. All members can modify or delete the service account.
Linked system: The linked system on which the service account is created.
Username: The username of the service account on the linked system. A configured prefix will be prepended to this.
Password rotation: Indicates how to manage the service account’s password. Passwords for service accounts are automatically generated. It is possible to automatically rotate this daily, placing the password in the group’s vault. With manual rotation, you can choose whether or not to place the password in the group vault.
Password: The service account’s password. This password will only be displayed after a manual rotation.
SSH public key: An optional SSH public key that is added to the service account, if the linked system supports this.
Description: A description of the service account. This description is also set on the linked system.

Figure 92. Service account

13.2. Groups on system

A service account can be added to one or more groups on the linked system where the service account resides. Through these groups, the service account can be granted permissions on the system itself or to underlying applications. Access to a group must be requested and is handled by the group with ownership for the group on the linked system.

Figure 93. Groups for a service account

14. Groups

With Topicus KeyHub access rights are distributed via groups. All available groups are shown on the group overview page.

The table shows the name, description and the summary of each group. The various elements in this table are clickable and lead to the corresponding page of the group. Group are categorised automatically according to the first word of the group name.

Figure 94. Group overview

14.1. Details

The properties of a group are managed via the details page. Only group managers can modify these properties. See manage group for an explanation of the displayed fields.

Figure 95. Group details

14.2. Accounts

The menu-item Accounts shows all members of the group. A KeyHub administrator is not responsible for managing group memberships, this is task of the group managers. KeyHub administrators can assign a new group manager to a group (see Four eyes principle). This is especially useful when a group has no group managers anymore.

Figure 96. Group members

14.3. Applications

Each group can grant access rights to Single Sign-On to specific applications. Setting up a SSO-connection to an application is done by the technical management group of the application and has to be approved by a manager of the responsible group of the application.

Figure 97. Applications of a group

14.4. Group provisioning

Each group can assign access to certain groups on systems of linked systems. These groups can be activated on the dashboard. Setting up a new group on system to a linked system is done by the technical management group of the linked system. This request has to be approved by a manager of the responsible group of the group on system.

Figure 98. Groups on systems

15. Directories

A Topicus KeyHub account always originates from a directory. There are several types of directories:

Maintenance: Every Topicus KeyHub-installation has its own maintenance directory. This directory consists of exactly one account: the keyhub-account. The keyhub-account is a unique account and can only be enabled by (re)starting Topicus KeyHub in maintenance mode.
LDAP: The LDAP-directory is used to authenticate users against Microsoft Active Directory, OpenLDAP or any other LDAP v3-compliant directory. Users from the LDAP-directory can register their own Topicus KeyHub account from the login-page (certain rules apply). By connecting Topicus KeyHub to a corporate directory, account management can be executed from a central department within the organisation or can be divided into multiple departments like divisions.
OIDC: The OpenID Connect-directory (OIDC for short) is used to authenticate a Topicus KeyHub account against an OpenID Provider (OP). Topicus KeyHun is connected to the OP using Single Sign-On. Users can register their own Topicus KeyHub-accounts from the login-page. Account management is outsourced to the OP.
Internal: For each internal directory, Topicus KeyHub manages the accounts. These accounts are especially useful for sharing access to users who do not exist in the corporate directory. An account in an internal directory has to be created by a KeyHub administrator and before activating the account another administrator has to approve the create-account-request. After approval an account can be activated following the link in the registration e-mail.

Figure 99. Directory overview

15.1. LDAP directory

Using an LDAP-directory Topicus KeyHub authenticates against an LDAP v3 compliant directory. Examples of such directories are Microsoft Active Directory or OpenLDAP. Using their LDAP-account, users can register their Topicus KeyHub account from the login-page and the relevant data from the LDAP-account is copied to the Topicus KeyHub account. The LDAP-account is validated every time a users logs on to Topicus KeyHub. If the LDAP-account is invalid, authentication is not allowed and users cannot log in to Topicus KeyHub anymore.

An LDAP-directory consists of the following properties:

Active: Users can only authenticate when the directory is active. Deactivating the directory ensure no-one from this directory is able to login to Topicus KeyHub anymore.
UUID: The unique identifier of this directory within Topicus KeyHub.
Base organisational unit: Users from the directory are always members of this organisational unit and can only be member of organisational units under this unit. This value can only be changed for directories that do not contain any users.
Name: The name of the directory as presented to users throughout Topicus KeyHub. Choose a familiar name as new users should be able to recognise this name when registering their Topicus KeyHub account.
Dialect: Although LDAP v3 is standardized, there are subtle differences in the dialect used by different systems. If the specific directory is not listed, choose OpenLDAP.
Primary host: The hostname of the primary LDAP server. When using a (highly recommended) secure connection, an IP-address cannot be used.
Failover host: The hostname of the optional secondary LDAP server. If left blank, Topicus KeyHub cannot use another server when communication with the primary server fails. The failover host is only used when communication with the primary host fails.
Port: The port number of the LDAP server. The default port is 389. When using LDAPS port number 636 is possible. For every port other than 636 Topicus KeyHub will use StartTLS when using a secure connection.
TLS: User passwords and secrets are sent through the connection with the LDAP-server. Securing the connection is therefore highly recommended. See the chapter about certificates for more information.
Trusted certificate: This certificate determines which certificates can be trusted when setting up a secure connection. If left blank, the default Java-truststore will be used. See the chapter about certificates for more information.
Trusted certificate for failover: The same as the above, but for the failover host.
Bind DN: The complete DN to bind to when applying search queries to accounts within the directory. It is highly recommended to use a read-only LDAP account.
Bind password: The password to create the bind
Client certificate: When using client authentication Bind DN and Bind password are replaced by a certificate which Topicus KeyHub uses to authenticate itself against the directory. This is the most secure way of setting up a connection to the directory.
Base DN: The DN in the directory to search for users
Search filter: The LDAP filter to which users should comply to in order to be used. This filter should contain at least one term with {}, where the username is inserted. The filter should only return active accounts. For a Microsoft Active Directory a search filter is similar to:

(&(sAMAccountName={})
  (objectClass=user)
  (!(useraccountcontrol:1.2.840.113556.1.4.803:=2)))

Password recovery in the directory: On password recovery, write the password back in the directory. The user with the bind DN must have sufficient rights to do this. When using e-mail, be aware that a user who has forgotten their password may also have lost access to e-mail. If 2FA is used for re-authentication, a user will not be able to perform password recovery if 2FA is not enabled on the account (or if the 2FA codes are lost).
Helpdesk group: Members of this group process password recovery and 2FA reset requests for all users from this directory. If no group is configured, these requests will be processed by managers of groups the user is member of or the KeyHub Administrators.

Changes to this property will take effect as soon as users log in again. For users who have not yet logged in after a change, the old settings will remain in effect.

Restrict 2FA setup: If this option is enabled, it is not possible for a user to modify the 2FA configuration. 2FA can only be setup at registration or after it has been reset by a KeyHub Administrator or member of the helpdesk group.
Username modifiable: Whether or not users can edit their username when registering their Topicus KeyHub account.
Default directory: The default directory to look for accounts that not exist yet. If the credentials of the account exist in this directory and are valid, registration is started automatically.
Rotating password: Indicates whether or not new users get a rotating password by default upon registration. When Always on the user can no longer choose and the option will always be enabled upon registration. Existing users must first enable the option before a group can be activated.
Attributes: A list of attributes that are read from the directory and stored with the account. These attributes can then be used in custom attribute scripts. The names of the attributes are separated by spaces.

Figure 100. LDAP directory

15.2. OIDC directory

With an OIDC directory Topicus KeyHub authenticates against an OpenID Connect Provide (OP). Users register their own account and the relevant information is copied to Topicus KeyHub. When logging on to Topicus KeyHub, a Single Sign-On connection with the OP is set up. If a user account is disabled or deleted in the OP, authentication in Topicus KeyHub is no longer possible.

The following fields van be

An OIDC-directory consists of the following properties:

Active: Users can only authenticate when the directory is active. Deactivating the directory ensures no-one from this directory is able to login to Topicus KeyHub anymore.
UUID: The unique identifier of this directory within Topicus KeyHub.
Base organisational unit: Users from the directory are always members of this organisational unit and can only be member of organisational units under this unit. This value can only be changed for directories that do not contain any users.
Name: The name of the directory as presented to users throughout Topicus KeyHub. Choose a familiar name as new users should be able to recognise this name when registering their Topicus KeyHub account.
Supplier: When using Google or Microsoft Azure Active Directory this can be entered here. Choosing the right supplier enhances the compatibility, offers additional options and eases configuration.
OIDC Issuer identifier: An OIDC Issuer identifier is a case-sensitive https-URL. This consists of at least a schema and host and an optional port number and/or path. The URL cannot contain a query or fragment. Topicus KeyHub uses OpenID Connect Discovery to configure the OIDC-directory. The OpenID Provider has to support this. The discovery information can be found by adding /.well-known/openid-configuration to the Issuer.
Client identifier: The identifier supplied by the OpenID Provider to which Topicus KeyHub is known at the OP.
Client secret: The secret belonging to the above identifier.
Domain restrictions: Available when choosing Google or Microsoft Azure Active Directory. This option forces that only accounts from within a certain domain are able to register.
Logout URL: If the chosen OpenID Connect Provider does not advertise end_session_endpoint via the discovery endpoint, a custom URL can be specified here for logging out. It is also possible to overwrite the advertised URL via this field.
Enforces 2FA: If the OpenID Provider enforces 2FA then this option can be enabled. When checked Topicus KeyHub will not ask for 2FA. Only use this option when 2FA is enforces by the OP as otherwise the possibility exists that users can login to Topicus KeyHub without using 2FA.
ACR values: A space-separated list of ACR values. This is passed as acr_values to the IDP. With this the IDP can be instructed to force certain forms of authentication on the user. When the IDP returns an acr claim in the id_token it must match one of the specified values.
Send login_hint: When this option is enabled, Topicus KeyHub will send a login_hint parameter to the IDP. This hint can help the IDP automatically select the correct account. Disable this option if the IDP does not understand the specified values and therefore selects incorrect accounts.
Helpdesk group: Members of this group process password recovery and 2FA reset requests for all users from this directory. If no group is configured, these requests will be processed by managers of groups the user is member of or the KeyHub Administrators.

Changes to this property will take effect as soon as users log in again. For users who have not yet logged in after a change, the old settings will remain in effect.

Restrict 2FA setup: If this option is enabled, it is not possible for a user to modify the 2FA configuration. 2FA can only be setup at registration or after it has been reset by a KeyHub Administrator or member of the helpdesk group.
Username modifiable: Whether or not users can edit their username when registering their Topicus KeyHub account.
Default directory: The default directory to look for accounts that not exist yet. If the credentials of the account exist in this directory and are valid, registration is started automatically.
Rotating password: Indicates whether or not new users get a rotating password by default upon registration. When Always on the user can no longer choose and the option will always be enabled upon registration. Existing users must first enable the option before a group can be activated.
Attributes: A list of attributes that are read from the directory and stored with the account. These attributes can then be used in custom attribute scripts. The names of the attributes are separated by spaces.

Figure 101. OIDC directory

At the OpenID Provider end most likely a 'callback-' or 'redirection-URI' should be specified. This should be: HOSTNAME/login/oidc. If multiple profiles can be chosen, 'web application' or 'confidential client' should be specified.

15.3. Internal directory

With an internal directory all account management is executed within Topicus KeyHub. The primary use of an internal directory is to enable users who do not have an account in the LDAP-directories to login to Topicus KeyHub. An internal directory consists of only a few properties:

Active: Users can only authenticate when the directory is active. Deactivating the directory ensure no-one from this directory is able to login to Topicus KeyHub anymore.
UUID: The unique identifier of this directory within Topicus KeyHub.
Base organisational unit: Users from the directory are always members of this organisational unit and can only be member of organisational units under this unit. This value can only be changed for directories that do not contain any users.
Name: The name of the directory as presented to users throughout Topicus KeyHub.
Group with ownership: Managers from the chosen group are responsible for managing users in this directory. They can create, approve, edit and delete users. This responsibility is shared with the KeyHub administrators.
Helpdesk group: Members of this group process password recovery and 2FA reset requests for all users from this directory. If no group is configured, these requests will be processed by managers of groups the user is member of or the KeyHub Administrators.

Changes to this property will take effect as soon as users log in again. For users who have not yet logged in after a change, the old settings will remain in effect.

Restrict 2FA setup: If this option is enabled, it is not possible for a user to modify the 2FA configuration. 2FA can only be setup at registration or after it has been reset by a KeyHub Administrator or member of the helpdesk group.
Rotating password: Indicates whether or not new users get a rotating password by default upon registration. When Always on the user can no longer choose and the option will always be enabled upon registration. Existing users must first enable the option before a group can be activated.

Figure 102. Internal directory

15.4. Directory accounts

The account overview of a directory shows all Topicus KeyHub accounts that are registered from a directory. For LDAP-directories this is just an overview. For internal directories however, the corresponding accounts can be managed from this page.

Figure 103. Directory accounts

15.5. Internal account

An internal account is an account of an internal directory. The properties of an internal account are all required. To create an internal account the approval of another manager from the owning group is required.

After approval of a new internal account, an activation e-mail needs to be sent from the account details page. This e-mail will be sent to the corresponding e-mail address and comes with an activation code which is valid for one (1) hour. After expiration of the activation code a new activation e-mail can be sent from this page.

Figure 104. Internal account

16. Organisational units

Organisational units form a tree with the different parts of the organisation. The branches within the tree form shielded sections within the Topicus KeyHub environment. Users are associated with one or more organisational units. Only the elements within those organisational units or the parent units are accessible to the user. You can create a maximum of 5 levels of organisational units. New organisational units are always created under an existing unit.

Figure 105. Organisational units

16.1. Manage organisational units

An organisational unit has a number of properties:

Parent organisational unit: The organisational unit that is directly above this organisational unit. Each organisational unit has a parent organisational unit, except for the root element of the tree. It is not possible to change the parent.
UUID: A unique identifier for the organisational unit within KeyHub.
Name: The name of the organisational unit as displayed to users throughout the application.
Insert above: This option is only available when creating a new organisational unit. The new organisational unit will be created with the checked organisational units as child units. These organisational units will thereafter have the new organisational unit as their parent organisational unit.
Group with ownership: Managers of this group are responsible for granting access to the organisational unit. This means that managers from this group can assign users to the organisational unit, adjust settings, and processes requests about the organisational unit. Managers of this group can transfer ownership to another group.
Description: A more detailed description of the organisational unit.

Figure 106. Organisational unit

16.2. Accounts within an organisational unit

Accounts are always associated with the base organisational unit of the directory they belong to. This gives the user access to everything that belongs to that organisational unit or to a parent unit. A member of an organisational unit’s owning group can also associate an account with additional organisational units. This must be an organisational unit that falls under the base organisational unit of the directory. The accounts overview shows which accounts are associated to an organisational unit.

Figure 107. Accounts within an organisational unit

16.3. Settings for an organisational unit

Here the settings can be specified for the organisational unit and units below it if they don’t specify them themselves.

Hint for new group names: Show a hint to users when requesting new groups. This hint is shown as a placeholder in the field for the name of the new group. For example, enter the expected format of a group name here.
Approve 'Create group': Requests to create new groups are handled by the chosen group rather than the KeyHub administrators.
Approve 'Enable technical administration': Requests to enable technical administration on groups are handled by the chosen group rather than the KeyHub administrators.
Approve 'Remove group': Requests to remove groups are handled by the chosen group rather than the KeyHub administrators.
Password recovery fallback group: Password recovery requests for users with insufficient group managers are also sent to users in the chosen group rather than the KeyHub administrators.

Figure 108. Setting for an organisational unit

16.4. Moving groups to another organisational unit

Groups can be moved from one organisational unit to another. This is a request from a manager of the owning group of the 'source' organisational unit, to a manager of the owning group of the 'target' organisational unit. Both managers should also be members of both organisational units.

16.4.1. Selecting groups to move

Starting from the source organisational unit’s details page, click the 'Move groups' button to start creating a request to move one or more groups. On the next page, the groups to be moved and the target organisational unit to move them to, can be selected.

Figure 109. Select groups to move to another organisational unit

16.4.2. Additional changes during the move

Click the 'Next' button to see confirmation page with a report about the request. This will show the details of the request, and whether or not it can be executed. It will also show whether there are any additional changes for any of the moved groups.

After the move, all links between the moved groups and any other groups must still be valid. This includes links such as a service account administered by one group having access to a group on system owned by another group. If the resulting situation would not be valid, any such links will be removed.

Members of a group can only stay members if they are already linked to the target organisational unit. If not, their membership will be revoked.

Additionally, all open requests for or by the groups, or for any of their owned or administered entities, will be canceled.

Click the 'Request' button to send in the request.

Figure 110. Additional changes when moving groups to another organisational unit

16.4.3. Problems preventing the move

If there are any problems preventing the request from being executed, these will be displayed instead.

Groups fulfilling certain roles cannot be moved.

All managers of a group should be moveable, and after the move the group should still have sufficient members with vault access.

A nested groups structure should be moved in its entirety. Moving a nested group without its parent, or vice versa, is not possible.

Figure 111. Problems when trying to move groups to another organisational unit

16.4.4. Confirming the move request

Clicking the 'Approve' button for the move groups request on the dashboard, will send the user to the confirmation page. This will enable the accepting manager to review any changes or problems reported.

Clicking the 'Approve' button on this page will show a popup where the user can leave the optional feedback and finally confirm the request.

After accepting and processing the request, the provisioning will be synchronised via a background job. This means it can take a short while before any changes have been properly propagated to all linked systems.

Figure 112. Confirming the move groups request

17. Applications

Applications are used for Single Sign-On and/or server-to-server communication with Topicus KeyHub. Single Sign-On (SSO) in Topicus KeyHub is group based. This means that each SSO application is connected to a specific Topicus KeyHub group. Only members of that group can use the corresponding SSO application. Three different protocols are supported: OAuth2/OIDC, SAML v2.0 and LDAP v3.

Figure 113. Applications

17.1. OAuth 2.0/OpenID Connect application

OAuth 2.0 has been standardized since late 2012 and has, in combination with OpenID Connect, grown to the common standard for authorisation and authentication. OAuth 2.0 is divided into several RFCs where RFC 6749 and RFC 6750 are the most important. OpenID Connect is developed by the OpenID working groups and the specification is found at https://openid.net/developers/specs/. Topicus KeyHub supports the complete core specification and discovery.

To setup an OAuth 2.0 application it is highly recommended to use OpenID Connect discovery. All relevant information about setting up a SSO application is found at HOSTNAME/.well-known/openid-configuration.

The following properties can be configured for an OAuth2 application:

UUID: A unique identifier for this application within Topicus KeyHub
Name: The name of this application as presented to the users.
Launchpad tile: Show the application as a tile on the launchpad. See the chapter about the launchpad for more information.
Technical administrators group: Members of this group can perform the technical administration of this application. All members can modify or delete the application. Webhooks of this application are managed by this group as well.
Group with ownership: Managers of this group are responsible for granting access to this application. This means that managers from this group can offer SSO to this application to other groups. In other words: members of the other group are granted access to this application. Managers of this group can transfer ownership or the technical administration to another group.
Supported grant types: The OAuth 2.0 specification distinguishes several grant_types. Topicus KeyHub supports code and implicit for SSO-purposes. If users have to authenticate through Topicus KeyHub to the application, this option has to be chosen. For direct server-to-sever-communication Topicus KeyHub supports client_credentials. When using this option the application itself requests an access token without interaction of the user. The client itself can perform requests on Topicus KeyHub. An example of such an application is the Command Line Interface.

This option cannot be modified after saving this new application.

Profile: OAuth 2.0 defines a number of profiles for applications. Choose the profile that best matches the application. The profiles are described in detail below. This option is only available for code and implicit grants.
Show landing page: Displays a landing page immediately after login and before redirecting to the SSO application. With native desktop applications it is not always possible to terminate the login process properly. If when logging in the user gets stuck on the last displayed page in Topicus KeyHub, this option can be enabled. The user will then receive a clear message that the login process has been completed and that the window can be closed.
Debug mode: If this option is enabled, Topicus KeyHub’s REST API returns any errors in its entirety. This information can be useful in troubleshooting API calls. However, this information can also be used by a possible attacker to obtain in-depth information about the system’s internals. Therefore, never leave this this option enabled on a production environment.
Application URIs: The various URLs where the application is located, separated by enters. This option is only available for code and implicit grants. The hostname and path may contain one wildcard as a range of characters from the alphanumeric group [a-zA-Z0-9] or a dash. For example, {4-10} means that every URL that has 4 to 10 alphanumerical characters instead of this wildcard is accepted. Besides this, it is possible to enter a range of port numbers, like [8080-8180]. The value of the OAuth redirect_uri parameter is verified against these values.
URI to start login: The URI within the application where a third party login can be started. The OpenID Connect specification refers to this as the initiate_login_uri. This URI is used to start an IdP initiated login from Topicus KeyHub. This option is only available for code and implicit grants.
Allowed scopes: This property configures the various scopes this application may request. This minimizes the rights an application might have on the REST-API. For SSO-applications it is recommended to limit this to Profile.
Custom attributes: Any additional attributes can be defined here which can be retrieved through userinfo. The possibilities of these attributes are described in Custom attributes. This option is only available for code and implicit grants.
Claims for the id_token: A space-separated list of claims. These claims are added to the 'id_token', even if the client does not explicitly request them to be added. Some clients expect additional claims in the 'id_token' without this being part of the specification. These claims can be added via this option. It is also possible to provide custom attributes as claims in the 'id_token'.
Allowed Resource URIs: Allowed URIs for resource indicators. Topicus KeyHub can be used as authorization server for these resource servers. To request a token for another resource server, the URL of this server must be passed as the resource parameter in the authorization request. The resulting OAuth 2.0 access token will be in the format described in RFC 9068. A resource URI may contain one wildcard as a range of characters from the alphanumeric group [a-zA-Z0-9] or a dash. For example, {4-10} means that every URL that has 4 to 10 alphanumerical characters instead of this wildcard is accepted. Besides this, it is possible to enter a range of port numbers, like [8080-8180]. Access tokens for other resource servers cannot be used on the backend of Topicus KeyHub itself.
Access to accounts and structure of groups: With this option the client is granted read-access to accounts, linked systems and other clients at groups where this client is connected to. This option is only available for the client_credentials grant.
Client identifier: This unique number is generated automatically by Topicus KeyHub and is referred to by oauth_consumer_key in the specifications. This value is not a secret.
Secret: This value is used by the client to sign requests and is referred to as client secret or consumer secret. This value is to be kept secret at all times. If this value is compromised, a new secret can be generated.

Regenerating the client secret immediately invalidates the old secret which and therefore the ability to use SSO to the application.

Save secret in vault: If enabled, the client’s secret is automatically placed in the vault. When enabling on an existing client, the secret must be rotated to activate this option.

17.1.1. OAuth 2.0 application profile

The OAuth 2.0 specification describes three profiles: 'web application', 'user-agent-based application' (renamed to 'browser-based application' in OAuth 2.1) and 'native application'. These profiles are also used within Topicus KeyHub, with some extensions. The choice of a profile determines whether an application is assigned a client secret and how refresh tokens are handled.

Server-side web application: A server-side web application is an application that runs on a web server. The application keeps the tokens and secrets on the server, separate from the end user. Applications of this type are assigned a client secret and can make unlimited use of refresh tokens. Each refresh token is valid for 60 days and this period restarts when the refresh token is used.
Client-side browser application: A client-side browser application is an application that runs in the end user’s browser, usually in JavaScript. The end user is able to intercept all information passing through this application. This type of applications is not able to keep a client secret, secret, and is therefore not granted one. Due to the limited options for safely storing a refresh token, browser applications do not receive a refresh token. Access tokens are only valid for one hour. After this hour, the user must go through the OAuth 2 authentication flow again to provide the application with a new access token.
Client-side browser application (with refresh tokens): This type of application is the same as the profile described above, except that a (limited) refresh token is now provided. For some applications the need to re-authenticate every hour can be problematic and seriously degrade the user experience. For these applications, you can choose this profile. The refresh tokens provided to the application are valid for 4 hours and can be refreshed up to 12 hours after the first token is issued. After these 12 hours, the user must go through the OAuth 2 authentication flow again. Essentially, the user needs only authenticate once daily, as long as they use the application at least once every 4 hours.
Public native application: A native application which is installed directly on the end user’s device. This could be a PC or mobile phone, but also something like a smart TV. The application is distributed through a public channel, such as a store or a website. It is assumed that any client authentication credentials included in the application can be extracted. This type of applications is therefore not assigned a client secret. Since we can’t assume anything about the extent to which such an application can safely store tokens, no refresh tokens are provided.
Public native application with secure storage: This type of application is similar to the profile described above, with the addition that it can be said with reasonable certainty that tokens can be stored securely. For example, mobile phones offer the option of using a secure part of the storage to store credentials. Because the tokens are safely stored by this type of application, refresh tokens are provided. Each refresh token is valid for 60 days and this period restarts when the token is used.
Native application with secret: This type of application is again an extension of the profile described above, but now the client secret is shared via a separate channel. The application can both store the tokens and the secret securely. As with the profile above, each refresh token is valid for 60 days and this period restarts when the token is used.

Figure 114. OAuth 2.0/OIDC application

17.2. SAML v2.0 application

SAML v2.0 is an older standard from 2005 and has been standardized by OASIS. Especially enterprise applications often support SAML v2.0. Topicus KeyHub takes the role of Identity Provider (IdP), the application is a Service Provider (SP). To automatically configure the Service Provider Topicus KeyHub offers metadata through HOSTNAME/login/saml2/metadata.

The following properties can be configured for a SAML v2.0 application:

UUID: A unique identifier for this application within Topicus KeyHub
Name: The name of this application as presented to the users.
Launchpad tile: Show the application as a tile on the launchpad. See the chapter about the launchpad for more information.
Technical administrators group: Members of this group can perform the technical administration of this application. All members can modify or delete the application. Webhooks of this application are managed by this group as well.
Group with ownership: Managers of this group are responsible for granting access to this application. This means that managers from this group can offer SSO to this application to other groups. In other words: members of the other group are granted access to this application. Managers of this group can transfer ownership or the technical administration to another group.
Client identifier: The identifier of the Service Provider, sometimes referred to as Entity Identifier. This has to be an URI.
Subject format: Topicus KeyHub can deliver the subject in three formats: Primary identifier, UPN and username. With Primary identifier the subject consists of a unique number which will never change. With UPN the subject is a combination of the username and the domain, like user@domain. With Username the subject is the Topicus KeyHub-username. Which format is recommended highly depends on the Service Provider.
Custom attributes: Any additional attributes can be defined here which can be retrieved through userinfo. The possibilities of these attributes are described in Custom attributes.
IdP signing certificate: This certificate is used by Topicus KeyHub for signing the SAML2 messages.
Metadata (URL or manually): The configuration of a SAML SSO application requires SAML Metadata. Some Service Providers offer a URL, others only basic documentation. If a URL is available it is recommended to use it. Otherwise the metadata should be entered manually.

Figure 115. SAML v2.0 application

17.3. LDAP v3 application

LDAP v3 is a standard from 2006 and is the de-facto standard for retrieving information from directory services. Topicus KeyHub contains an implementation of the LDAP v3 server with which information about groups and accounts can be retrieved. To connect to the LDAP server of Topicus KeyHub, any LDAP v3 client can be used, as long as StartTLS is supported.

To use the LDAP server a certificate is required which can be configured at general settings.

The following properties can be configured for a LDAP v3 application:

UUID: A unique identifier for this application within Topicus KeyHub
Name: The name of this application as presented to the users.
Technical administrators group: Members of this group can perform the technical administration of this application. All members can modify or delete the application. Webhooks of this application are managed by this group as well. Managers of this group can transfer the technical administration to another group.
Bind DN: The identifier of the application to be used by a simple bind. This value is available after saving.
Secret: This value is used by clients for authentication with a simple bind. This value is to be kept secret at all times. If this value is compromised, a new secret can be generated.

Regenerating the client secret immediately invalidates the old secret.

Save secret in vault: If enabled, the client’s secret is automatically placed in the vault. When enabling on an existing client, the secret must be rotated to activate this option.
Client certificate: If supported by the client, it is possible to use a SASL external bind with a X509 client certificate. The client then authenticates with the private key of a predetermined certificate. The public part of the certificat is to be provided.

Figure 116. LDAP v3 application

17.4. Groups for an application

Single Sign-on with an application is only allowed for users who are member of a group which is connected to the application. This way, SSO in Topicus KeyHub is authorisation as well as authentication.

Figure 117. Grouop for an application

17.4.1. Adding a group to an application

Adding a group to an application allows members from that group to access the application through SSO. Members of the technical management group of this application may request access to make the application available to members of another group. Manager from the responsible group have to approve there requests.

Figure 118. Adding a group to an application

17.5. Permissions for OAuth 2.0 clients

OAuth 2.0 applications that use the client_credentials grant still need to be granted permissions before they can be used. These can be global permissions over the entire application, but also permissions specific to a single group or linked system. Open the Permissions tab to view the assigned permissions.

Figure 119. Permissions granted to an OAuth 2.0 client

Click on Add to request a permission. This request will go to a manager of the group in charge of the relevant permission. For global permissions, these are the members of the KeyHub Administrators group. For permissions over a linked system, a manager of the group with technical administration must agree.

Figure 120. Request permissions for an OAuth 2.0 client

The following permissions can be requested for an OAuth 2.0 client:

Accounts - Query and read accounts: The client is allowed to search for accounts and read general information for accounts. This permission must be approved by a KeyHub Administrator.
Accounts - Create new accounts: The client is allowed to create new accounts within Topicus KeyHub. This is only possible using the SCIM-endpoint. This permission must be approved by a KeyHub Administrator.
Accounts - Remove accounts: The client is allowed to remove accounts. This permission must be approved by a KeyHub Administrator.
Applications - Create new applications: The client is allowed to create new applications within Topicus KeyHub. These new applications will always be administered by the creating clients' own technical administration group. This permission must be approved by a manager of the group with technical administration of the client.
Applications - Query and read applications: The client is allowed to search for and read general information from other applications. This permission must be approved by a KeyHub Administrator.
Groups on systems - Create new groups on systems: The client is allowed to create new groups on the designated linked system. These groups are created directly within the linked system and can also be linked to groups or service accounts within Topicus KeyHub. This permission must be approved by a manager of the group with ownership of the linked system.
Groups - Create new groups: The client is allowed to create new groups within Topicus KeyHub. This permission must be approved by a KeyHub Administrator.
Groups - Grant applications permissions after creating: The client can directly give permissions to clients, including itself, for groups it creates. This permission must be approved by a KeyHub Administrator.
Groups - Query and read groups: The client is allowed to search for groups and read general information from groups. This permission must be approved by a KeyHub Administrator. When this permission is combined with the permission to search accounts, applications, or linked systems, the client also gets permission to read the links between these resources: memberships, sso connections, and provisioning configuration. With this permissions, clients will also get permission to read private groups.
Groups - Assign group classifications: The client is allowed to assign group classifications to existing groups. If the client also has the permission to create groups, the classification can be set directly when the group is created. This permission must be approved by an auditor group manager.
Groups - Access the vault of a group: The client is allowed to create, read, modify, and delete vault records for a designated group. This permission must be approved by a manager of the designated group.
Groups - Management of a group’s launchpad tiles: The client is allowed to create, read, modify, and delete launchpad tiles for a designated group. This permission must be approved by a manager of the designated group.
Groups - Access group details: The client is allowed to read details for a designated group. These details consist of the members of the group, linked applications, and groups on systems for that group. This permission must be approved by a manager of the designated group.
Groups - Configure a group for additional authorisation: The client may, when creating new groups, associate the designated group to perform additional authorisation. The designated group can be specified as an authorising group for activation, membership and audits, or as a group to nest the new group under. This permission must be approved by a manager of the designated group.
Linked systems - Query and read linked systems: The client is allowed to search for provisioned systems and read general information about these systems, includings the groups on the system. This permission must be approved by a KeyHub Administrator.
Service accounts - Create new service accounts: The client is allowed to create new service accounts within Topicus KeyHub. This permission must be approved by a manager of the group with ownership of the linked system.
Service accounts - Query and read service accounts: The client is allowed to search for and read general information from service accounts. This permission must be approved by a KeyHub Administrator.
Service accounts - Update service accounts: The client is allowed to update service accounts administred by a selected group. This permission must be approved by a manager of the designated group.

17.6. Audit log

The menu-item Auditlog gives access to the audit log of the selected application. The audit log that is shown contains rules regarding authentication and authorisation of the application. With the filter on top of the screen the audit log can be filtered.

$Audit log of an application$

Figure 121. Audit log of an application

17.7. Custom attributes

Custom attributes for OpenID Connect and/or SAML are described in JavaScript using the ECMAScript 5 standard. The script defines the body of a function which has the following outline;

function (account, groups) {
   {SCRIPT}
}

Here, the account is the account of the authenticated user and groups are the groups this account is a member of. account and the elements of the groups array have the following properties:

account
  - boolean active              : true if the account is active
  - String uuid                 : the unique identifier of the account
  - boolean validInDirectory    : true if the account is valid in the directory
  - String username             : the username of the account
  - String displayName          : the name of the user
  - String email                : the e-mail address of the user
  - String idInDirectory        : the identifier of the account within the directory
  - directory
    - boolean active            : true if the directory is active
    - String uuid               : the unique identifier of the directory
    - String name               : the name of the directory
    - String type               : the type of the directory
  - Instant lastActive          : the moment of the last login
  - boolean canRequestGroups    : true if the user is allowed to request groups
  - String locale               : the locale of the user
  - Object attributes           : the stored attributes for the account,
                                  as map from key to list of values
  - Object attributesFirstValue : the stored attributes for the account,
                                  for every key the first value

groups[]
  - boolean admin               : only true for the KeyHub Administrator group
  - String uuid                 : the unique identifier of the group
  - String name                 : the name of the group
  - String description          : the description of the group
  - String rights               : MANAGER or NORMAL
  - Instant provisioningEndTime : the chosen end time of the group
  - boolean active              : true when the group is enabled

Some examples of valid scripts are:

// the e-mail address of the user:
return account.email;

// the uuid's of all groups this user is a member of:
return groups.map(function (group) {return group.uuid;});

18. Linked systems

Topicus KeyHub can create accounts on linked systems on-demand. Accounts of linked systems are created (or activated) when the user activates the corresponding group on the dashboard. The following types of linked systems are supported:

LDAP: An LDAP-connection is used to create posix-accounts on an LDAP-system like OpenLDAP. This type of connection is typically used for authorisation of Unix-based systems.
Active Directory: The Active Directory connection is used to activate accounts on an Microsoft or Samba Active Directory. This type of connections is typically used for authorisation of Windows-based systems, but can be used for other types of applications as well. Any application which can connect to an Active Directory is supported.
Azure tenant: The Azure tenant connection is used to create accounts in a Microsoft Azure Active Directory tenant. This allows access to the Azure portal or Office 365.
LDAP Source directory: A LDAP source directory connection is used to dynamically provision accounts in the authentication LDAP directory with groups. The account used to log in to Topicus KeyHub is hereby added to and removed from groups within that LDAP-directory. The accounts themselves are not created and/or deleted.
Azure OIDC source directory: An Azure OIDC source directory connection is used to dynamically provision accounts in the Azure OIDC directory with groups. The account used to log in to Topicus KeyHub is hereby added to and removed from groups within that Azure directory. The accounts themselves are not created and/or deleted.
Azure tenant with AD Connect: An Azure tenant with AD Connect connection is used to dynamically provision accounts in a Microsoft Azure Active Directory tenant with groups, whereby this tenant is synchronized with an on-premise Active Directory through Azure AD Connect. The account from the on-premise Active Directory that is used to log in to Topicus KeyHub is synchronized to Azure AD by Azure AD Connect. This account within the Azure Active Dictory is added to and removed from groups within that Azure directory by Topicus KeyHub. The accounts themselves are not created and/or deleted.
Internal LDAP: An internal LDAP-connection emulates the dynamic provisioning on the LDAP-endpoint of Topicus KeyHub itself.

Figure 122. Linked systems

18.1. Connecting to LDAP

LDAP-systems are often used for services to authenticate against. In combination with Topicus KeyHub, an LDAP can be used for dynamic authorisation as well. Topicus KeyHub supports LDAP v3 compliant servers like OpenLDAP and 389 Directory Server.

During the setup of an LDAP-connection this connection can be tested. Topicus KeyHub will try to setup a connection to the linked system and perform some basic operations. The result of this test is shown in the window on the top right of the screen.

Figure 123. Testing a linked LDAP

The following properties can be configured on a linked LDAP:

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not create or activate any accounts on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Primary host: The host name of the primary LDAP server. When using a (highly recommended) secure connection, an IP-address cannot be used here.
Failover host: The hostname of the optional secondary LDAP server. If left blank, Topicus KeyHub cannot use another server when communication with the primary server fails. The failover host is only used when communication with the primary host fails.
Port: The port number where the LDAP listens to. The default port is 389. When using LDAPS port number 636 can be used. For all other ports than 636 Topicus KeyHub will use StartTLS to secure the connection.
TLS: User passwords and secrets are sent through the connection with the LDAP server. Securing the connection is therefore highly recommended. See the chapter about certificates for more information.
Trusted certificate: This certificate determines which certificates can be trusted when setting up a secure connection. If left blank, the standard Java-truststore will be used. See the chapter about certificates for more information.
Trusted certificate for failover: The same as the above, but for the failover host.
Bind DN: The complete DN to bind to when applying search queries to accounts within the directory. It is highly recommended to use a read-only LDAP account.
Bind password: The password to create the bind
Client certificate: When using client authentication Bind DN and Bind password are replaces by a certificate with Topicus KeyHub uses to authenticate itself against the directory. This is the most secure way of setting up a connection to the directory.
Base DN: The DN in the directory to search for users
Group RDN: The relative DN, with respect to the Base DN, where the groups are located. Groups on an LDAP system are created as posixGroup, groupOfNames or groupOfUniqueNames.
User RDN: The relative DN, with respect to the Base DN, where the accounts are located. Accounts on an LDAP system are created as posixAccount.
Service account RDN: The relative DN, with respect to the Base DN, where the service accounts are located. Service accounts on an LDAP system are created as posixAccount.
Username prefix: A prefix that is placed before the Topicus KeyHub username when an account is created on the LDAP. This prefix is separated from the Topicus KeyHub username by a dash character '-'. The resulting account name in the LDAP looks like this: '<prefix>-<username>'.
Remove unknown accounts: Accounts that are not known within Topicus KeyHub will be removed during a synchronization.

Only activate this option if Topicus KeyHub is fully responsible for managing the accounts within the given DN.

SSH public key: Indicated whether the LDAP server supports the ldapPublicKey object class. This objecft class defines the sshPublicKey attribute where the SSH public key of the user can be stored. Many of the widely used LDAP servers (like OpenLDAP) support this attribute. When disabled, the SSH public key of the user will not be provisioned to the LDAP server.
Password hashing: When using an LDAP-connection, passwords are stored as a hash. Topicus KeyHub is responsible for choosing the hashing algorithm. A common algorithm is SSHA. With this algorithm a password is combined with a salt and hashed once with SHA-. Because of this, this algorithm is considered weak, but it is supported by most LDAP servers. Since version 2.4.41 OpenLDAP supports PBKDF2-SHA512 as well. This is a very strong algorithm which performs 64k iterations of SAH-512 on a salted password. If the LDAP server supports this algorithm, it is highly recommended to use this.
Additional object classes: Additional values for the objectClass attribute of accounts. When using custom attributes it may be necessary to add additional object classes. Values are separated by spaces.
Custom Attributes: Additional attributes that are added to accounts can be defined here. The possibilities of these attributes are described in Custom attributes. Note that these values must be allowed within the scheme used. Additional object classes may need to be added to support the desired attributes.
User ID (uid): Topicus keyHub automatically assigns UIDs to users from a number sequence. Choose an existing sequence here or start a new one. The number is always incremented by 1 for each new account. Always ensure that accounts created by KeyHub do not conflict with other accounts on systems. The sequence can only be set at initial setup and must start in the range 2000 to 60000. See the section on number sequences for more details.
Group ID (gid): The Group ID of the primary group of which Topicus KeyHub will be part.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, request to create a new connection to existing groups, or request service accounts. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: This unique identifier is read from the LDAP server. It is not possible to add the same LDAP server multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 124. Linked LDAP

18.2. Connecting an Active Directory

Active Directory is Microsoft’s directory server. This solution supports both an LDAP-interface as an Windows-domain. Topicus KeyHUb connects to an Active Directory through the LDAP-interface, although the created accounts can be used within the domain of the Active Directory as well. To prevent changing the Object GUID of the account and because Active Directory requires a plaintext password when creating an account, Topicus KeyHub activates and deactivates accounts on Active Directory instead of deleting and creating accounts. Accounts are automatically removed from an Active Directory when a user no longer has access to the system via any group for a period of 2 weeks or when the Topicus KeyHub account is removed.

To prevent issues when creating accounts on Active Directory, it is highly recommended to disable the password policies on the Active Directory. Deleting the policies is not sufficient as Active Directory then uses the default policy. The password policy should be configured in Topicus KeyHub. The typical error message for issues concerning password policies is Server is unwilling to perform.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not create or activate any accounts on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Primary host: The host name of the primary Active Directory server. When using a (highly recommended) secure connection, an IP-address cannot be used here.
Failover host: The hostname of the optional secondary LDAP server. If left blank, Topicus KeyHub cannot use another server when communication with the primary server fails. The failover host is only used when communication with the primary host fails.
Port: The port number where the Active Directory listens to. The default port is 389. Wenn using LDAPS port number 636 can be used. For all other ports than 636 Topicus KeyHub will use StartTLS to secure the connection.
TLS: User passwords and secrets are sent through the connection with the Active Directory server. Securing the connection is therefore highly recommended. See the chapter about certificates for more information.
Trusted certificate: This certificate determines which certificates can be trusted when setting up a secure connection. If left blank, the standard Java-truststore will be used. See the chapter about certificates for more information.
Trusted certificate for failover: The same as the above, but for the failover host.
Bind DN: The complete DN to bind to when applying search queries to accounts within the directory. This account should have the authorisation to create new entries and modify existing entries in the Active Directory.
Bind password: The password to create the bind
Client certificate: When using client authentication Bind DN and Bind password are replaced by a certificate which Topicus KeyHub uses to authenticate itself against the directory. This is the most secure way of setting up a connection to the directory.
Base DN: The DN in the directory to search for users
Group RDN: The relative DN, with respect to the Base DN, where the groups are located. Groups on an Active Directory system are created as group, either as a local or a global security group.
User RDN: The relative DN, with respect to the Base DN, where the accounts are located. Accounts on an Active Directory system are created as user.
Service account RDN: The relative DN, with respect to the Base DN, where the service accounts are located. Service accounts on an Active Directory system are created as user.
Username prefix: A prefix that is placed before the Topicus KeyHub username when an account is created on the LDAP. This prefix is separated from the Topicus KeyHub username by a dash character '-'. The resulting username in the AD looks like this: '<prefix>-<username>'.
Remove accounts after: An account is automatically removed once it loses all access to the system. Here you can configure how much time must pass before the account must be removed. Use 'd' for days, 'w' for weeks', 'm' for months and 'y' for years, for example '2w' for a period of 2 weeks.

Accounts on linked systems are always removed as soon as the account is removed from Topicus KeyHub, even if this period has not yet expired.

Remove unknown accounts: Accounts that are not known within Topicus KeyHub will be removed during a synchronization.

Only activate this option if Topicus KeyHub is fully responsible for managing the accounts within the given DN.

SAM-Account-Name: The SAM-Account-Name attribute in the AD is used by some legacy systems for authentication. This attribute has a maximum length of 20 characters. If the combination of the username prefix and username in Topicus KeyHub becomes longer than these 20 characters, normally no SAM-Account-Name will be set. In that case, the AD generates a random, unique value for this attribute. With this option you can choose to shorten the SAM-Account-Name attribute, so that it does not exceed 20 characters. Note that this truncated value may no longer be unique. It is also possible to take the value from an account attribute with the same name, with the possible addition of a prefix. If no systems are used that depend on this attribute, you can choose to omit it entirely.
Additional object classes: Additional values for the objectClass attribute of accounts. When using custom attributes it may be necessary to add additional object classes. Values are separated by spaces.
Custom Attributes: Additional attributes that are added to accounts can be defined here. The possibilities of these attributes are described in Custom attributes. Note that these values must be allowed within the scheme used. Additional object classes may need to be added to support the desired attributes.
SSH public key: Indicated whether the AD server supports the ldapPublicKey object class. This object class defines the sshPublicKey attribute where the SSH public key of the user can be stored. Active Directory, by default, does not support this object class and attribute. For support, these need to be added manually. An alternative is the usage of the altSecurityIdentities attribute to store the SSH public key. This attribute does not require custom object classes, but it is not officially meant to store an SSH public key. When disabled, the SSH public key of the user will not be provisioned to the AD server.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, request to create a new connection to existing groups, or request service accounts. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: This unique identifier is read from the Active Directory. It is not possible to add the same Active Directory server multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 125. Linked Active Directory

18.3. Connecting to Microsoft Azure Active Directory

Azure Active Directory is the cloud environment for managing access to many of Microsoft’s online services, including Office 365 and the Azure portal. KeyHub connects to Azure Active Directory via the graph API. For this, an application registration must be created within the Azure portal with the following application permissions: RoleManagement.ReadWrite.Directory, User.ReadWrite.All, Directory.ReadWrite.All and User.ManageIdentities.All. The application also needs to be added to the Global administrators role. Topicus KeyHub can create users and assign them to directory roles and groups within Azure. To prevent the UUID of the accounts from changing and because Azure Active Directory requires a plaintext password when creating an account, KeyHub deactivates accounts instead of deleting them. Accounts are automatically removed from an Azure Active Directory as soon as a user no longer has access to the system via any group for a period of 2 weeks or if the Topicus KeyHub account is removed.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not create or activate any accounts on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Client identifier: The application ID for the app registration in Azure.
Client secret: The secret associated with the above identifier.
Azure tenant: The name of the tenant within Azure.
Identity provider domain: With an identity provider domain set, users will be invited via that domain and log in via SSO. If this field is left empty, users are created directly within the tenant with the password from Topicus KeyHub. By entering the domain of the Topicus KeyHub installation here, users can log in to Azure with SSO via Topicus KeyHub.
Username prefix: A prefix that is placed before the Topicus KeyHub username when an account is created within Azure. This prefix is separated from the Topicus KeyHub username by a dash character '-'. The resulting account name in Azure looks like this: '<prefix>-<username>'.
Remove accounts after: An account is automatically removed once it loses all access to the system. Here you can configure how much time must pass before the account must be removed. Use 'd' for days, 'w' for weeks', 'm' for months and 'y' for years, for example '2w' for a period of 2 weeks.

Accounts on linked systems are always removed as soon as the account is removed from Topicus KeyHub, even if this period has not yet expired.

Remove unknown accounts: Accounts that are not known within Topicus KeyHub will be removed during a synchronization.

Only activate this option if Topicus KeyHub is fully responsible for managing the accounts within the given DN.

Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, request to create a new connection to existing groups, or request service accounts. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: The UUID associated with the connected Azure tenant. It is not possible to add the same Azure tenant multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 126. Linked Azure Active Directory

18.4. Connecting a LDAP source directory

The source directory is the LDAP directory that a user uses to log in to Topicus KeyHub. When linking to the source LDAP directory, the user is dynamically added to and removed from groups within this directory.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not add accounts to groups on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
LDAP directory: The directory which is linked. If multiple directories are used within Topicus KeyHub, only users from the chosen directory will be able to use this linked system.

The LDAP directory must be configured with write permissions.

Group DN: The DN within the chosen directory, where the groups are located.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, or request to create a new connection to existing groups. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: This unique identifier is read from the directory. It is not possible to add the same directory server multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 127. Linked LDAP source directory

18.5. Connecting a Azure OIDC source directory

The source directory is the Azure OIDC directory that a user uses to log in to Topicus KeyHub. When linking to the source Azure OIDC directory, the user is dynamically added to and removed from groups within this directory.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not add accounts to groups on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to. This is the same as the source directory’s organisational unit.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Azure OIDC directory: The directory which is linked. If multiple directories are used within Topicus KeyHub, only users from the chosen directory will be able to use this linked system.

The client used for the Azure OIDC directory must be configured with write permissions.

Tenant: The Azure tenant containing the accounts.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, or request to create a new connection to existing groups. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: This unique identifier is read from the directory. It is not possible to add the same tenant multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 128. Linked Azure OIDC source directory

18.6. Connecting a Azure tenant with AD Connect

When linking to an Azure tenant with AD Connect, the user is dynamically added and removed from groups within Azure Active Directory. This is used when users sign in to Topicus KeyHub from an on-premise Active Directory and this directory is synchronized with Azure AD Connect to an Azure AD tenant. The source directory is the Active Directory LDAP directory that a user uses to log in to Topicus KeyHub.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not add accounts to groups on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to. This is the same as the source directory’s organisational unit.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
LDAP directory: The directory which is linked. If multiple directories are used within Topicus KeyHub, only users from the chosen directory will be able to use this linked system.

This directory must be synchronized with the chosen Azure tenant via Azure AD Connect.

Client identifier: The application ID for the app registration in Azure.
Client secret: The secret associated with the above identifier.
Tenant: The Azure tenant containing the accounts.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, or request to create a new connection to existing groups. When self-service is disabled, this functionality will only be available to the members of the content administrators group.
External UUID: This unique identifier is read from the directory. It is not possible to add the same tenant multiple times in Topicus KeyHub. This is enforced through this UUID.

Figure 129. Linked Azure tenant with AD Connect

18.7. Connecting an internal LDAP

Topicus KeyHub has its own LDAP-endpoint. Through this endpoint the static structure of Topicus KeyHub can be extracted. By setting up a connection with the internal LDAP the dynamic context of Topicus KeyHub becomes available as well. This dynamic context distinguishes itself from the static content by DC=dynamic. Just like a connection to a regular LDAP server only active accounts exist and accounts are only assigned groups when the corresponding group in Topicus KeyHub is activated from the dashboard.

Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not create or activate any accounts on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
LDAP Client: The LDAP client definition which among others determines the credentials. See LDAP v3 application for more information regarding the registration of an LDAP client.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, or request to create a new connection to existing groups. When self-service is disabled, this functionality will only be available to the members of the technical administrators group.

Figure 130. Linked internal LDAP

18.8. Connecting a SCIM-system

KeyHub supports provisioning through the System for Cross-domain Identity Management, or SCIM. SCIM is an open standard that enables the automatic provisioning of users and groups through a REST API.

Status: Shows the current status of the linked system. If a linked system gives errors too often, it will be disconnected temporarily to prevent further malfunctions.
Active: Users can only use a linked system whenever it is active. Topicus KeyHub will not add accounts to groups on linked systems that are not active.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Vendor: Many vendors use their own SCIM dialect. Choose the correct vendor dialect for optimal functionality of the SCIM integration.
URL: The complete URL where the SCIM REST API can be found. Only http and https may be used.
Authentication Scheme: If Topicus KeyHub needs to authenticate during provisioning via SCIM, an authentication method can be chosen here. The available options will display various fields for entering the authentication details.
User name: Available with the authentication scheme 'Basic authentication'. This will be sent together with the password in the Authorization header.
Password: Available with the authentication scheme 'Basic authentication'. This will be sent together with the username in the Authorization header.
Bearer Token: Available with the authentication scheme 'Bearer token'. This token will be sent in the Authorization header, preceded by the word Bearer.
Header name: Available with the authentication scheme 'Custom'. The value entered below will be sent in a header with the name entered here.
Header value: Available with the authentication scheme 'Custom'. The value entered here will be sent in a header with the name entered above.
Remove accounts after: An account is automatically removed once it loses all access to the system. Here you can configure how much time must pass before the account must be removed. Use 'd' for days, 'w' for weeks', 'm' for months and 'y' for years, for example '2w' for a period of 2 weeks.

Accounts on linked systems are always removed as soon as the account is removed from Topicus KeyHub, even if this period has not yet expired.

Remove unknown accounts: Accounts that are not known within Topicus KeyHub will be removed during a synchronization.

Only activate this option if Topicus KeyHub is fully responsible for managing the accounts within the given DN.

Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, request to create a new connection to existing groups, or request service accounts. When self-service is disabled, this functionality will only be available to the members of the content administrators group.

Figure 131. Provisioned SCIM-system

18.9. Namespaces

A namespace is a variant, or proxy, of an existing provisioned system with its own provisioning. It is functionally equivalent with a seperate provisioned system on the same external system as an existing base system. The technical configuration is derived from this base system, but a namespace has its own DNs for groups and for service accounts.

A namespace has its own groups and serviceaccounts on the system, which are separate from the chosen base system, but it uses the same provisioned accounts as the base system. This means that users can have access to a combination of groups in either system. For users there is no functional difference between a namespace or its base system.

Technical administration of the namespace is done by the technical administrators group of the base system. This mostly concerns setting the correct RDNs for groups and service accounts. Configuration option such as hostnames and credentials are derived from the base system.

A namespace has its own content administration group. This group is also the owning group of the namespace.

A namespace can be scoped to a different organisational unit from its base system, as long as this organisational unit lies hierarchically under the organisational unit of the base system.

The following properties can be configured on a namespace:

Status: Shows the namespace’s current status. This is the status of the base system.
Actief: A namespace can not be activated or deactivated. This property represents the status of the base system.
UUID: A unique identifier for this linked system connection within Topicus KeyHub.
Name: The name of the connection as displayed to users of Topicus KeyHub.
Organisational unit: The organisational unit this system belongs to.
Technical administrators group: Members of this group can perform the technical administration of this linked system. Members may edit the system or request it be removed. Webhooks for the system are also managed by this group.
Group with ownership: Members of this group make the decisions about the linked system. Requests addressed to the linked system are handled by the managers of this group.
Content administrators group: Members of this group make decisions about the contents of the linked system. Request to create new groups on system or service accounts are addressed to this group. Requests for access to existing groups on system also need to be approved by members of this group, before being sent on to the owning group of the group on system.
Group RDN: The relative DN, with respect to the Base DN, where the groups are located. Groups on a namespace can be of any type supported by the parent system.
Service account RDN: The relative DN, with respect to the Base DN, where the service accounts are located.
Self-service: The enabled self-service options for the linked system. When self-service is enabled, group managers can request new groups, request to create a new connection to existing groups, or request service accounts. When self-service is disabled, this functionality will only be available to the members of the content administrators group.

Figure 132. Namespace

18.10. Provisioned system groups

A linked system only provides authorisations when the groups of the linked system are connected to groups in Topicus KeyHub. Members of these groups will find the group on their dashboard which provides the possibility of (de)activating the group. Each time a member activates a group on the dashboard, the account of the user will be created or activated on the linked system and provisioned with the configured group. The user then has access to the systems and services that authenticate against the connected linked system and group.

Figure 133. Provisioned system groups

18.10.1. Adding a group to a linked system

Adding a group to a linked system will provide the corresponding group member with the authorisation to that linked system. The following properties can be configured when adding a group to a linked system:

Linked system: The linked system where the group will be added to.
Group: The Topicus KeyHub group to be connected.
New or existing: For the group within the system you can choose from one of the existing groups or a new group can easily be created. If an existing group is chosen, a request will be sent to the group with ownership for the selected group. If a new group is chosen, a request will be sent to the system’s content administrator group.
Group on system: The existing group on the linked system to which access must be given.
New group on system: The name of the new group can be changed here. By default, Topicus KeyHub will fill in the name of the group in KeyHub here, removing spaces.
Type of the new group: Some linked systems support multiple group types, such as posixGroup, groupOfNames and groupOfUniqueNames for a linked LDAP system. Select the desired type here.
Group with ownership: Members of this group make the decisions about access to the group on the linked system.
Activation required: Use dynamic account provisioning for this group. With dynamic account provisioning, the group on the dashboard must be enabled by the user before it is activated.
Reason: The reason for the request, which will be used for the assessment of the request.

Figure 134. Adding a group to a linked system

18.11. Groups on linked system

An overview of all groups on a linked system can be found under Groups on system. This shows a list of all groups as configured on the linked system, including the corresponding group(s) of Topicus KeyHub.

Figure 135. Groups on system

The special group Account-only provisioning allows users to activate an account on the linked system without associating a group on the linked system with it. This group does not actually exist on the linked system, but only serves to connect it to a group within Topicus KeyHub.

18.11.1. Details of a group on a linked system

Clicking on a group on system opens the following screen where the details of the group on system will be shown. This page can also be reached via the Manage Access page.

A group on a linked system cannot be modified. It is possible to transfer responsibility of a group on system to another group in Topicus KeyHub. Completely removing a group on system is possible as well.

It is possible to remove a group on a linked system from Topicus KeyHub but keeping the actual group on the system itself. This will only work when the group resides outside the search context on the linked system, otherwise Topicus KeyHub will detect the group again and recreate the record.

Topicus KeyHub is unaware of outside uses of a group on system. Never remove a group from a linked system without determining whether this group is used elsewhere.

Figure 136. Details of a group on a linked system

18.11.2. Groups linked to a group on a linked system

An overview of KeyHub groups linked to the group on a linked system can be found under Groups.

Figure 137. KeyHub groups linked to a group on a linked system

18.11.3. Service accounts linked to a group on a linked system

An overview of service accounts linked to the group on a linked system can be found under Service accounts.

Figure 138. Service accounts linked to a group on a linked system

18.12. Service accounts within a linked system

An overview of all service accounts within a linked system can be found under Service Accounts. This shows a list of all service accounts as configured on the linked system, including which group is responsible for technical administration. Further details of a service account can be viewed by opening a service account.

Figure 139. Service accounts within a linked system

18.13. Namespaces of a linked system

An overview of all namespaces for a linked system can be found under Namespaces. This shows a list of all namespaces that have the linked system as their base. A technical administrator of the system can create a namespace directly via the Add button.

Figure 140. Namespaces of a linked system

18.14. Issued permissions

OAuth 2.0 applications using the client_credentials grant can be granted permissions for operations on a linked system. See the chapter on permissions for OAuth 2.0 clients for more details on these permissions. The permissions targeting this linked system can be viewed and, if desired, revoked under the tab Issued permissions.

Only the group with ownership of the linked system can revoke a granted permission.

Figure 141. Permissions issued to OAuth 2.0 Clients

18.15. Synchronisations

Linked systems are fully synchronised once an hour. The logs of this can be viewed under Synchronisations. Each synchronisation also keeps track of how many modifications have been made. Under normal circumstances, a full synchronisation should not produce any modifications. However, if errors have occurred during partial synchronisations or if changes have been made manually on the linked system, these anomalies will be corrected and reported.

Only a technical administrator of the linked system can manually start a synchronisation.

Figure 142. Synchronisations

18.16. Linked systems and organizational units

A linked system is also scoped to an organisational unit. Only groups linked to the same organisational unit, or to organisational units below the system’s unit, can see and use the system. This means that to be linked to a group on system of this system, the group’s organisational unit must be equal to or below the system’s organisational unit.

The owner, technical administrator and content administrator groups must belong to the same organisational unit as the system.

In the case of source directory provisioning, the linked system’s organisational unit is the same as directory’s organisational unit.

The system’s organisational unit field is likely to not be visible unless you’re actively using this functionality. For instance, if only the default organisational unit is present in the installation, the field would not be helpful in any way and will be hidden.

19. Global settings

Topicus KeyHub supports some global settings which should be configured before Topicus KeyHub is ready for normal usage.

It might take up to one minute before modified settings are enabled.

These global settings are:

Domain: The domain which serves the Topicus KeyHub instance. This domain is used as qualifier for the SAML v2.0 UPN and as naming context for the internal LDAP server.
Maintenance message: The maintenance message entered here will be displayed to all users on all pages throughout Topicus KeyHub. The message will remain until the field is cleared again.
Minimum password length: Short passwords pose a security risk. This option provides the possibility to enforce a minimum password length. It is highly recommended to use a length of 12 characters or more.
Default license role: The license role new accounts will be created with. If you set this to Pro, but you have no more Pro licenses available, new accounts will be created as Business.
Web session Timeout: This option sets the maximum length of inactivity for a web session before it expires. The value must be between 30m and 12h. Use m for minutes and h for hours. The default value is 4 hours.
Password authentication Timeout: This option sets the re-authentication interval by means of the user password. The value must be between 30m and 7d. Use m for minutes, h for hours, and d for days. The default value is 4 hours.
2FA authentication timeout: This option sets the re-authentication interval by means of a second factor. The value must be between 30m and 7d. Use m for minutes, h for hours, and d for days. The default value is 7 days.

The default values used by Topicus KeyHub for the re-authentication intervals have been chosen with care. Security and ease of use have been carefully weighed against each other. Shortening these intervals may reduce the length of time an attacker could take advantage of a stolen session, but it also has a negative impact on user-friendliness. Values that are too tight can cause users to look for other, less secure ways to access systems, such as storing passwords locally. Overly relaxed values increase the time span in which a stolen session can be abused.

Branding logo

With this setting, Topicus KeyHub can be provided with a branding logo. This logo takes the place of the KeyHub logo except on the login page, where a combination of the 2 logos is made. It is only allowed to upload a png file of exactly 540x280 pixels. For the best results, it is recommended to use a transparent background and use the entire space available.

Password generation

Topicus KeyHub has an adjustable password generator for passwords in the vault. The default generator is selected with the value KEYHUB. This generator generates very strong passwords that meet the latest password strength recommendations. It is also possible to determine your own setting by entering values in the format CL32LUDS. This value is made up of the following elements:

The fixed value CL.
A number with the length of the generated password, between 8 and 250.
A choice from the letters LUDS in upper or lower case. The L stands for lowercase letters, U for uppercase letters, D for digits and S for special characters. If the letter is capitalized, the password will always contain at least 1 character from that set. If a letter from the string LUDS is omitted, passwords will be generated without characters from the missing set(s).

Some examples:

CL8LUDS: zLPI:h8f, length 8, contains at least 1 lowercase letter, 1 uppercase letter, 1 number and 1 symbol.
CL8LUds: -YpJdLgE, length 8, contains at least 1 lowercase letter and 1 uppercase letter, numbers and symbols are optional.
CL10ld: 5quqdbgzz6, length 10, contains only lowercase letters and numbers.
CL32LUDS: C6B!*BPh1lU3cQd#*QXJTe-&a7rHCuHp, a very strong password with length 32 and at least 1 lower case letter, 1 upper case letter, 1 number and 1 symbol.

The default password generator KEYHUB generates very strong passwords. This generator is updated when there are new password recommendations. If a different generator is chosen, the organisation is responsible for adjusting the generator. If set incorrectly, it is possible to generate passwords that are not sufficiently strong. Only choose a different password generator if there are compelling reasons.

Public key for recovery: A prerequisite to being able to use vaults, is to upload a public key. This key is required to restore inaccessible vaults. Modifying this key requires its private key. If the private key is not supplied, recovery of existing vaults is no longer possible until each vault is opened at least once.
License key: The license file with the license key for this Topicus KeyHub instance. This license key is provided by Topicus or through one of its partners.
LDAP server certificate: The certificate with corresponding private key, used to secure connections with the LDAP server. Without certificate the LDAP server cannot be used.
IdP signing certificate: This certificate is used by Topicus KeyHub for signing access tokens, OpenID Connect ID tokens and SAML assertions. Topicus KeyHub automatically generates a certificate that is valid for 5 years. The certificate can be renewed via the appliance manager.
Verbose provisioning logging: Enables verbose logging for account provisioning. This option can be very useful when troubleshooting issues with provisioning.
Hint for new group names: Show a hint to users when requesting new groups. This hint is shown as a placeholder in the field for the name of the new group. For example, enter the expected format of a group name here. Configuring the property here is the same as under the root organisational unit.
Approve 'Create group': Requests to create new groups are handled by the chosen group rather than the KeyHub administrators. Configuring the property here is the same as under the root organisational unit.
Approve 'Enable technical administration': Requests to enable technical administration on groups are handled by the chosen group rather than the KeyHub administrators. Configuring the property here is the same as under the root organisational unit.
Approve 'Remove group': Requests to remove groups are handled by the chosen group rather than the KeyHub administrators. Configuring the property here is the same as under the root organisational unit.
Auditor group: The group that has access to the auditor dashboard. Configuring the property here sets it for the root organisational unit. If the KeyHub-administrators group is not the owner of the root organisational unit, this property can not be changed here.
Password recovery fallback group: Password recovery requests for users with insufficient group managers are also sent to users in the chosen group rather than the KeyHub administrators. Configuring the property here is the same as under the root organisational unit.
Audit Log Retention: Audit log records are automatically deleted after the set period. This period must be at least 3 months. Leave this field blank to never delete records. Use m for months and y for years, for example 5y for a period of 5 years.
Audit log pseudonymization: Audit log records are automatically pseudonymized after the set period. With pseudonymization, the fields containing usernames are wiped. The records can then only be traced back to the user by means of the UUID. This period must be at least 3 months. Leave this field blank to never pseudonymize the records. Use m for months and y for years, for example 5y for a period of 5 years.
Responsible disclosure: If the organisation has a responsible disclosure policy, it can be entered here. Limited HTML-layout is allowed: a, b, br, div, i, li, ol, p, u and ul. The responsible disclosure will be disclosed through a link on the login-screen.

Figure 143. Global settings

20. Notification settings

Topicus KeyHub supports some notification settings you can use to adjust Topicus KeyHub’s communication to your own preferences.

It might take up to one minute before modified settings are enabled.

These settings are:

Email signature: With this setting you can add a custom signature to every email Topicus KeyHub sends out. Topicus KeyHub will also append its own default signature.
Sender address for email: Enter the email address that Topicus KeyHub will send e-mail from. If this is left blank, the email address of the user will be used as the sender.
No links in emails: When this box is checked, Topicus KeyHub will no longer include links or URLs in any emails. This includes the accept/reject links for requests, the links to the console in the footer and the registration links for internal accounts.
User reserve: The number of users to be kept in reserve. A warning will be sent as soon as less than this number of users are available within the license.

Figure 144. Notification settings

21. Certificates

X.509-certificates play an important rol in securing communications between Topicus KeyHub and other connected systems. For a trusted and safe configuration it is important to use these certificates correctly and configure trusted certificates in Topicus KeyHub. Certificates can be managed on the Settings-page.

21.1. Trusted certificates

To setup a secure connection to a server, this server should be able to present a certificate. The public key of this certificate is used to exchange encryption keys. However, just encrypting the communication is not sufficient. Topicus KeyHub should trust the server to be the actual intended server. Therefore the certificate should be configured in Topicus KeyHub as trusted certificate. A common way to realise this is to sign the server-certificates with one or more central certificates and upload these certificates to Topicus KeyHub.

Figure 145. Certificates

In order to upload a trusted certificate to Topicus KeyHub, the PEM-file should be uploaded and assigned an alias. This certificate can then be configured as the certificate for a trusted connection. Another possibility is to upload a certificate while configuring an LDAP. In that case the uploaded certificate will not be available to other connections.

Figure 146. Trusted certificate

21.2. Certificates with a private key

Certificates with a private key are used at various places within Topicus KeyHub. Such certificates can serve for client authentication (also called mutual TLS) or for authentication of a server endpoint. Topicus KeyHub supports different formats for uploading these certificates:

PEM: A PEM file contains the Base64 encoded DER representation of the certificate or key between markers in the following form: -----BEGIN CERTIFICATE----- and ----- END CERTIFICATE-----. Upload the certificate and the private key as 2 separate PEM files. If the private key is encrypted with a password, this password must also be specified. Obviously, the certificate and private key must belong together.
PKCS#12: Public-Key Cryptography Standard 12 (PKCS#12) is a complex format that can store various types of cryptographic information. For certificates, PKCS#12 is often used to store a certificate chain and private key in a single file. Under Windows, the file extension .pfx is commonly used for PKCS#12 files. Topicus KeyHub can read a certificate and its private key from a PKCS#12 file. The certificate chain is not read. The file and private key must be encrypted with the same password.

22. Number sequences

Topicus keyHub automatically assigns UIDs to users from a number sequence. The number is always incremented by 1 for each new account. By using the same number sequence for multiple connected systems, users are assigned the same UID on all these systems. When replacing or reimplementating a linked system, this also ensures that users retain the same UID. A number sequence cannot be deleted if it is still being used by a linked system.

Figure 147. Number sequences

23. Webhooks

Webhooks can be used to trigger external systems and applications based on events that occur in Topicus KeyHub. For every type of audit log event a webhook can be configured. Furthermore it is possible to restrict a webhook to a single group, directory, application or linked system.

With webhooks, information about potential important events are shared with other systems. Although the information that is sent by default is concise, it could provide a malicious party with information about the use of KeyHub. Very detailed information is sent when using 'Verbose payloads'. Therefore, only create webhook connections with trusted systems.

23.1. Creating a webhook

The following properties can be configured for a webhook:

Active: Webhook deliveries will only be performed when the webhook is active.
Name: The name of the webhook.
URL: The complete URL where the webhook should be delivered. Only http and https may be used.
TLS: Webhook deliveries might contain sensitive information like usernames. Therefore it is highly recommended to use a secure connection. See the chapter about certificates for more information.
Trusted certificate: This certificate determines which certificate should be trusted when setting up a secure connection. If left blank, the default Java-truststore will be used. See the chapter about certificates for more information.
Client certificate: When using client authentication, Topicus KeyHub will authenticate itself with a certificate at the webhook receiver. See the chapter about certificates for more information.
Authentication Scheme: If Topicus KeyHub has to authenticate when delivering the webhook, an authentication method can be selected here. The available options will show different fields for entering the authentication credentials.
User name: Available with the authentication scheme 'Basic authentication'. This will be sent together with the password in the Authorization header.
Password: Available with the authentication scheme 'Basic authentication'. This will be sent together with the username in the Authorization header.
Bearer Token: Available with the authentication scheme 'Bearer token'. This token will be sent in the Authorization header, preceded by the word Bearer.
Header name: Available with the authentication scheme 'Custom'. The value entered below will be sent in a header with this name.
Header value: Available with the authentication scheme 'Custom'. The value entered here will be sent in a header with the name entered above.
Verbose payloads: Send the complete objects with the delivery of a webhook. This option requires the use of a secure connection.

Figure 148. Webhook

23.1.1. Events

Each webhook should be assigned one or more events for which the webhook should trigger. The option 'All events' can be used to select all available events in Topicus KeyHub. When selecting specific events, the following categories are supported:

Autentication: Events about failed and successful authentication attempts. Unlocking a vault and issuing a SSO-token are part of this category as well.
Provisioning: The (de)activation of accounts on groups on system (i.e. the user activating groups on the dashboard).
Profile: Modifications considering accounts and authentication of accounts and/or vaults.
Authorisation: The approval and denial of access to groups and/or vaults.
Default operations: All events based on the elements in Topicus KeyHub. These exist primarily of create, modify and delete events. For vault records there is an additional event: reading the password or file.
Request: All events regarding a request in Topicus KeyHub. For every type of event a selection can be made: requested, approved and denied.

23.1.2. Deliveries

The most recent deliveries of a webhook are shown when opening the webhook. This shows basic information like time and duration, as well as detailed information about the payload and the response. Deliveries can be triggered again with the 'Redeliver' button.

Figure 149. Webhook delivery

23.1.3. Payload

The payload of a webhook delivery consists of the following properties:

seq: An incremental number to determine the order of delivery. Webhooks are delivered a-synchronously. When multiple events are triggered there is no guarantee that the webhooks are delivered in the same order. This field makes sure the order can be restored at the receiving end of the webhook. This field is always present.
timestamp: The exact time on which the event took place. This field is always present.
type: The type of event. This field is always present.
byParty: The user or application who triggered the event. This field consists of a name, uuid and optionally an object.
account: The user who was the subject of the event. This field consists of a name, uuid and optionally an object.
group: The group which was subject of the event. This field consists of a name, uuid and optionally an object.
group2: A possible second group which was subject of the event. This field consists of a name, uuid and optionally an object.
groupClassification: The group classification which was subject of the event. This field consists of a name, uuid and optionally an object.
directory: The directory which was subject of this event. This field consists of a name, uuid and optionally an object.
client: The application which was subject of this event. This field consists of a name, uuid and optionally an object.
system: The linked system which was subject to this event. This field consists of a name, uuid and optionally an object.
serviceAccount: The service account which was subject to this event. This field consists of a name, uuid and optionally an object.
certificate: The certificate which was subject to this event. This field consists of a name, uuid and optionally an object.
vaultRecord: The vault record which was subject to this event. This field consists of a name, uuid and optionally an object.
webhook: The webhook which was subject to this event. This field consists of a name, uuid and optionally an object.
modificationRequest: A reference to the request which was subject to this event. This field consists of a uuid and optionally an object.
organizationalUnit: The organisational unit which was subject to this event. This field consists of a name, uuid and optionally an object.
accessProfile: The access profile which was subject to this event. This field consists of a name, uuid and optionally an object.
securityLevel: The security level which was required for this event or which was subject to this event.
parameter1: An additional unbound parameter used to send additional information which cannot be categorised in one of the above properties.
parameter2: An additional unbound parameter used to send additional information which cannot be categorised in one of the above properties.
parameter3: An additional unbound parameter used to send additional information which cannot be categorised in one of the above properties.

24. Vault recovery

Topicus KeyHub offers the possibility to recover vaults that have become unavailable or deleted by accident. During initial installation of Topicus KeyHub, a key-pair has been generated. The public key of this key-pair was uploaded at the settings of Topicus KeyHub. The private key of this key-pair should be safely stored in a physical safe. To recover a vault in Topicus KeyHub, this private key is required.

Figure 150. Vault recovery

24.1. Deleted vaults

When a group, account or application is removed from Topicus KeyHub, the accompanying vault will become inaccessible. Topicus KeyHub stores these vaults up to 100 days after removal. During this period the vault can be restored. Click on a vault to start the process to restore.

The window shows the name and type of the vault and which vault records are available for restore, After uploading the private key, an existing group in Topicus KeyHub should be chosen to restore the vault records into. After restoring, all recovered vault records are distinguishable by the prefix that has been added to the name of the vault record.

A personal vault can only be restored to an account with the same username.

Figure 151. Recover deleted vault

24.2. Inaccessible vaults

In situations that a vault is no longer accessible by anyone, for example if all members left a group or a used forgot his/her password to the personal vault. access can be restored using the recovery key.

The KeyHub administrator can click on the Recover access button, select the vault and then the user who should be granted access. Topicus KeyHub then asks for the private key and access is restored. This procedure is available for both group vaults and personal vaults.

Figure 152. Recover access

24.3. Generate a new recovery key

If the recovery key is leaked or lost, a new key pair must be generated. This should be an RSA key pair with a length of 4096 bit in DER format. This key pair can be generated with the following openssl commands:

openssl genpkey -algorithm RSA -outform der -pkeyopt rsa_keygen_bits:4096 \
      -out privatekey.der
openssl rsa -pubout -inform der -in privatekey.der -outform der \
      -out publickey.der

Upload the new public key under settings, along with the old private key, if it is still available.

25. About Topicus KeyHub

The 'about' page shows general information about the current Topicus KeyHub installation and the license.

25.1. Right now

Active accounts: Shows the number of accounts that are currently active.
Active sessions: Shows the number of sessions that are currently active.

25.2. Usage over time

This graph shows the usage of active users over the last two months.

25.3. License conditions

This shows the relevant conditions of the license of Topicus KeyHub. Exceeding the license conditions may impact the use of Topicus KeyHub.

Issue date: The date the license was issued.
Not before: The license is not valid before this date.
Expires at: The license is not valid after this date.
Number of licenses: The total number of user licenses. This is the sum of Business and Pro license roles.
Number of Pro licenses: The number of Pro user licenses.

25.3.1. Licensed features

Workflows: With this feature enabled you can use workflows like extra authorisation by other groups, delegation of manager privileges and private groups.
Nested groups: With this feature enabled, groups can be nested within other groups.
Enterprise organisation: With this feature organisations with multiple organisational units can separate the different units.
Compliance plus: With this feature enabled extra functionality on the auditor dashboard, like unlimited group classification, becomes available.
Service accounts: With this feature enabled provisioning of service accounts becomes available.
Identity Lifecycle Management: With this feature enabled it is possible to automatically manage the entire lifecycle of users.
Clustering: With this feature enabled Topicus KeyHub can be run in a cluster with 3 nodes for high availability.
Enterprise clustering: With this clustering feature enabled Topicus KeyHub can be run with 5 nodes.
Isolation mode: With this feature enabled Topicus KeyHub can run in network environments completely disconnected from the internet.

25.4. License characteristics

This shows the characteristics of the current license. Among others the owner and contact person of the license is shown. In case this changes it is recommended to contact Topicus.

Figure 153. About Topicus KeyHub

26. Command line interface

Topicus KeyHub can be access through a command line interface (CLI). To enable the CLI, the KeyHub CLI bundle has to be downloaded and unpacked on the system. The CLI requires an operational Java 17 installation.

The following command shows all options of the CLI:

> keyhub help
usage: keyhub <command> [ <args> ]

Commands are:
    help           Display help information.
    login          Connect to a KeyHub server either as a user or as a client.
    logout         Disconnect from a KeyHub server, discarding the credentials.
    status         Shows the status of the current connection and authentication.
    switch         Switch between authentication sessions.
    version        Displays the version of the Topicus KeyHub CLI.
    provisioning   Control account provisioning in Topicus KeyHub
    query          Query for different types of objects in Topicus KeyHub
    vault          Access vaults in Topicus KeyHub

See 'keyhub help <command>' for more information on a specific command.

26.1. Logging in with the Command line interface

It is required to log in with the CLI to Topicus KeyHub first. Logging in is done with the login command. There are several ways to log in with the Topicus KeyHub CLI, which are explained below.

> keyhub help login
NAME
        keyhub login - Connect to a KeyHub server either as a user or as a
        client.

SYNOPSIS
        keyhub login [ --client-credentials-grant ] [ --client-id <clientId> ]
                [ --client-secret <clientSecret> ] [ --store-secret ]
                [ --target-client-id <targetClientId> ] [ --uri <uri> ]

OPTIONS
        --client-credentials-grant
            Authenticate as a client, rather than as a user.


        --client-id <clientId>
            The client identifier as issued by KeyHub. When the client-id and
            secret are ommitted, the internal KeyHub Command Line Interface
            application is used.


        --client-secret <clientSecret>
            The client secret as issued by KeyHub, use '-' for a prompt.


        --store-secret
            Store the client-secret on disk for subsequent calls.


        --target-client-id <targetClientId>
            Produce a login token or assertion for the specified client
            identifier.


        --uri <uri>
            The root URI of the KeyHub instance including protocol (i.e.
            https://keyhub.mycompany.com).

26.1.1. Log in as a user

The easiest way to log in is as a regular user using the predefined KeyHub Command Line Interface client.

Use login with a --uri parameter to log in to Topicus KeyHub and follow the instructions:

> keyhub login --uri https://keyhub.example.org/
Authentication is required

Using a browser visit                          And enter the code
https://keyhub.example.org/login/code                    WMRJ-HRWW

Or directly visit
https://keyhub.example.org/login/code?usercode=WMRJ-HRWW
> keyhub status
Session #1 (active)
Status: connected to https://keyhub.example.org/
  Type: user authenticated on default CLI
  Client ID: 77ef8551-b8f2-46da-9932-1241e7997b0b
  User logged in: keyhubuser
  Access token: valid until 2024-06-20T16:26:46.757775068Z
  Vault: valid until 2024-06-20T16:26:46.757775068Z

Review the information and complete the login process.

Figure 154. Check the code

26.1.2. Using a secure client

The disadvantage of the method described above is that the standard 'KeyHub Command Line Interface' client does not support a long lasting login session. KeyHub Command Line Interface has the Public native application profile, so it does not get issued refresh tokens. As a result, the session expires after an hour and the user must log in again. This can be solved by creating a custom client with the profile 'Native application with secret' and use that to log in. Because refresh tokens can be used with this type of client, the session will remain active for a very long time. Log in as follows:

> keyhub login --uri https://keyhub.example.org/ \
    --client-id d5bee030-89a1-47f7-a114-e523ccfdc0c1 \
    --client-secret UHjn8ldBkvlsjfYSvXGLzLndq_30FNvMfLk1J0yq \
    --store-secret
Authentication is required

Using a browser visit                          And enter the code
https://keyhub.example.org/login/code                    ZZMZ-LBCB

Or directly visit
https://keyhub.example.org/login/code?usercode=ZZMZ-LBCB

26.1.3. Log in to a SAML v2.0 application

It is also possible to log in to a SAML v2.0 application via the CLI. In this situation, logging in will generate a SAML 'Response', which can be used to authenticate to the application. Here too, you can use your own client to get a longer session duration:

> keyhub login --uri https://keyhub.example.org/ \
    --target-client-id https://saml2-client.example.org \
    --client-id f3352687-fe5e-4ca1-a17b-3c61c5da062e \
    --client-secret eeunpl6UVgrypAyFEodBIvOeRD_SadcSbrOHCWOR \
    --store-secret
Authentication is required

Using a browser visit                          And enter the code
https://keyhub.example.org/login/code                    RNXF-RMCT

Or directly visit
https://keyhub.example.org/login/code?usercode=RNXF-RMCT

<?xml version="1.0" encoding="UTF-8"?><saml2p:Response> ... </saml2p:Response>

26.1.4. Log in with the client credentials grant

For automated integrations it can sometimes be useful to log in with the 'client credentials grant'. In these cases, the CLI itself authenticates instead of a user. To do this, create an OAuth 2.0 client and log in as follows:

> keyhub login --uri https://keyhub.example.org/ \
    --client-id 31d40750-eb6c-40b6-91d7-cf2b79984a5d \
    --client-secret MPn6sfm9jzQq8weYNtCYbENxLo3Ms2IR7SlO-mpZ \
    --client-credentials-grant

> keyhub status
Session #1 (active)
Status: connected to https://keyhub.example.org/
  Type: client credentials grant
  Client ID: 31d40750-eb6c-40b6-91d7-cf2b79984a5d
  Client Secret: not stored
  Access token: valid until 2024-06-20T16:25:13.983398721Z
  Vault: valid until 2024-06-20T16:25:13.983398721Z

26.2. Manage logged in sessions and log out

In the examples above, the status command has already been used a number of times:

> keyhub help status
NAME
        keyhub status - Shows the status of the current connection and
        authentication.

SYNOPSIS
        keyhub status

If there are multiple logged in sessions, it will look like this:

> keyhub status
Session #1
Status: connected to https://keyhub.example.org/
  Type: client credentials grant
  Client ID: 31d40750-eb6c-40b6-91d7-cf2b79984a5d
  Client Secret: not stored
  Access token: valid until 2024-06-20T16:25:13.983398721Z
  Vault: valid until 2024-06-20T16:25:13.983398721Z

Session #2
Status: connected to https://keyhub.example.org/
  Type: user authenticated on default CLI
  Client ID: 77ef8551-b8f2-46da-9932-1241e7997b0b
  User logged in: keyhubuser
  Access token: valid until 2024-06-20T16:25:19.198226750Z
  Vault: valid until 2024-06-20T16:25:19.198226750Z

Session #3
Status: connected to https://keyhub.example.org/
  Type: user authenticated on custom CLI client
  Client ID: d5bee030-89a1-47f7-a114-e523ccfdc0c1
  Client Secret: stored
  User logged in: keyhubuser
  Access token: valid until 2024-06-20T16:25:24.550471831Z
  Vault: valid until 2024-06-20T16:25:24.550471831Z, extended on demand

Session #4 (active)
Status: connected to https://keyhub.example.org/
  Type: user authenticated on target client, custom CLI client
  Client ID: d5bee030-89a1-47f7-a114-e523ccfdc0c1
  Client Secret: stored
  Authenticated for: https://saml2-client.example.org
  Access token: valid until 2024-06-20T16:25:29.869966951Z

The active session can be switched with the switch command:

> keyhub help switch
NAME
        keyhub switch - Switch between authentication sessions.

SYNOPSIS
        keyhub switch --index <index>

OPTIONS
        --index <index>
            The index of the session to active. Use 'status' to list the
            available sessions.

A session can be logged out using the logout command:

> keyhub help logout
NAME
        keyhub logout - Disconnect from a KeyHub server, discarding the
        credentials.

SYNOPSIS
        keyhub logout [ --all ] [ --index <index> ]

OPTIONS
        --all
            Logout all active sessions.

        --index <index>
            The index of the session to logout. When not specified, the last
            used session will be logged out.

26.3. Searching

You can search for elements in Topicus KeyHub via the CLI. For this, use a command from the query command group:

> keyhub help query
NAME
        keyhub query - Query for different types of objects in Topicus KeyHub

SYNOPSIS
        keyhub query { accounts | groups | records } [--] [ --uuid <uuid> ]
                [ --matches <matches> ] [ --query <query> ] [ --name <name> ]
                [ --output <output> ] [cmd-options]

        Where command-specific options [cmd-options] are:
            accounts:
            groups: [ --own ]
            records: [ --type <type> ]

        See 'keyhub help query <command>' for more information on a specific command.

All commands accept at least the options listed below. If multiple search options are specified, only those lines that match all specified search options are returned.

--name: Searches for an exact match to the name of the element.
--uuid: Searches for an exact match to the element’s UUID.
--matches: Filters for a textual match within the element. This includes the UUID, name, and possibly other properties.
--query: This allows you to search for different properties of the element. The syntax of this query is described below.

To search for records from multiple vaults at the same time, the query records command can be used. The following extra search option is available:

--type: Filters by the type of a vault record. The possible values are PASSWORD, FILE, TOTP and COMMENT.

The last column shows the type values present within the record: P for password, F for a file, T for TOTP and C for a comment. The result of a vault query command can be combined with a vault read command to read a specific record.

> keyhub query records --matches foo
VAULT                                  VAULT NAME       RECORD                                 NAME                  URL                  USERNAME   SECRETS
25bbf8c4-499c-4940-b16f-dfb0f54c749c   personal vault   53e81d9a-08b7-4efc-aadf-dc599ed0be8c   passwordforfoo        http://example.com   usn        P  C
25bbf8c4-499c-4940-b16f-dfb0f54c749c   personal vault   9cd0669c-a2d9-40dd-9748-42035d3ff371   file                                                   F
d590b067-74f9-48a7-8e38-7391f8a3518c   Product-X Test   385706a1-ceb5-4326-97ef-2fb22dadd986   grouppasswordforfoo                                   P  C
> keyhub query records --matches foo --type PASSWORD
VAULT                                  VAULT NAME       RECORD                                 NAME                  URL                  USERNAME   SECRETS
25bbf8c4-499c-4940-b16f-dfb0f54c749c   personal vault   53e81d9a-08b7-4efc-aadf-dc599ed0be8c   passwordforfoo        http://example.com   usn        P  C
d590b067-74f9-48a7-8e38-7391f8a3518c   Product-X Test   385706a1-ceb5-4326-97ef-2fb22dadd986   grouppasswordforfoo                                   P  C
> keyhub vault read --group d590b067-74f9-48a7-8e38-7391f8a3518c \
    --record 385706a1-ceb5-4326-97ef-2fb22dadd986 --type PASSWORD
groupsecret

26.3.1. Search queries

The syntax of a query is:

expression
  : expression 'and' expression
  | expression 'or' expression
  | 'not' expression
  | ( path '.' )? '(' expression ')'
  | path '=' value
  ;

path : IDENTIFIER ( '.' IDENTIFIER )*   ;

value : LITERAL ( ',' LITERAL )* ;

LITERAL : '\'' ( ~'\'' )* '\'' ;
IDENTIFIER : [a-zA-Z0-9_]+ ;

An example of a query is (note the quotes):

--query "color='GREEN' and not name='exclude this' or secret.type='FILE'"

The available filter properties can be found in the OpenAPI definition under the /keyhub/rest/v1/vaultrecord path.

26.4. Use vaults

Access to the vaults can be achieved by the various vault-commands

> keyhub help vault
NAME
        keyhub vault - Access vaults in Topicus KeyHub

SYNOPSIS
        keyhub vault { cp | export | import | list | lock | mv | read | rm |
                share | unlock | write } [--] [cmd-options]

        Where command-specific options [cmd-options] are:
            cp: --record <recordUuid> [ --personal ] [ --client ] [ --group <group> ]
                    [ --target-account <targetAccount> ] [ --target-group <targetGroup> ]
                    [ --output <output> ]
            export: [ --file <file> ] [ --personal ] [ --client ] [ --group <group> ]
                    [ --output <output> ]
            import: --file <file> [ --personal ] [ --verbose ] [ --client ] [ --group <group> ]
                    [ --output <output> ]
            list: [ --personal ] [ --client ] [ --group <group> ] [ --output <output> ]
            lock:
            mv: --record <recordUuid> [ --personal ] [ --client ] [ --group <group> ]
                    [ --target-account <targetAccount> ] [ --target-group <targetGroup> ]
                    [ --output <output> ]
            read: [ --type <type> ] [ --record <recordUuid> ] [ --query <query> ]
                    [ --personal ] [ --client ] [ --group <group> ] [ --output <output> ]
            rm: --record <recordUuid> [ --personal ] [ --client ] [ --group <group> ]
                    [ --output <output> ]
            share: --record <recordUuid> [ --personal ] [ --client ] [ --group <group> ]
                    [ --target-account <targetAccount> ] [ --target-group <targetGroup> ]
                    [ --output <output> ]
            unlock: [ --client-secret <clientSecret> ]
            write: [ --password <password> ] [ --record <recordUuid> ] [ --filename <filename> ]
                    [ --file <file> ] [ --color <color> ] [ --client ] [ --totp <totp> ]
                    [ --username <username> ] [ --warningperiod <warningPeriod> ]
                    [ --personal ] [ --name <name> ] [ --group <group> ] [ --comment <comment> ]
                    [ --url <url> ] [ --enddate <endDate> ] [ --output <output> ]

        See 'keyhub help vault <command>' for more information on a specific command.

When during login the option --store-secret has not been passed, the vault needs to be opened explicitly with th unlock-command:

> keyhub help vault unlock
NAME
        keyhub vault unlock - Unlock the vaults.

SYNOPSIS
        keyhub vault unlock [ --client-secret <clientSecret> ]

OPTIONS
        --client-secret <clientSecret>
            The client secret as issued by KeyHub, use '-' for a prompt.

To close the vault, the lock-command can be used:

> keyhub help vault lock
NAME
        keyhub vault lock - Lock the vaults.

SYNOPSIS
        keyhub vault lock

26.4.1. Read and write passwords

All vaults can be accessed via the CLI that are also available via the browser. The CLI can have access to multiple group vaults and always has access to the personal vault or a client-linked vault. The latter is the equivalent of a user’s personal vault. The client-bound vault cannot be read by users and/or other CLI clients. The commands for accessing passwords in vaults all expect one of the following options: --personal,` --client or` --group <UUID>. These options select respectively the user’s personal vault, the client-bound vault and the group’s vault with the giving UUID.

To list all passwords from al vault, use the vault list-command:

> keyhub help vault list
NAME
        keyhub vault list - Lists the records in a vault.

SYNOPSIS
        keyhub vault list [ --client ] [ --group <group> ]
                [ --output <output> ] [ --personal ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified

This command will not show the password, file or secret, only the metadata will be returned. To retrieve the actual password, file or secret, the vault read-command should be used:

> keyhub help vault read
NAME
        keyhub vault read - Reads a record in a vault.

SYNOPSIS
        keyhub vault read [ --client ] [ --group <group> ]
                [ --output <output> ] [ --personal ] [ --query <query> ]
                [ --record <recordUuid> ] [ --type <type> ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --query <query>
            A query for the record to read.

            This option is part of the group 'query' from which only one option
            may be specified



        --record <recordUuid>
            The record to read (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'query' from which only one option
            may be specified



        --type <type>
            The type of secret to display.

With vault write new or modified passwords can be stored.

> keyhub help vault write
NAME
        keyhub vault write - Creates or updates a record in a vault.

SYNOPSIS
        keyhub vault write [ --client ] [ --color <color> ]
                [ --comment <comment> ] [ --enddate <endDate> ]
                [ --file <file> ] [ --filename <filename> ] [ --group <group> ]
                [ --name <name> ] [ --output <output> ]
                [ --password <password> ] [ --personal ]
                [ --record <recordUuid> ] [ --totp <totp> ] [ --url <url> ]
                [ --username <username> ] [ --warningperiod <warningPeriod> ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --color <color>
            The color of the record.

            This options value is restricted to the following set of values:
                NONE
                GREEN
                RED
                BLUE
                DARK
                PINK_LAVENDER
                CRIMSON_RED
                MIDDLE_YELLOW
                ANDROID_GREEN
                SAGE
                ARTICHOKE


        --comment <comment>
            A comment on the record, use '-' for stdin.


        --enddate <endDate>
            The end date for the record, formatted as yyyy-mm-dd.


        --file <file>
            The file to store with the record, use '-' for stdin.


        --filename <filename>
            The filename to be set on a record of type FILE.


        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --name <name>
            The name of the record.


        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --password <password>
            The password to store with the record, use '-' for stdin.


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --record <recordUuid>
            The record to update (UUID).

            This options value must have a length of 36 characters



        --totp <totp>
            The TOTP secret to store with the record, use '-' for stdin.


        --url <url>
            The URL to be set on the record.


        --username <username>
            The username to be set on the record.


        --warningperiod <warningPeriod>
            How far in advance Topicus KeyHub should start displaying expiry
            warnings.

            This options value is restricted to the following set of values:
                AT_EXPIRATION
                TWO_WEEKS
                ONE_MONTH
                TWO_MONTHS
                THREE_MONTHS
                SIX_MONTHS
                NEVER

To retrieve a list of passwords and then read one of these passwords, the following commands can be used:

> keyhub vault list --client
Vault for https://keyhub.example.org/keyhub/rest/v1/client/1024108
RECORD                                 NAME       URL                  USERNAME   SECRETS
3cb167c0-718a-4bee-908e-e35154478893   password   http://example.com   usn        P  C
> keyhub vault read --client --type PASSWORD \
    --record 3cb167c0-718a-4bee-908e-e35154478893
secretreadfromstdin

26.4.2. Copy, move and share passwords

With the commands vault cp, vault mv and vault share, passwords can be copied, moved and shared respectively. The options for these commands are identical.

> keyhub help vault cp
NAME
        keyhub vault cp - Copies a record from one vault to another.

SYNOPSIS
        keyhub vault cp [ --client ] [ --group <group> ] [ --output <output> ]
                [ --personal ] --record <recordUuid>
                [ --target-account <targetAccount> ]
                [ --target-group <targetGroup> ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --record <recordUuid>
            The record to copy (UUID).

            This options value must have a length of 36 characters



        --target-account <targetAccount>
            Copy the selected record to the targeted personal vault (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'target' from which only one
            option may be specified



        --target-group <targetGroup>
            Copy the selected record to the targeted group vault (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'target' from which only one
            option may be specified

With --personal, --client or --group <UUID>, in combination with --record <UUID>, the password is selected. The target vault is selected with --target-account <UUID> or --target-group <UUID>.

26.4.3. Import and export passwords

With the vault import command, vault records can be bulk imported from a CSV file. The CSV file must contain one vault record per line in the format shown below and must use UTF-8 without BOM as encoding. Fields can be quoted using double quotes to prevent parse errors in case they contain a comma. Do not use a header row or make sure it starts with exactly the values name, color and url. The name and at least one secret (password, totp or comment) is required. The options correspond to those of the vault write command.

name, color, url, username, password, totp secret, end date, warning period, comment

Some examples are:

Repo,RED,https://nu.nl,username1,password1,4334654345,2021-01-01,SIX_MONTHS,
Test account,BLUE,,,password1,,,,"long comment, with quotes"
Drive,,,,,,,,"this has a comment only, defaults to NONE"
Webshop,NONE,,user,pwd,,,,"Use double double quotes like this:"" to get a quote"

> keyhub help vault import
NAME
        keyhub vault import - Imports all records from a CSV file into a vault.
        The CSV file must contain the following fields:
        name,color,url,username,password,totp,enddate,warningperiod,comment.
        See the manual for more information on the expected format.

SYNOPSIS
        keyhub vault import [ --client ] --file <file> [ --group <group> ]
                [ --output <output> ] [ --personal ] [ --verbose ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --file <file>
            The CSV file to import.

            This options value must be a path to a file. The provided path must
            exist on the file system. The provided path must be readable and
            writable.



        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --verbose
            Log every record imported.

A vault can be exported with vault export. The format of the export is the same as that of the import.

TOTP secrets, files, and vault records shared from other vaults are not exported.

> keyhub help vault export
NAME
        keyhub vault export - Exports all records from a vault into a CSV file.
        The CSV file will contain the following fields:
        name,color,url,username,password,totp,enddate,warningperiod,comment.

SYNOPSIS
        keyhub vault export [ --client ] [ --file <file> ] [ --group <group> ]
                [ --output <output> ] [ --personal ]

OPTIONS
        --client
            Use the client's vault. Can only be used when a client is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified



        --file <file>
            Write the contents to the given file.

            This options value must be a path to a file. The provided path must
            be readable and writable.



        --group <group>
            Use the vault for the given group (UUID).

            This options value must have a length of 36 characters


            This option is part of the group 'vault' from which only one option
            may be specified



        --output <output>
            Select the output format.

            This options value is restricted to the following set of values:
                json
                plain
                detail
                csv


        --personal
            Use your personal vault. Can only be used when a user is
            authenticated.

            This option is part of the group 'vault' from which only one option
            may be specified

26.5. Account provisioning

The dynamic provisioning of accounts within Topicus KeyHub can be accessed via the CLI. This is done with the provisioning command group:

> keyhub help provisioning
NAME
        keyhub provisioning - Control account provisioning in Topicus KeyHub

SYNOPSIS
        keyhub provisioning { activate | deactivate | password | rotatepassword
                | status } [--] [ --output <output> ] [cmd-options]

        Where command-specific options [cmd-options] are:
            activate: [ --reason <reason> ] [ --minutes <durationInMinutes> ]
                    --group <groupUuid>
            deactivate: [ --all ] [ --group <groupUuid> ]
            password:
            rotatepassword:
            status: [ --filter <filter> ]

        See 'keyhub help provisioning <command>' for more information on a specific command.

26.5.1. Rotating passwords

With the command provisioning password the rotating password is returned. This password can be rotated with provisioning rotatepassword. For both commands, the user must have the rotating password enabled on the account.

26.5.2. Activating and deactivating accounts via provisioning

Account provisioning can be done using provisioning activate. This command requires an argument --group <UUID> which is the group to activate. An optional --reason <text> argument is used when the provisioning of the selected group requires a reason. The default duration is 1 hour. This can be changed using the --minutes argument.

Deactivation of a group can be done using provisioning deactivate. The argument --group <UUID> is used to select a specific group to deactivate. To deactivate all groups, the --all argument can be used instead.

To retrieve the current status of all groups that can be provisioned, the provisioning status command is used. An example output would be:

> keyhub provisioning status
UUID                                   NAME             STATUS                          REASON         AUTHORIZATION   FOLDER
b82c9778-bec7-4d11-ba99-9cfd9a40c3f1   Product-X Test   active until 2024-06-20 16:30   not required   not required
ca6ed054-8bf5-4596-8f5d-32dac25bb35f   Product-X Dev    inactive                        not required   not required

26.6. Configuration for client credentials

To use the CLI without a user login in, an OAuth2 application should be setup in Topicus KeyHub. Choose the Client credentials grant for this application. Without additional configuration this application can now be used to store vault records in the vault of the application. To access the vaults of groups, the application must first be granted permissions to access the vaults of the groups in question. For more information on this, see the section on permissions for OAuth 2.0 clients.

Virtual appliance

27. Installation - configuration

Welcome to the Topicus KeyHub installation. Login with the 6-digit password displayed at the terminal or serial console of the appliance. If the appliance is not yet deployed a guide can be found in the Best practice guide. The installation wizard will prepare Topicus KeyHub step by step for use.

Use the 'Restore backup' option if a backup from a previous installation is going to be restored. There will be the option to read all configuration from the backup or just import the data.

Figure 155. Welcome to the Topicus KeyHub installation

27.1. Step 1 - Change maintenance password

The first step of the wizard is to change the maintenance password. The current password has been copied from the console during setup. Topicus KeyHub suggests a sufficiently strong password, but choosing a new password manually is possible as well.

Store the new password on a secure location.

Figure 156. Step 1 - Change maintenance password

27.2. Step 2.1 - Configure time

Select the timezone for Topicus KeyHub and configure NTP.

Figure 157. Step 2.1 - Configure time

Timezone: Select the timezone where most of the Topicus KeyHub users are located.
NTP servers: For the operation of Topicus KeyHub it is important that the clock of the machine is set correctly. By default NTP servers from the NTP pool are used. If these are not accessible, or different servers need to be used, these can be set here.

27.3. Step 2.2 - Configure network parameters

The right configuration of the network parameters is of great importance, as an invalid configuration might lead to Topicus KeyHub becoming unavailable.

Figure 158. Step 2.2 - Configure network parameters

DHCP: Select whether Topicus KeyHub operates on a static IP configuration or a dynamic configuration (DHCP)
IP-address: The static ip-address where Topicus KeyHub is located.
Netmask: The netmask for the static configuration.
Gateway: The gateway for the static configuration.
DNS-servers: The list of DNS-servers to be used. Add internal DNS-servers here.
External URL: The URL where Topicus KeyHub can be accessed by users.
Offline: Run the Topicus KeyHub appliance without an active internet connection. For more information, see 'Offline installation'.
Proxied configuration: Select this if Topicus KeyHub operates behind a reverse proxy. For more information, see 'Proxied configuration'.
Hostname: The hostname of the server where Topicus KeyHub is located.
Domain: The domain within which Topicus KeyHub is located.
FQDN: The fully qualified domain name which follows from the configuration above.

27.3.1. Offline installation

It is possible to install and run the Topicus KeyHub appliance without an internet connection. For this, the image that is suitable for offline installation must be used. It is very important for 2FA to function correctly that the Topicus KeyHub appliance clock is synchronized. A reachable NTP server must therefore be set during an offline installation. Since Topicus KeyHub cannot download updates from the internet, the appliance must be manually updated using the update files from the Topicus KeyHub website. These update files contain updates for the Topicus KeyHub application and the underlying OS. Additional OS updates can also be obtained from a corporate repository.

27.3.2. Proxied configuration

When running in a proxied configuration, Topicus KeyHub will listen to the following HTTP headers from the proxy: X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Port. The reverse proxy needs to be configured to set these headers correctly. The management interface will be accessible on the FQDN (combination of hostname and domain), while Topicus KeyHub itself will be accessible at the given external URL. The certificate given at step 2.3 needs to be valid for the FQDN, not the external URL. This certificate will be used to secure the communication between the reverse proxy and Topicus KeyHub. The certificate for the external URL needs to be configured at the reverse proxy. An example configuration for NGINX can be found below.

NGINX example configuration

server {
   listen 80;
   server_name external-url.example.com;
   return 301 https://external-url.example.com/;
}
server {
   include tls-configuration.inc;

   listen 443 ssl http2;
   server_name external-url.example.com;

   access_log /var/log/nginx/external-url.example.com.access.log;
   error_log /var/log/nginx/external-url.example.com.error.log error;

   location / {
      proxy_pass          https://hostname.domain:443;
      proxy_redirect      off;

      proxy_set_header    Host               $host;
      proxy_set_header    X-Real-IP          $remote_addr;
      proxy_set_header    X-Forwarded-For    $remote_addr;
      proxy_set_header    X-Forwarded-Port   $server_port;
	  proxy_set_header    X-Forwarded-Proto  https;
   }
}

27.4. Step 2.3 - Configure server certificates

Topicus KeyHub can only be accessed using a secure connection. Therefore the configuration of server certificates is necessary.

Figure 159. Step 2.3 - Configure server certificates

Let’s Encrypt: Use the free online service Let’s Encrypt to automatically obtain certificates. This option is not available when used in a proxied configuration.
Server certificate: Select the public certificate file (PEM) and the private key file (PEM) or a combined PKCS#12 file. Please refer to the chapter on certificates for more details on the different formats.

Make sure that the certificate that is uploaded is trusted by the current browser as well. Failure to do so may cause step 2.4 to fail.

Certificate Authority(-ies): A complete certificate chain is required for the configuration of the web interface. Specify a PEM bundle here with all the certificates needed to construct the full certificate chain. This bundle must include all certificates from root to the certificate used to sign the certificate selected above. A PEM bundle consists of one or more certificates in PEM format appended one after the other in one file.

27.5. Step 2.4 - Apply configuration

This step applies the configuration and shows the progress of the various steps. If an issue occurs, the previous configuration will be restored.

If the transfer of session fails, there is a good chance that there is an error in the network and/or certificate configuration. The console of the web browser can sometimes contain useful information to find the cause of the problem.

Figure 160. Step 2.4 - Apply configuration

27.6. Step 3 - Start Topicus KeyHub

After successfully applying the configuration, Topicus KeyHub will be started. Various steps will be executed to finalize the configuration and to start the application. It might take up to five minutes to start Topicus KeyHub for the first time.

Topicus KeyHub generates a recovery key to recover access to vaults. This key is required in cases that a user forgot his/her vault password and access to the personal vault has to be recovered. During installation, downloading the recovery key is a mandatory step.

Store the key in a secure location, for example an USB-stick in a physical vault. This key can be used to gain access to all secrets in all vaults in Topicus KeyHub.

It is highly recommended to store the recovery key on two distinct physical places to minimise the risk of losing it. After loss of the recovery key, it will be impossible to recover access to a vault.

Figure 161. Step 3 - Start Topicus KeyHub

27.7. Step 4.1 - Setup primary directory

This step configures the primary directory. Against this directory users are authenticated when logging in to Topicus KeyHub. The fields to configure depend on the selected directory type. In the case of an LDAP or Active Directory, see this chapter for an extensive description of the configurable fields. In the case of an OIDC-directory, see this chapter for an extensive description of the configurable fields.

When restoring a backup, step 4.1 and 4.2 are skipped and the backup is restored instead.

Figure 162. Step 4.1 - Setup primary directory

27.8. Step 4.2 - Register the first user

The first user has to be registered. This user is automatically granted KeyHub Administrator rights after creating the account. The page shows a link to the Topicus KeyHub instance where the first account should be registered. Follow this link or open Topicus KeyHub in a separate browser window and click on register to proceed. Once the first account is created, return to this Appliance Manager to continue to the next step.

Figure 163. Step 4.2 - Register the first user

27.9. Step 5 - Installation complete

If all steps are successfully executed, the installation is completed. It is now possible to login in to Topicus KeyHub and start using the application.

After installation, it is advised to configure e-mail for notifications. E-mail is also required to make use of internal directories.

Figure 164. Step 5 - Installation complete

28. Configuration

All settings chosen during the installation can be changed afterwards via the configuration menu. Modified settings will not be applied directly, but will be staged. To apply the staged settings, press the button with 'changes pending' at the top right corner of the screen. An overview will be shown with all modified settings.

All changes have to be applied explicitly before taking effect.

The configuration page shows all pending changes. Certain changes require a restart of Topicus KeyHub. A notification is shown if this applies.

In order to roll back all changes and thus not to apply them, the Discard button can be used.

Before applying changes, it is wise to make a backup. If this is not desired, this can be disabled.

Figure 165. Apply changes

28.1. Configure the application

General changes to the Topicus KeyHub installation can be modified under Application.

Maintenance mode: Check this box to restart Topicus KeyHub in maintenance mode. During maintenance mode only the keyhub-account can log on to the application when using the maintenance password.

With Topicus KeyHub in Maintenance Mode, regular users are not able to log on to the application.

Memory allocation: Divide the VM’s memory among the different components. The first 6GB of memory has a default allocation that cannot be changed. Of all available memory above 6GB, 50% can be divided between the Topicus KeyHub application and the OS and database. Of the remaining 50%, half is always allocated to the Topicus KeyHub application and the other half to the OS and database.

The memory allocation is the same for all nodes in a cluster. It is therefore important to give all nodes the same amount of memory. This responsibility lies with the administrator.

Example 1. Example calculation

The VM has 10,000 MB of memory available, which is 10,000 - 6,000 = 4,000 MB above the baseline. Of this 4,000 MB, 2,000 MB can be allocated manually.

If 1,500 MB of this is allocated to the Topicus KeyHub application and 500 MB to the OS and database, the result is:

The Topicus KeyHub application gets 2,048 + 4,000 * 25% + 1,500 = 4,548MB.
The appliance manager always gets 512 MB.
The remaining memory, 10,000 - 4,548 - 512 = 4,940 MB, is available to the OS and database.

Overload protection: Sets the sensitivity of the overload protection. The higher the value, the longer it will take before the overload protection intervenes and aborts a request. Higher values require more memory and more CPU cores.

The overload protection protects the application against requests that use excessive amounts of memory or CPU. Increasing the limit will result in such requests being acted upon later. In extreme cases, multiple simultaneous requests could cause the application to run out of memory. We recommend not increasing this value unless strictly required.

Release channel: The release channel can be modified from the stable version, although this is not recommended for normal use. Other options are acceptance and development. Please pay attention to the fact that other release channels are not supported by the manufacturer.
Shutdown on lost quorum: Stop the application on nodes that are not part of a quorum within the cluster. Topicus KeyHub periodically reads the status of Pgpool. If Pgpool loses the quorum and the node is running the primary database, all services on the node will be stopped. This prevents possible data corruption in the event of a split-brain situation. However, if the node was the only running node in the cluster, this action will make the cluster unreachable.
Company repository: If an own RPM repository is used within the company, this can be specified here. This repository can be used as a mirror of upstream repositories for retrieving system updates in offline mode or for providing custom packages.

Figure 166. Configure the application

28.2. Configure the time

This step is equal to the according step during installation. Please refer to the appropriate chapter for further information on the configuration parameters.

Figure 167. Configure the time

28.3. Configure the network

This step is equal to the according step during installation. Please refer to the appropriate chapter for further information on the configuration parameters.

Figure 168. Configure the network

28.4. Configure the firewall

The firewall of the Topicus KeyHub appliance can be configured via the Firewall option. The firewall consists of 3 zones: management, monitoring and backup. Each zone can make certain TCP and UDP ports available for a list of IP ranges.

Misconfiguration of the management zone may make it impossible to connect to Management Console and SSH, making it impossible to roll back the configuration. It is therefore recommended to always take a snapshot of the VM before making changes to this zone.

IP whitelist for firewall for management: These IP-addresses will be whitelisting in the firewall for the management zone. The Management Console of Topicus KeyHub (port 50443) and SSH (50022) are only accessible from IP-addresses in this whitelist. The internal LDAP (port 389) is also part of the management zone.
Exposed TCP ports for management: These TCP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas. Port 50443 (Management Console), port 50022 (SSH), and port 389 (internal LDAP) are part of the management zone.
Exposed UDP ports for management: These UDP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas.
IP whitelist for firewall for monitoring: The monitoring ports can only be accessed from IP addresses in the ranges specified here. Port 9443 is part of the monitoring zone.
Exposed TCP ports for monitoring: These TCP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas. Port 9443, for the metrics and health endpoints, are part of the monitoring zone.
Exposed UDP ports for monitoring: These UDP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas. To expose SNMP, port 161 must be listed here.
IP whitelist for firewall for backup: The backup ports can only be accessed from IP addresses in the ranges specified here. This zone can be used to make a local backup agent accessible.
Exposed TCP ports for backup: These TCP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas.
Exposed UDP ports for backup: These UDP ports will be opened for the IP ranges given above. Multiple ports must be separated by commas.

Figure 169. Configure the firewall

28.5. Configure e-mail delivery

Topicus KeyHub requires a fully operational e-mail configuration for account registrations and for notifications. For this, the e-mail server including potential credentials has to be configured. To verify correct configuration, a test e-mail will be sent after the configuration is applied. This test e-mail can also be sent by clicking on the appropriate button.

The button to send a test email uses the current configuration. If there are still pending changes, they must be applied first.

E-mail server: The address of the e-mail server used to send e-mails from Topicus KeyHub.
Encryption: Indicates if and how the connection to the SMTP server should be encrypted.
Username: If authentication is required to connect to the e-mail server, enter the username here.
Password: If authentication is required to connect to the e-mail server, enter the password here.
Administrator e-mail address: Enter the e-mail address of the administrator of Topicus KeyHub. This e-mail address will be used when the maintenance account is used to log on.
Sender address for E-mail: Enter the e-mail address that the appliance manager must use to e-mail from. Only the appliance manager will use this email address. The address of e-mails from Topicus KeyHub itself is set in the general settings.
Additional Postfix configuration: Specify additional configuration that will be passed in verbatim to Postfix. These parameters must be in the form key = value, with one key-value pair per line. The parameters will be applied last, overriding any other parameters set. Check the Postfix configuration documentation for information on the available parameters.

Figure 170. Configure e-mail delivery

28.6. Configure the certificates

This step is mostly equal to the corresponding step during installation. Please refer to the appropriate chapter for further information on the configuration parameters.

IdP signing certificate: This certificate is used by Topicus KeyHub for signing OAuth2 access tokens, OpenID Connect ID tokens and SAML assertions. Topicus KeyHub automatically generates a certificate that is valid for 5 years. The certificate can be renewed by clicking on 'Regenerate'.

When renewing the Idp signing certificate, all users will be logged out. All access tokens also lose their validity and single sign-on connections can stop working. For some services it may be necessary to manually re-enter the new certificate.

Figure 171. Configure the certificate

28.7. Configure monitoring

Options for enabling and configuring SNMP can be found under Monitoring. The Topicus KeyHub appliance supports the delivery of metrics via OTLP or they can be read from the OpenMetrics endpoint. In addition, the appliance supports both SNMP v2c and SNMP v3 for basic system information of the VM. Using OTLP or the OpenMetrics endpoint is preferred as they provide more information.

These options are available for OTLP:

Enable OTLP: Send monitoring information and metrics via OTLP to the endpoint below.
OTLP endpoint: The OTLP endpoint to send the metrics to.
TLS: Secure the connection with TLS, optionally with a client certificate.
Certificate authority(-ies): Provide a PEM bundle with all the certificates needed to construct a complete certificate chain from root to the final certificate.
Client certificate: The certificate that KeyHub uses to authenticate to the OTLP server.

These options are available for SNMP:

Enable SNMP v2c: Make monitoring information available via SNMP v2c.

V2c is not encrypted and the community string only offers very limited protection.

SNMP v2c community: The community string under which the information is made available. This value will have to be entered in the monitoring system in order to be able to read the information.
Enable SNMP v3: Make monitoring information available via SNMP v3. Authentication is protected with SHA and the traffic is encrypted with AES.
SNMP v3 username: The username for authenticating with SNMP v3.
SNMP v3 password: The password for the above username for authenticating with SNMP v3.
SNMP v3 privacy password: The password with which the data is encrypted. If left blank, this is the same as the user password.

Figure 172. Configure monitoring

28.7.1. Metrics and health endpoints

The Topicus KeyHub appliance provides a number of endpoints with information about the status of the application:

https://external-url.example.com:9443/metrics: The OpenMetrics endpoint provides metrics of, among other things, CPU and memory usage of KeyHub in the OpenMetrics format.
https://keyhub-node-x.local:9443/health/live: Indicates if the node is running properly.
https://keyhub-node-x.local:9443/health/ready: Indicates if the node is able to handle traffic.

Port 9443 is only accessible for IP addresses in the IP whitelist for the monitoring zone.

28.8. Configure backups

Options for enabling and configuring how the Topicus KeyHub appliance should operate in combination with a backup solution can be found under Backups. This is all about making the backups accessible. The actual creation of backups can be done manually or automatic. Backups are placed in the /data/tkh/backup directory. It is possible to download these backups via scp, sftp or rsync via the user keyhub-backup. Another possibility is to use a specialized backup agent that needs to be installed on the system.

It is possible to make changes to the OS of the Topicus KeyHub appliance that interfere with the correct operation and/or security of Topicus KeyHub. The making of such changes, such as installing additional packages, is entirely at the risk of the customer.

Backup retention: The number of backups to keep before the oldest backup is removed. Retaining too many backups can cause the disk of the Topicus KeyHub appliance to fill up.
Encrypted backups: Encrypt the contents of the backups.

Make sure the decryption key is stored in a safe location. Without this key it will be impossible to restore a backup.

Create backup user: Create a user with the name keyhub-backup.

Protocols such as scp, sftp and rsync operate via ssh over port 50022. The firewall configuration for this port must be set in the network configuration.

Password backup user: The password for the user with the name keyhub-backup. A suggestion is shown for a sufficiently strong password. It is also possible to choose a different password.
SSH key for backup user: An optional SSH public key for the backup user. When set, this key can be used for a passwordless login for keyhub-backup.

Figure 173. Configure backups

28.9. Configure log forwarding

The Topicus KeyHub-appliance can be configured to automatically forward logs to an external server. These options can be found under Logging. This concerns the system logs, as well as the Wildfly-containers' logs. These logs will be streamed over TCP to the configured server and port. The format used will be RFC5424 with octet-counted framing. This TCP-connection can be secured using TLS. If mTLS is used, both the client and server certificate must be signed by the same CA.

The logs will also remain available on the log volume.

Send logs to remote server: If enabled, the logs are immediately forwarded to another system.
Server address: The address of the server to which the logs should be delivered.
Server port: The TCP port to which the logs should be delivered. Port 1468 is a commonly used port for syslog.
Template: Configure an alternative template for the format of the syslog messages. By default, the template RSYSLOG_SyslogProtocol23Format is used. Refer to the RSyslog manual for available templates.
TLS: Secure the connection with TLS, optionally with a client certificate.
Certificate authority(-ies): Provide a PEM bundle with all the certificates needed to construct a complete certificate chain from root to the final certificate. This chain must be used both for the log server’s certificate and, if appropriate, for the client certificate.
Client certificate: The certificate that KeyHub uses to authenticate to the log server.

Figure 174. Configure logging

28.10. Configure authentication

28.10.1. Change the authentication information for maintenance

The maintenance password can be modified here. This password is used to log on to Topicus KeyHub while in Maintenance Mode. Pick a strong password and store this in a safe location, for example on two USB-sticks which are stored in a physical safe. A public key can be specified for logging in via SSH.

Figure 175. Configure the maintenance password

28.10.2. Configure SSO with Topicus KeyHub

The appliance manager supports authentication using Single Sign-on with Topicus KeyHub. This allows sign-on with a single click. By default the appliance manager application is not linked to a group in Topicus KeyHub, which is required for SSO. To link the application, login to Topicus KeyHub as KeyHub Administrator and go to 'Manage access'. Here, open the 'KeyHub Appliance Manager', which can be found under the 'KeyHub Administrator' group. Add a group under the 'Groups' section of this application. All users in this group will now have access to the Topicus KeyHub Appliance Manager through Single Sign-on.

29. Deployment

Under Deployment, insight is given about the use of the virtual machine(s) on which Topicus KeyHub runs. Here, it is possible to view disk usage and allocate extra space if necessary. It is also possible to setup a cluster for high availability.

29.1. Disk management

The Topicus KeyHub virtual appliance comes standard with a disk of 80GiB. This disc is divided into 6 parts:

/ (root): The root filesystem of 24GiB. This contains the OS, the data files of Topicus KeyHub and the backups.
/var/log: The 15GiB log file system. Here the logging is written from the OS and the various parts of Topicus KeyHub.
/var/lib/docker: The 24GiB docker file system. This contains all docker images, temporary volumes and other data used by docker.
swap: The swap partition of 2GiB.
/boot: The 2GiB boot partition.
Reserved space: The remaining space, approximately 12GiB, is reserved for snapshots taken during an update.

Figure 176. Disk Management

With long-term use of Topicus KeyHub or in larger organisations, the standard disk size may not be sufficient. The database and backups, in particular, can increase significantly in size, causing the root file system to fill up. Via disk management it is possible to allocate extra space to Topicus KeyHub. To do this, first enlarge the disk via the used virtualization environment. In some environments this can be done without shutting down the VM. In that case, click on 'Rescan disk' after enlarging the disk to notify Topicus KeyHub of the changed size. The unallocated space will be shown in the bottom row of the table.

To allocate 'unallocated' space to a volume, click on 'Allocate disk space'. Space can be assigned to /, /var/log, /var/lib/docker and the reserved space. In most cases the space will be allocated to / and in some cases to /var/log. Allocating space to /var/lib/docker is not necessary under normal conditions. Since the reserved space is used during update to keep a snapshot of / and /var/lib/docker, it is advised to allocate some of the space to this. By default, 80% of the available space will be allocated to / and 20% to the reserved space. Divide all available space among the volumes as desired and click 'Assign'.

Always take a snapshot of the VM before allocating the disk space. The snapshotting system of the Topicus KeyHub appliance is unable to recover from an error while allocating disk space.

All available space must be allocated at once. It is not possible to leave part of the unallocated space unused.

Figure 177. Allocate disk space

29.2. Replication

For KeyHub to run in a cluster, the network settings need to be set to static. Nodes changing ip address will break the cluster; therefore, DHCP is not supported. This also means that running a cluster on Azure is currently not supported.

Topicus KeyHub can be run in a cluster for high availability. For the highest reliability, this cluster should consist of an odd number of nodes with a minimum of 3. All nodes in the cluster are equivalent. This means that all nodes can handle requests from all users and all nodes must be able to connect to the same services such as Active Directories and LDAP servers. The nodes communicate with each other over 2 ports. Both ports must be accessible to all nodes from all other nodes in the network.

50022/tcp (ssh): For exchanging configuration and executing remote administration commands.
51871/udp (wireguard): For a secure overlay network over which the cluster nodes communicate with each other.

A load balancer must be set up to distribute the traffic over the nodes in the cluster. For this, Topicus KeyHub must be setup in a proxied mode. The load balancer can use a node’s health endpoint to determine if the node is capable of handling traffic.

Since each node runs on its own internal host, each node needs its own certificate. The certificates for the different hosts must all be issued by the same CA. It is not possible to run a cluster with self-signed certificates.

29.2.1. Setting up a cluster

To set up a cluster, a new VM must first be imported. This VM must be running the exact same version as the VM that is currently the cluster coordinator. If the current VM is not running the latest version of Topicus KeyHub, it is advised to upgrade first before starting the cluster configuration. A certificate is also required for the new VM, the network settings must be known and the DNS must be configured.

Adding a new node requires all current nodes in the cluster to restart their services. This will interrupt the service to users.

On the cluster overview, select Change and then Add.

Figure 178. Welcome to the cluster wizard

Step 1 - Establish link

When establishing the link, the keys are exchanged between the current and the new VM.

Figure 179. Step 1 - Establish Link

To do this, enter the following information:

IP address: This is the current IP address of the VM. This can be an IP address automatically assigned to the machine via DHCP. The current IP address can be found on the console of the VM.
Password: The password assigned to this VM. This password is a 6-digit code displayed on the console of the VM.

During setup, a connection is setup once via SSH with password authentication. This option must be enabled temporarily on the new node by pressing 'P' on the terminal. Eventually, the new node will get the same configuration as the cluster coordinator.

Step 2.1 - Configure network parameters

Set the network parameters for the new VM. Refer to relevant chapter of the installation manual for a description of the different fields. With a cluster setup it is not possible to choose DHCP for the network configuration.

Figure 180. Step 2.1 - Configure network parameters

Step 2.2 - Configure server certificates

Specify the server certificate for the new VM. Refer to appropriate chapter of the installation manual for a description of the different fields.

Figure 181. Step 2.2 - Configure server certificates

Step 2.3 - Apply the given configuration

Apply the configuration for the new VM. Once the configuration has been completed, a number of tests will be performed to test the connectivity between the machines.

Figure 182. Step 2.3 - Implementing the configuration

Step 3 - Start replication

Configure all current cluster nodes to include the new node and start replication. At this step, all nodes in the current cluster will be restarted to load the new configuration.

Figure 183. Step 3 - Start replication

29.2.2. Cluster overview

The cluster overview shows all nodes and general information about the cluster. If a problem is found with one of the nodes, this will also be displayed. Clicking on a node will give a detailed view about that node.

Figure 184. Cluster overview

29.2.3. Modify the cluster

Changes to the cluster can be made by clicking on Change on the cluster overview. In addition to adding and removing nodes, it is also possible to temporarily disable nodes or take them out of service. Disabling nodes can be used to restore a quorum in a cluster where some of the nodes have failed. A node that is not available will continue to run but notify the load balancer that it is not available.

The user must ensure that the disabled nodes are no longer active. If the disabled nodes are not taken out of service, there is a possibility that multiple primary databases are active within the cluster. The split timeline that is created in this way cannot later be reduced to a single timeline without loss of data.

Nodes that are temporarily out of use can be reactivated later. It is possible that after reactivation the database on some nodes does not get the correct status. Follow the instructions in the interface to get the cluster back to a healthy state.

Deactivating nodes requires all other nodes in the cluster to restart. This will cause an interruption of the service. Updating the availability can be done without interruption.

Figure 185. Modify the cluster

29.2.4. Node Details

The node details display detailed information about a node in the cluster. The information is split into 3 sections: general information, information about Pgpool and information about the database.

Figure 186. Node details

The general information consists of the following fields:

Identifier: The code with which the node is known within the cluster. This code is automatically generated when importing a VM and cannot be modified.
External IP address: The external IP address of the VM. This is the IP address with which the VMs communicate with each other.
Cluster link address: The internal IP address of the VM within the secure overlay network. A secure Wireguard overlay network is set up between the nodes in a cluster. Replication of the database and the clustering of Pgpool and WildFly is performed over this network. Each node gets its own IP address within this network.
Cluster link address reachable: Indicates whether or not the node’s cluster link address is reachable from the cluster coordinator. If this address cannot be reached, the node will not be able to participate in the cluster. See the recovery chapter for more information.
Topicus KeyHub version: The version of Topicus KeyHub on this node.
Application status: Indicates whether the Topicus KeyHub application is reachable on this node. Available means that the application is running and technically capable of handling requests.
Availability: Indicates whether the Topicus KeyHub application is available within the load balancer.

The following fields are shown for Pgpool:

Name: The internal name of the Pgpool instance on this node.
Status: The current status of the Pgpool watchdog on this node. Normally this will be 'Leader' or 'Standby'. Consult the Pgpool documentation for an explanation of all statuses.

The information about the PostgreSQL database consists of the following fields:

Status: The status of the database backend as reported by the Pgpool watchdog leader. Normally this will be 'Up' or 'Waiting'.
Role: Primary or standby.
Primary database: When this node is running a standby database, the cluster link address of the primary database is shown here.
Replication delay: When this node is running a standby database, the difference in PostgreSQL’s log sequence number between the primary and this standby node.
Replication status: When this node is running a standby database, the status of the replication. This should always be streaming / async.
Last status change: The moment of the last status change of this PostgreSQL backend.
First audit record at: The timestamp of the first audit record in the database on this node.
Last audit record at: The timestamp of the last audit record in the database on this node.
Database size: The size of the PostgreSQL database on this node.

29.2.5. Recovering from problems

The Topicus KeyHub appliance tries to keep the cluster in a consistent state. Sometimes, however, it can happen that a malfunction occurs on or between the nodes. In many cases, the cluster can automatically recover from such a failure. However, in some cases it is required to perform manual recovery actions.

Cluster link unreachable: The node’s cluster link address cannot be reached. This can have a wide variety of causes. It may be that the node itself is offline, the network connection to the node has been lost or that network traffic is being blocked. It is not possible to automatically fix this condition. Check the status of the VM and network connections. As soon as the node is available again, this will be displayed.
No primary database: There is no primary database in the cluster. This could be caused by the primary database going offline at a time when the Pgpool cluster had no quorum. First try to resolve the cause of the failure by repairing the node that was running the primary database. If this does not work, promotion of a standby node to primary is available. Note that if this node was behind in replication, data can be lost. To force promotion, open the appropriate node and click the 'Force promotion' button.
Multiple primary databases: There are multiple primary databases in the cluster. This can occur if the node with the primary database goes offline, a new primary database is chosen, and the original node reenters the cluster. Although Pgpool tries to avoid this situation, this is not always possible. For recovery it will have to be chosen which database is to be deleted. Go to the node that is incorrectly primary and click on the 'Restore database' button. The database on the node will be deleted and restored from another primary database. If there are more than 2 primary databases, this will have to be done for all nodes except the real primary database. See Restoring a database for more information on resolving this problem.
Database offline: The database on the node is not reachable. Something probably went wrong with the database on that node during a failover or outage. Click on the 'Restore database' button to reinitialize the database. The database on the node will be deleted and restored from the primary database. See Restoring a database for more information on resolving this problem.
Database inconsistent: Replication on the node is not working. The replication delay will show a number greater than 0. There may be or has been a network outage between the node and the primary database. Check whether there are currently no problems with the connection between the nodes. In the event of a temporary failure, the replication will automatically recover and the replication delay will drop to 0. If the replication is not resumed and there is no failure in the network (anymore), database restoration is available. Click on the 'Restore database' button to reinitialize the database. The database on the node will be deleted and restored from the primary database. See Restoring a database for more information on resolving this problem.
Wrong primary: The database on the node is standby but is not following the primary database of the cluster. This can occur if a failover occurred while this node was offline. The cluster has moved to a different primary database and this node is not aware of the change. Click on the 'Restore database' button to reinitialize the database. The database on the node will be deleted and restored from the primary database. See Restoring a database for more information on resolving this problem.
Pgpool offline: Pgpool is not running on the node. With larger network problems within the cluster it can sometimes happen that Pgpool does not start properly. Click on the 'Restore Pgpool' button to restart Pgpool. To ensure that Pgpool forms the cluster properly, it may be that several Pgpool nodes are restarted. This can cause a short interruption of the availability of Topicus KeyHub. If Pgpool is offline on the cluster coordinator, the entire cluster overview will not show any data. In that case open the node that is cluster coordinator and restore Pgpool there.

29.2.6. Restoring a database

If there is a problem with the database on one of the nodes, it can be stored. When restoring a database, it will be deleted from the node and then reinitialized from the primary database. In the event of a (hardware) failure on the specific node or a communication problem with the node, this action can be performed safely. In these situations, the database will lag behind the rest of the cluster. With more complex problems, such as a split in the network, the node may contain data that is not in the primary database. Restoring in such a situation may result in unrecoverable data loss.

After clicking on 'Restore database' the screen will be displayed for restoring a database. Here at the top data of the current primary database is shown and at the bottom data of the database that will be overwritten. If a discrepancy is found between these data that cannot be logically explained from the database lagging behind, a warning is displayed.

Always check carefully that the data shown is logical for the database to be restored. Restoring a database will irretrievably delete all data in overwritten database.

Before the database is overwritten, an attempt will be made to make a backup of the data in the database. This backup is written to /data/tkh/backup on the selected node.

Since there is a problem with the database that will be overwritten, no guarantees can be given about the contents of the backup. If the database server is not running or the data directory is corrupt, the backup will be empty.

Figure 187. Restoring a database

29.2.7. Deleting a node

Open the node details and click remove to remove a node from the cluster. The node does not have to be online to be removed. If the node is still active, it will be shut down first. Removing a node requires all services to restart on the other nodes in the cluster.

Figure 188. Deleting a node

29.2.8. The cluster coordinator

The first node in the cluster is assigned the role of cluster coordinator. Configuration changes, management of the cluster and management of the cron jobs are done on the cluster coordinator. This node will also run the configured jobs. Backups will therefore be made on the cluster coordinator. It is possible to transfer the role of cluster coordinator to another node in the cluster. To do this, log in to the appliance manager on the specific node. The message shown below will be visible. Click on 'Promote to cluster coordinator' to transfer the role of cluster coordinator to this node.

Figure 189. Cluster coordinator

30. Updates, Backups and Support

30.1. Dashboard

The dashboard shows the status of the Topicus KeyHub appliance at a glance. This page shows the current version of Topicus KeyHub, the number of available system updates and the settings for updates and backups. Topicus KeyHub does not automatically check for updates if not configured to do so. To manually check for updates, use the button Check for updates.

If an update for Topicus KeyHub is available, it will be shown next to the current version.

Before installing system and/or Topicus KeyHub updates, a backup is always made first. A temporary snapshot of the system is also made, which is automatically restored when an error is detected.

Figure 190. Appliance dashboard

30.2. Cron jobs

Topicus KeyHub can automatically make backups and/or install updates. The schedules for these tasks are specified in the so-called cron format. This format consists of 5 fields, separated by spaces. These fields represent, in order: minute (0-59) hour (0-23) day-of-month (1-31) month (1-12) and day-of-week (0-7, 0 and 7 for Sunday). A range is specified with n-m or for the full range. A range can be limited to an interval by means of /x, eg. /5 for every 5 minutes. Multiple values and/or ranges can be combined with commas.

With automatic updates, it is possible to specify some options in addition to switching the updates on and off:

System updates: Install system updates for the underlying OS. It is highly recommended to do this at least once a week.
Topicus KeyHub updates: Automatically install Topicus KeyHub updates from the configured distribution channel. Topicus KeyHub will be unavailable for some time during an update. These updates need to be performed during an appropriate service window.
Reboot: With some updates, such as a new version of the kernel, it is required to restart the system in order to complete the update. By checking this option the system will automatically restart after installing updates, if required. Naturally, Topicus KeyHub will be temporarily unavailable during a restart.

Figure 191. Cron jobs

30.3. Backups

This page shows an overview of the backups made. The name and size of each backup is shown. If a backup needs to be restored that is not shown in the list of backups, the backup can be uploaded manually via the Upload button. It is also possible to create a new backup via the button Create. By clicking on the name of the backup it can be downloaded.

Figure 192. Backups

Detailed information, including the corresponding version of Topicus KeyHub and the date on which the backup was made, can be viewed by opening the backup. The relevant backup can then be restored via the Restore button. Before the backup is restored, Topicus KeyHub first creates a new backup. If problems occur while restoring the selected backup, the current version will be restored automatically. When restoring a backup, a choice is offered to restore the database and the configuration of the appliance or just the database.

Figure 193. Restoring a backup

30.4. Support

If problems occur when using Topicus KeyHub, it may be necessary to view or download log files. Via the option Support, these files can be accessed and dumps can be made for support from Topicus.

30.4.1. Logs

Topicus KeyHub keeps a wide range of information in different log files. These log files can be viewed and/or downloaded. By default only the log files of Topicus KeyHub are shown, but the system logs are also available.

Figure 194. Logs

30.4.2. Support Dumps

A support dump contains all logging for a full day and current status information. In a cluster setup, the dump contains this information for all nodes in the cluster. By default, support dumps are encrypted, so they can easily be sent over an unsecured channel. Encrypted dumps can only be opened by Topicus Security employees.

Figure 195. Support Dumps

30.5. Actions

To reboot or shutdown the VM, the corresponding buttons can be used. The button to update the configuration performs a complete synchronization of the configuration of the VM. With this synchronization, all parts of the VM are checked and straightened if necessary.

If a hotfix is made available, it can be applied to the system via 'Apply hotfix'. Only apply a hotfix after explicit instructions from Topicus Security.

Figure 196. Actions

Appendix A: Database integrity

The Topicus KeyHub database is protected against unauthorized changes. Important parts in the database are digitally signed. This signature is checked in the background and on user interaction. If errors are found with these checks, they are recorded in the audit log. It is also possible to send these errors directly to a monitoring system via a webhook. Topicus KeyHub will only report errors and not correct them. Users affected by these errors will receive a notification on their dashboard via which the signatures can be repaired.

It is important to realize that it is not possible for Topicus KeyHub to determine the cause of the error. There is a possibility that unauthorized changes have been made to the database. It is therefore important to review the records in the audit log and to check whether the groups in Topicus KeyHub are still correct. When signature mismatches are reported, it is also a good idea to contact the supplier.

31. Copyright notices

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.