Topicus KeyHub

KeyHub Install Guide for Azure

This document provides a step-by-step guide through the installation process of Topicus KeyHub in Azure. The only prerequisite is an Azure account to install KeyHub with. Furthermore, this guide explains the connection of an Azure AD which provides the accounts which can log on to Topicus KeyHub with single sign on. For other user directories we kindly refer to the manual which is included in the Topicus KeyHub software and available after install.

Part 1 - Getting the KeyHub appliance

First you have to get the KeyHub appliance which is available in the Azure Marketplace. Either search the Marketplace for “Topicus KeyHub” or use this direct link.

The Topicus KeyHub offer should look something like this:

Figure 1. Topicus KeyHub in the Azure Marketplace

To install Topicus KeyHub, click the GET IT NOW button on the left side of the screen.

The following dialog is shown:

Figure 2. Create the VM dialog

Click on “Continue” and you will be redirected to your own Azure-portal. You might need to log in to Microsoft Azure first.

In the Azure portal, the Topicus KeyHub offer is presented, like such:

Figure 3. Get the KeyHub appliance

Click on the button “Create” to create your virtual machine. This leads to the configuration screen of the virtual machine:

Figure 4. Create virtual machine

Some basic information is to be provided here, such as:

Subscription: If you have multiple subscriptions, select the one to install KeyHub to
Resource group: Either select a resource group that already exists or create a new one
Virtual Machine Name and Region: Select the preferred settings
Size: The recommended size for the VM is preselected, but you can choose a different size if desired
Administration account: Although KeyHub comes with a maintenance account, Azure creates an account in the VM. It is recommended to choose "Password" as authentication type with any username other then "keyhub" and a strong generated password.

If you choose "SSH public key" you can only use this to login to the KeyHub appliance shell. You can not use the username "keyhub"

Click on “Review + Create” to continue. Optionally you can go through the other configuration screens. The default settings are ok for KeyHub.

Figure 5. Review screen

Review your virtual machine and if everything is correct, click on “Create” to create the VM.

The following screen shows the progress of the creation. The complete process can take up to 5 minutes.

Figure 6. Creating VM screen

Once the implementation is complete, a notification is shown. Click on “Go to resource” to see the details. The resource should look something like this:

Figure 7. VM created screen

Part 2 - Installing the Appliance

On the right side of the resource screen presented above, the “Public IP-address” is shown. This is the IP-address to connect to in the next step. However, first scroll the menu down to the section “Support and troubleshooting” and select the tab called “Boot diagnostics”.

Selecting this tab shows the screen with the console output. It should look something like this:

The console output is important because it presents the initial login password. You find it under the ‘Login with: keyhub / 123456’. These six digits are required for the initial login. With the ‘Download screenshot’ you can download a screenshot (bitmap) of the screenshot.

The console output shows the URL as well (in this case: https://10.0.3.4:50443/admin). This private IP-address shown here should be replaced by the public IP-address provided in the “Resource Overview”-page shown before:

Combining the public IP-address with the port (50443) and path (/admin) will give you the URL which you can connect to. In our case: https://104.45.43.163:50443/admin.

Visit this URL in a new browser window to continue the setup. This should present the login-screen of Topicus KeyHub:

Enter the maintenance password to login. The first time you login, the maintenance password is the six-digit-code presented in the console output of Azure (see section above).

The following step requires setting up a strong maintenance password.

Be sure to store the maintenance password somewhere secure!

After the required password change, the installation wizard of Topicus KeyHub will guide you through the necessary steps. These steps are not discussed in more detail here. For additional support please refer to the user manual which can be accessed by pressing the question mark-symbol on the left bottom side of the KeyHub-interface:

Part 3 - Setup Single Sign-On with Azure AD

During the installation of KeyHub, the final step is setting up the ‘Directory’. Here you can setup single sign on with your corporate Azure AD if required.

External URL by Azure

During setup of the SSO, the ‘External URL’ is required. Probably your organization will use its own DNS-entries, but you can also let Azure configure this for you. If you configure your own DNS, you can skip this paragraph.

To get an external URL in Azure, go to the Virtual Machine that was just created. There, on the bottom right the ‘DNS name’ is visible and if not configured, you can click on ‘Configure’ to do so.

The following screen looks like this:

And there you can configure the DNS name label and whether it is a dynamic or static assigned name. After saving you can navigate back to the overview. the screen looks like this:

Here you can find the complete DNS name provided by Azure. This can be used to configure the SSO with KeyHub.

Configure SSO in KeyHub

During the installation of KeyHub, you can setup SSO. The screen to do so looks something like this.

Select ‘OIDC’ as the directory type, name your directory and select ‘Microsoft Azure Active Directory’ as the Provider.

Then the ‘client identifier’ and the ‘client secret’ are required. These can be found in Azure.

To make sure only users from your own Azure tenant can register an account in KeyHub you need to set the domain restriction to your domain. This will be the domain name after the @ in your users e-mail address. You can also find this domain in Azure AD overview. Just navigate to the menu item Custom domain names.

eg. for user@topicus-keyhub.com you will use topicus-keyhub.com as domain restriction.

If you leave this field empty you cannot use the single-tenant option in Azure. For multiple domains you will need a paid subscription with Microsoft. This is out of scope for this guide.

Getting the client identifier

Go to the Azure Portal and search for "app registrations" This shows the overview of your App registrations:

For Single Sign-On to Topicus KeyHub, a new app registration is required. Click on the + symbol “New registration" to create a new application. The following screen is shown:

At "Supported account types" select the single-tenant option. The ‘Redirect URI’ consists of your public Azure-KeyHub-URL combined with the path ‘/login/oidc’. With the configuration in this document, the ‘Sign-on URL’ is: ‘https://keyhub-azure.westeurope.cloudapp.azure.com/login/oidc’.

After providing this information, the ‘App registration’ can be created. After creation, the Application ID is available on the screen that looks something like this:

Applying the client identifier

The Application ID from the ‘Azure app registration’ is required at the corresponding configuration step in Topicus KeyHub and should be entered on the ‘Client identifier’ field.

Getting the client secret

The final step of the SSO setup requires the client secret. This secret has to be generated by Azure AD in the App registration as well. Go to the “App registration” as created in the previous step and go to Settings, and then “Certificates & secrets”. The screen should look something like this:

A client identifier can be generated here. In order to do so, click "New client secret"

The screen should look something like this:

Name your secret and select an expiry period. Click "Add". Copy the generated value for use in KeyHub.

the value is not available anymore after you leave this screen!

This value should be entered as the “Client secret” in the Directory-configuration screen in Topicus KeyHub:

This finalizes the installation and setup of Topicus KeyHub on Azure.

Additional support

For additional support, please refer to the manual which can be accessed by pressing the question mark-symbol on the bottom left side in Topicus KeyHub.

For questions and support visit our product website https://www.topicus-keyhub.com