Introduction
Welcome to the Topicus KeyHub manual.
Topicus KeyHub ensures the authentication and authorisations of users. This manual describes how it works.
Topicus KeyHub principles
Topicus KeyHub works according to the principle central authentication, decentral authorisation. This means that every user authenticates against a single identity provider. After authentication that user will be granted authorisation and permissions according to the various groups of which he/she is a member. These groups are managed by various group managers, who are responsible for their group.
At Topicus KeyHub safety is key. This means that two-factor-authentication is required. Every user has to have at least one compatible two-factor-authentication method available. Topicus KeyHub supports both TOTP and WebAuthn protocols. For WebAuthn, any FIDO2 compatible device can be used. Examples are the USB security keys as sold by Yubico, Feitian and Google, among others. For TOTP there are also multiple solutions available, such as the Topicus KeyHub mobile app or the Google Authenticator-app. |
Layout of this manual
This manual is devided into several parts. After the Getting Started section where many tips and tricks are described, the next part is all about the functionality for regular users. This contains chapters about registration of new accounts and the daily use of Topicus KeyHub. The section that follows is especially for KeyHub-administrators and group managers who can performed advanced tasks like setting up new single sign-on connections. Finally the last section contains information about the Open Virtual Appliance (OVA).
Getting Started
Registration
Topicus KeyHub supports just-in-time account registration. Just follow the URL for your specific Topicus KeyHub instance (something like https://keyhub.<your_organisation>.com), enter your username and just follow the steps on the screen. The username is probably the same as the one you need for your corporate email.
Browser extension
Topicus KeyHub comes with a browser extension for Google Chrome and Mozilla Firefox. With this extension applying passwords and 2FA-codes becomes even easier. Go to www.topicus-keyhub.com/browser-extensions and click on the extension for your browser.
After installing the extension, go to Topicus KeyHub and in 'Profile > Settings' you can enable the browser extension by connecting Topicus KeyHub with it.
You can test the browser extension by clicking on the icon in the top-right corner of your screen. If successfully connected, all your password vaults should become visible.
Mobile app
If your organisation uses the 2-factor authentication solution of Topicus KeyHub, you can download the Topicus KeyHub-app to your phone. You can find the app in the respective app-stores of Apple and Android. With this app installed, you will receive a push-notification when Topicus KeyHub requires it. Just click 'Login' in the notification and you are logged in.
If you do not want to install the Topicus KeyHub-app, you can also use a similar TOTP-based app like the Google Authenticator or Microsoft Authenticator as a two-factor authentication solution. Although these apps work fine themselves, you will not receive a push-notification and you are required to manually enter the 6-digit code.
Security keys
In addition to TOTP-based solutions, you can also use a FIDO2 compatible security key for 2-factor authentication. Topicus KeyHub fully supports the WebAuthn protocol, which means that you can use any compatible hardware security key (sometimes also called a "dongle").
On some devices your operating system can even function as a software security key, which means you can use, for example, the built-in fingerprint scanner as your second factor.
Manual
Topicus KeyHub comes with this context-sensitive manual. This means that whenever you press the questionmark-symbol at the bottom-left in Topicus KeyHub, this manual opens in a new browser tab at the corresponding section.
Personal vault
Topicus KeyHub comes with a personal vault which is like your password manager. You can find this vault in the Vault-section and this safe is meant for all your personal, professional credentials. For example your username/password for your time management, sick-leave application or all other applications you use with your personal credentials.
NOTE: You can store the recovery codes for your hard drive encryption in the personal safe as well!
Groups in Topicus KeyHub
In Topicus KeyHub all authorisations are assigned through groups. Every group could provide access to one or more single sign-on applications, servers and/or a password safe for that group. The responsibility for the access a group provides and for its members are in the hands of the group manager(s). You can request access to the groups you require. Navigate to My Groups and click on 'Request'. Now a list of all groups is shown, grouped by group name. Click on a specific group, enter an optional reason and click on the 'request access' button to request access to that group.
A group access request has to be approved by one of the respective group managers. |
Passwords and group vaults
Besides your personal vault Topicus KeyHub contains group vaults as well. Every group has its own vault to store and share passwords, 2FA-codes and files with other group members. Whenever you want to store a new secret like a password in Topicus KeyHub, you decide which group this secret belongs to and create a new vault record. Topicus KeyHub offers a password generator to generate strong secrets for new or updated credentials. After saving a new vault record in a group vault, every member of that vault immediately has access to that secret.
Vault records support storing files as well. Consider storing SSL-certificates and other sensitive data in a specific vault. |
Profile and settings
In Topicus KeyHub every user has its own profile settings under Settings at the bottom left of the Topicus KeyHub interface. Here you can change your language-settings, upload your SSH-key and consult your active sessions and user ids.
Changing your phone
Whenever you have to change phones, you will need to register your new device to generate 2FA-code again. If you still have your old phone in possession, you can easily reconfigure your 2FA from your Profile-page. If you lost your old phone, you can request a 2FA-reset from the Topicus KeyHub login-screen. Such requests always require another user from your organisation to approve them.
SSH-keys
Topicus KeyHub offers the possibility of uploading your SSH-key. This key is provisioned when a group is activated that grants access to a UNIX-based system. After activating the group, you can logon using your SSH-key.
Group managers
Every group should have at least one group manager, and preferably two or more. A group manager is responsible for all members of that specific group and for all the access that group provides. Group managers can approve or decline group-access-requests and assign new group managers.
Usage
1. Registration and authentication
In order to use Topicus KeyHub an account is necessary. There are two ways of obtaining an account: by manual registration or with an activation code.
Both options are available on the login screen.
1.1. Registration
In most cases an account for Topicus KeyHub can be registered manually. Following the Register option on the screen a three-step workflow is presented to setup an account.
1.1.1. Step 1: Create account
Every Topicus KeyHub account is validated against an existing 'user directory', most likely an LDAP or Active Directory. To create a new Topicus KeyHub account, the corresponding directory should be chosen first. In most cases only one option is available and the default selection will be the right one.
When registering an account at an LDAP-directory, the username and password of the corresponding user should be entered. If these credentials are unknown: it is probably the same username and password that are used for e-mail or logging on to the network of the company.
If the account is located in an external directory, the screen displayed above will be shown. The user is required to follow the link to logon to the external directory. After authenticating against the external directory, the user will be guided back to Topicus KeyHub and the corresponding username is shown.
It is possible to enable editable usernames. In that case the user is free to change ths username to a value of his/her liking. Be cautious though, because this username will be user throughout Topicus KeyHub and this username is also to be used when logging on to linked systems. It is not possible to change the chosen username. |
After the credentials are validated, the method of password usage can be chosen.
When using Topicus KeyHub against a LDAP-directory, the option exists of choosing a different password for Topicus KeyHub. This password can be different from the password with witch the authentication took place. In most cases it is not advised to choose a different password and the default settings will suffice.
For external directories it is mandatory to choose a password for Topicus KeyHub This password will be used to encrypt the password safes and to create accounts on linked systems.
See chapter chapter 5 for more details and possibilities on password usage.
Choosing the password concludes step 1.
1.1.2. Step 2: Setup Two-factor authentication
The second step in the registration process is to setup two-factor authentication (2FA). For this step either a security key, or a smartphone with a 2FA-app compatible with the TOTP-protocol can be used Any FIDO2-compatible security key should work. For TOTP, the Topicus KeyHub-app is recommended as this app supports push-notifications. With this app the user only needs to enter Yes or No in order to verify a logon request instead of typing a 6-digit code. Alternative apps that are supported are Google Authenticator, Duo Mobile and the Microsoft Authenticator.
If Topicus KeyHub authenticates against an external directory, it might be possible to skip step 2. This is most likely due to the fact that the external directory already enforces 2FA. |
The following screen is displayed:
A choice can be made for either the Use a 2FA app or the Use a security key option.
Security key
If the security key option is chosen, Topicus KeyHub will automatically try to connect to a compatible security key. The browser will likely show a notification to this effect. Simply activate the security key using the normal procedure for the specific security key to confirm the link with Topicus KeyHub.
With physical security keys usually there is an action needed like touching a spot on the key or scanning a fingerprint. If the operating system functions as the security key, it should prompt for confirmation.
2FA app
If a 2FA app is chosen the following screen wil be shown.
After scanning the QR-code with the Topicus KeyHub-app, the screen will show the type of the smartphone. If the information is correct, 2FA can be enabled.
The Topicus KeyHub-app requires an internet connection to setup and receive push-notifications. If no internet connection is present, the app can generate the 6-digit code as well. |
If another app is used, this app will add the Topicus KeyHub-account after scanning the QR-code. To finalise the 2FA-setup the 6-digit verification code will have to be entered in the above screen. After entering this code, 2FA is enabled.
This concludes step 2.
1.1.3. Step 3: Request groups
The final step in the registration process is to request groups. A group grants access to the specific passwords, servers, applications and linked systems of that group.
Groups can be found by using the search field. Depending on naming conventions the groups displayed could correspond to projects, teams, products or departments.
Click on the icon on the right side of a group to request access to that group. Select all groups that apply to the role for the account that is registered. After access to the required groups is selected, the Next-button will continue to the next screen.
The next step is to enter a reason for the request. This reason is displayed to the group managers of the group which can help them decide whether the request is valid and should be granted. It is highly recommended to enter a brief and clear description of why access to that group is requested.
Before the secrets of the group are available, the access request should be validated and granted. This means that access to a specific group is not instant but takes some time, depending on the group manager(s). |
Finally the button Send and login sends out the requests and logs the user in on Topicus KeyHub.
1.2. Activation code
Registration of a Topicus KeyHub account can also occur by using a registration code. On the login-screen the option I have a registration code is available (or click on the link in the corresponding e-mail). The registration code can be entered in the next screen.
If the account details are correct, the next step is to choose a password. This password should consist of a minimum number of characters. Be advised that specific words or characters are considered invalid and will therefore not contribute to the total number of characters of a password.
The next step is to setup 2-factor authentication. For a detailed description see the corresponding paragraph enabling two-factor-authentication.
1.3. Resetting two-factor authentication
In some cases it is necessary to reconfigure 2FA, for example when the security key or smartphone is broken or stolen. In order to reset 2FA it is required that the 2FA is disabled for that specific account. Users can request to disable 2FA themselves on the login-screen using the option I cannot use 2FA anymore.
Clicking that specific button leads to the following page:
To reset 2FA a mandatory reason should be entered. The request to disable 2FA is then to be judged by another user in the organisation. If the request is granted, the user and the other user are notified by e-mail.
A user can reconfigure the 2FA using the options available under the Profile-section in Topicus KeyHub. Users who have multiple smartphone apps or security keys registered can simply login using another registered 2FA method. Otherwise, the user should make sure they are still able to login using their current 2FA method, either by generating the current 2FA-code or using their security key, before reconfiguring 2FA. In the case of users who have a new smartphone and still possess the old one, they can reconfigure 2FA themselves in this way. |
1.4. Password lost
If the user has forgotten his or her password, a request to recover the password can be submitted via I forgot my password. The procedure for recovering a password differs per account type and depends on the options chosen for the password. The different procedures are discussed below.
1.4.1. Account from an LDAP directory
Users from an LDAP directory use the Topicus KeyHub password to open the vault. This password may be synchronised with the password from the directory. If synchronisation is activated and the password in the directory is changed outside Topicus KeyHub, a password synchronisation will be started. If the user has lost the old password here, a password recovery can be started. Password recovery with password synchronisation will ask for the new directory password and a reason for the recovery. This password is then also used as the new Topicus KeyHub password.
If password synchronisation is not enabled, the Topicus KeyHub password will be requested when the vault is opened. If the user has lost the password here, a password recovery can be started. The user enters the new password twice, along with a reason for the recovery.
After submitting the request, the account will be locked. 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.
After completing the request, the Topicus KeyHub password of the user has been changed to the new password. The request can be cancelled by the user at any time. The old or the new password must be entered here.
1.4.2. Account from an OIDC directory
Users from an OIDC directory use the Topicus KeyHub password to open the vault. After clicking on the link I forgot my password the user will arrive at the page where a new password for Topicus KeyHub can be chosen. The user must enter the new password twice, provide a reason for the recovery, and submit the request. After this, the account will be locked until the request has been processed. Once the request has been approved by 2 users, the request can be completed. After completing the request, the Topicus KeyHub password of the user has been changed to the new password.
1.4.3. Account from an internal directory
Users from an internal directory use the Topicus KeyHub password to log in to Topicus KeyHub and to open the vault. Clicking on the I forgot my password link will take the user to the 'forgot password' page below. After entering the username, the user will receive an email with an activation code. This code allows the user to initiate the recovery procedure.
After entering the code, the screen is displayed where the user can choose a new password for Topicus KeyHub. The user must enter the new password twice, provide a reason for the recovery, and submit the request. After this, the account will be locked until the request has been processed. Once the request has been approved by 2 users, a 30 minute cooldown period will begin. The request can be completed after these 30 minutes have passed, or as soon as a 3rd user approves the request. After completing the request, the user’s password has been changed to the new password.
1.4.4. Reset password and wipe associated data
Only choose a password reset if the recovery procedure cannot be followed. For example, if there is nobody who can approve the recovery request. |
Instead of a password recovery, a user can also opt for a password reset if the password is forgotten. To perform a password reset, the user must authenticate against the directory and use 2FA. A password reset can therefore only be performed if the user has lost the Topicus KeyHub password, but knows the password for authentication against the directory. A password reset deletes all of the user’s keys, resulting in the loss of the following access:
-
Access to the personal vault and group vaults.
-
Manager privileges of groups.
-
Membership of the KeyHub administrators group.
The password entered by the user will be set as the new Topicus KeyHub password.
1.5. Mandatory password change
In some cases the following message can be displayed when signing in to Topicus KeyHub. This occurs when the password (no longer) complies to the criteria set by Topicus KeyHub. The password could be too short or the user could not yet have a personal password vault due to preliminary ending the registration wizard before. In this case the user will be guided through a three-step process in order to pick a new password. As this process is equivalent to the registration wizard, see the corresponding section in chapter 8 for more information about password usage and this three-step process.
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.
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:
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.
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.
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.
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.
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::
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:
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
- 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.
- 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. IfOnly 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 from a KeyHub administrator is required to enable this option. For more information, see the chapter about applications and the chapter about linked systems.
- 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.
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.
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.
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.
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.
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. |
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.
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 change in 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.
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.
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.
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.
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.
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.
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. |
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.
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. |
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:
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. |
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.
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.
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.
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.
7. 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.
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.
7.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.
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)","certificate (UUID)","certificate (name)","vault record (UUID)","vault record (name)","webhook (UUID)","webhook (name)","request (UUID)","security level","parameter 1","parameter 2","parameter 3"
8. Profile
The Profile-page is used to change preferences and show all events and activities of a user.
8.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.
8.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. |
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.
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. |
- 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.
8.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.
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.
2FA app
To (re)configure TOTP-based 2FA ,a QR-code is displayed which has to be scanned by the app on the smartphone.
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.
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. |
8.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.
8.1.4. Change language
Topicus KeyHub supports English, Dutch and German and with the link Change language the preferred language can be chosen.
8.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.
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
8.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.
8.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.
8.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.
9. 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.
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.
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.
9.1. Types of requests
There are various types of requests within Topicus KeyHub. These various requests will be discussed below.
9.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.
9.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.
9.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.
9.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.
9.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.
9.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.
9.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.
9.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.
9.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
-
-
Query and read accounts
by a member of KeyHub administrators. -
Remove accounts
by a member of KeyHub administrators. -
Create new applications
by a member of KeyHub administrators. -
Create new groups
by a member of KeyHub administrators. -
Grant applications permissions on a group after creating
by a member of KeyHub administrators. -
Query and read groups
by a member of KeyHub administrators. -
Create new groups on systems
by a manager of the group with ownership of the selected linked system. -
Access to the vault of a group
by a manager of the selected group. -
Read group details
by a manager of the selected group. -
Create new applications
by a manager of the selected group. -
Configure a group for additional authorisation or nesting
by a manager of the selected group.
-
- 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.
9.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.
9.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.
9.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.
9.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.
9.1.14. Transfer ownership, technical administration or content administration
The ownership or technical administration of an application, linked system, group on system, service account 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.
9.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.
9.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.
9.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.
9.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.
9.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.
9.1.20. Transfer Auditor
Transferring the group that gives access to the auditor dashboard.
- Submitted by
-
A manager of the current auditor group.
- Handled by
-
A manager of the selected group.
- After accepting
-
Access to the auditor dashboard is immediately transferred to the selected group.
9.1.21. 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.
9.1.22. Enable technical administration
A group manager wants to have technical 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 is enabled on the group.
9.1.23. 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.
9.1.24. 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
.
9.1.25. 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
.
9.1.26. 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.
9.1.27. 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.
9.1.28. 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.
9.1.29. 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.
10. Auditor role
The auditor role can only be assigned to one group and is assigned to the KeyHub Administrators group by default. If a group has this role, it will be displayed in the group details.
Managers of the group with the auditor role assigned can request to transfer the role to a different group. Such a request can be initiated by editing the group via My Groups and clicking on the arrow in the Auditor panel. A manager of the receiving group will have to accept the request in order to complete the transfer of the auditor role.
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 to which the auditor role is assigned will gain access to two dashboards, the groups dashboard and the accounts dashboard.
10.1. Groups dashboard
The groups dashboard shows an overview of all groups in Topicus KeyHub and a summary of the audits performed and expired audit deadlines. For each group it is shown how many managers and members it has, as well as information about audits 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.
10.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.
10.3. Classifications
Groups can be divided into classifications via the auditor dashboard.
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.
10.4. Accounts Dashboard
The accounts dashboard shows an overview of all accounts in Topicus KeyHub and a summary of the accounts per directory, per account status and per 2FA status. For each account is shown 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.
10.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.
10.6. Service accounts Dashboard
The service accounts dashboard shows an overview of all service accounts in Topicus KeyHub and a summary of the service accounts per linked system and per password rotation mode. 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.
Administration
11. 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.
11.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.
-
The e-mail address for the account, taken from the directory.
11.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. |
11.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.
11.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.
11.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.
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. |
11.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.
12. 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.
12.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.
- Description
-
A description of the service account. This description is also set on the linked system.
12.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.
13. 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.
13.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.
13.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.
13.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.
13.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.
14. 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. Thekeyhub
-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.
14.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.
14.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 anacr
claim in theid_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.
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.
14.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.
14.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.
14.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.
15. 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.
15.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.
15.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.
15.3. 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.
15.3.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.
15.3.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.
15.3.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.
15.3.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.
16. 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.
16.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 OAuthredirect_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.
16.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.
16.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 a URL.
- 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.
16.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.
16.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.
16.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.
16.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.
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.
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 - 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.
16.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.
16.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;});
17. 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.
17.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.
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
orgroupOfUniqueNames
. - 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. |
- Supports SSH public key
-
Indicated whether the LDAP server supports the
ldapPublicKey
object class. This objecft class defines thesshPublicKey
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 withSHA-
. Because of this, this algorithm is considered weak, but it is supported by most LDAP servers. Since version 2.4.41 OpenLDAP supportsPBKDF2-SHA512
as well. This is a very strong algorithm which performs 64k iterations ofSAH-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.
17.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
. - 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 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.
- Supports SSH public key
-
Indicated whether the AD server supports the
ldapPublicKey
object class. This object class defines thesshPublicKey
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. 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.
17.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 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.
17.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.
17.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.
17.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.
17.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 content administrators group.
17.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
andhttps
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 wordBearer
. - 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.
17.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.
17.10. 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.
17.11. 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.
17.11.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
andgroupOfUniqueNames
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.
17.12. 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.
17.13. 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. |
17.14. 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.
17.15. 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.
17.16. 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.
17.17. 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. These permissions can be viewed and, if desired, revoked under the tab Issued permissions.
17.18. 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 for a linked system.
17.19. 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.
17.20. 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.
18. 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 morePro
licenses available, new accounts will be created asBusiness
. - Web session Timeout
-
This option sets the maximum length of inactivity for a web session before it expires. The value must be between
30m
and12h
. Usem
for minutes andh
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
and7d
. Usem
for minutes,h
for hours, andd
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
and7d
. Usem
for minutes,h
for hours, andd
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 formatCL32LUDS
. 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. TheL
stands for lowercase letters,U
for uppercase letters,D
for digits andS
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 stringLUDS
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.
- 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.
- 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 andy
for years, for example5y
. - 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 andy
for years, for example5y
. - 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
andul
. The responsible disclosure will be disclosed through a link on the login-screen.
19. 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.
20. 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.
20.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.
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.
20.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.
21. 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. |
21.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
andhttps
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 wordBearer
. - 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.
21.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.
21.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.
21.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 anobject
. - account
-
The user who was the subject of the event. This field consists of a
name
,uuid
and optionally anobject
. - group
-
The group which was subject of the event. This field consists of a
name
,uuid
and optionally anobject
. - group2
-
A possible second group which was subject of the event. This field consists of a
name
,uuid
and optionally anobject
. - groupClassification
-
The group classification which was subject of the event. This field consists of a
name
,uuid
and optionally anobject
. - directory
-
The directory which was subject of this event. This field consists of a
name
,uuid
and optionally anobject
. - client
-
The application which was subject of this event. This field consists of a
name
,uuid
and optionally anobject
. - system
-
The linked system which was subject to this event. This field consists of a
name
,uuid
and optionally anobject
. - certificate
-
The certificate which was subject to this event. This field consists of a
name
,uuid
and optionally anobject
. - vaultRecord
-
The vault record which was subject to this event. This field consists of a
name
,uuid
and optionally anobject
. - webhook
-
The webhook which was subject to this event. This field consists of a
name
,uuid
and optionally anobject
. - modificationRequest
-
A reference to the request which was subject to this event. This field consists of a
uuid
and optionally anobject
. - 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.
22. 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.
22.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. |
22.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.
22.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.
23. About Topicus KeyHub
The 'about' page shows general information about the current Topicus KeyHub installation and the license.
23.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.
23.2. Usage over time
This graph shows the usage of active users over the last two months.
23.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.
23.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.
- 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.
- Enterprise organisation
-
With this feature organisations with multiple organisational units can separate the different units.
- 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.
23.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.
24. 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.
24.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).
24.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 KZLW-KPJK
Or directly visit
https://keyhub.example.org/login/code?usercode=KZLW-KPJK
> 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-03-06T18:45:25.779706604Z
Vault: valid until 2024-03-06T18:45:25.779706604Z
Review the information and complete the login process.
24.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 766272bd-9611-4505-a58d-ee8cd8321702 \
--client-secret Do4YZxO7m2GQ2D2iqA66Iv16bkNhG4dsBb7QD4Lr \
--store-secret
Authentication is required
Using a browser visit And enter the code
https://keyhub.example.org/login/code XNGG-LKFZ
Or directly visit
https://keyhub.example.org/login/code?usercode=XNGG-LKFZ
24.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 ea4ac840-56c2-483e-8138-3061ca1d775e \
--client-secret ZMqvptZ16yThRyFzQYywE7uamHaD9sBy2mV8yYD0 \
--store-secret
Authentication is required
Using a browser visit And enter the code
https://keyhub.example.org/login/code RSLT-NMKC
Or directly visit
https://keyhub.example.org/login/code?usercode=RSLT-NMKC
<?xml version="1.0" encoding="UTF-8"?><saml2p:Response> ... </saml2p:Response>
24.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 ab2f56b3-a452-4f1a-80a3-b1c0c503f8e3 \
--client-secret NpQFp0IvpcZnKyt9LPRByfvv0OJfkimEgdxsCsjM \
--client-credentials-grant
> keyhub status
Session #1 (active)
Status: connected to https://keyhub.example.org/
Type: client credentials grant
Client ID: ab2f56b3-a452-4f1a-80a3-b1c0c503f8e3
Client Secret: not stored
Access token: valid until 2024-03-06T18:43:56.800504942Z
Vault: valid until 2024-03-06T18:43:56.800504942Z
24.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: ab2f56b3-a452-4f1a-80a3-b1c0c503f8e3
Client Secret: not stored
Access token: valid until 2024-03-06T18:43:56.800504942Z
Vault: valid until 2024-03-06T18:43:56.800504942Z
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-03-06T18:44:02.027912953Z
Vault: valid until 2024-03-06T18:44:02.027912953Z
Session #3
Status: connected to https://keyhub.example.org/
Type: user authenticated on custom CLI client
Client ID: 766272bd-9611-4505-a58d-ee8cd8321702
Client Secret: stored
User logged in: keyhubuser
Access token: valid until 2024-03-06T18:44:07.364780532Z
Vault: valid until 2024-03-06T18:44:07.364780532Z, extended on demand
Session #4 (active)
Status: connected to https://keyhub.example.org/
Type: user authenticated on target client, custom CLI client
Client ID: 766272bd-9611-4505-a58d-ee8cd8321702
Client Secret: stored
Authenticated for: https://saml2-client.example.org
Access token: valid until 2024-03-06T18:44:12.673500649Z
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.
24.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
andCOMMENT
.
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
ae84183c-d5ad-4c9a-866e-24575d4ac01e personal vault b9630cc9-97c6-4104-9348-173cb5747523 passwordforfoo http://example.com usn P C
ae84183c-d5ad-4c9a-866e-24575d4ac01e personal vault 4c457939-33d1-4e0b-87bd-8a6fd49032ee file F
b312b77a-e805-4e84-a5bf-aaf164d0768d Product-X Test a5b22433-b83f-405e-90aa-4bf581ec5d86 grouppasswordforfoo P C
> keyhub query records --matches foo --type PASSWORD
VAULT VAULT NAME RECORD NAME URL USERNAME SECRETS
ae84183c-d5ad-4c9a-866e-24575d4ac01e personal vault b9630cc9-97c6-4104-9348-173cb5747523 passwordforfoo http://example.com usn P C
b312b77a-e805-4e84-a5bf-aaf164d0768d Product-X Test a5b22433-b83f-405e-90aa-4bf581ec5d86 grouppasswordforfoo P C
> keyhub vault read --group b312b77a-e805-4e84-a5bf-aaf164d0768d \
--record a5b22433-b83f-405e-90aa-4bf581ec5d86 --type PASSWORD
groupsecret
24.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.
24.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
24.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/1029204
RECORD NAME URL USERNAME SECRETS
16213c41-a040-4a87-adef-916d16c50f71 password http://example.com usn P C
> keyhub vault read --client --type PASSWORD \
--record 16213c41-a040-4a87-adef-916d16c50f71
secretreadfromstdin
24.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>
.
24.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
24.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.
24.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.
24.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
38a77892-cc9d-45af-91d4-809de2391496 Product-X Test active until 2024-03-06 18:45 not required not required
69e80c37-49cf-49e2-941b-a3c08f600c2f Product-X Dev inactive not required not required
24.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
25. 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.
25.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. |
25.2. Step 2.1 - Configure time
Select the timezone for Topicus KeyHub and configure NTP.
- 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.
25.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.
- 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.
25.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.
25.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.
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; } }
25.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.
- 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.
25.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. |
25.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. |
25.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. |
25.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.
25.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. |
26. 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.
26.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. |
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.
26.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.
26.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.
26.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.
26.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.
26.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. |
26.7. Configure monitoring
Options for enabling and configuring SNMP can be found under Monitoring. The Topicus KeyHub appliance supports both SNMP v2c and SNMP v3, the latter being preferred due to the improved security. In addition, KeyHub has an OpenMetrics endpoint and supports delivering metrics via OTLP.
- Enable OTLP
-
Send monitoring information and metrics via OTLP to the endpoint below.
- OTLP endpoint
-
The OTLP endpoint to send the metrics to.
- 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.
26.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. |
26.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
.
26.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.
26.10. Configure authentication
26.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.
26.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.
27. 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.
27.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.
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. |
27.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.
27.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
.
Step 1 - Establish link
When establishing the link, the keys are exchanged between the current and the new VM.
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.
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.
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.
27.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.
27.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. |
27.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.
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.
27.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.
27.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. |
27.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.
27.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.
28. Updates, Backups and Support
28.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. |
28.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.
28.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.
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.
28.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.
28.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.
28.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.
28.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.
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.
29. Copyright notices
This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.