Topicus KeyHub Install Guide for Azure

Applies to Topicus KeyHub version 13.0.

29 november 2018


Overview

Part 1 - Getting the KeyHub appliance        2

Part 2 - Installing the Appliance        10

Part 3 - Setup Single Sign-On with Azure AD        13

External URL by Azure        13

Configure SSO in KeyHub        16

Getting the client identifier        18

Applying the client identifier        22

Getting the client secret        22

Additional support        25


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:

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

The following dialog is shown:

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

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

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

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

After providing the required information, click on the “Next: Disks”-button. This leads to the following screen:

For KeyHub the Standard-HDD will suffice.

Click on “Next: Networking” to continue.

The default settings in Networks are sufficient and do not require changes.

Click on “Next: Management” to get to the next step:

The Management-tab does require one important adaptation: switch the “Boot diagnostics” to “ON”. After the VM is created, the initial password is presented on the console-window and without this setting, the console is not available.

Click on “Next: Guest configuration” to continue.

The default settings are sufficient and do not require changes.

Click on “Next: Tags” to continue.

The default settings are sufficient and do not require changes.

Click on “Next: Review and Create” to continue.

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.

Once the implementation is complete, a notification is shown. Click on “Go to the resource” to see the details.

The resource should look something like this:

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.0.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://13.94.188.184: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 this 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 any organisation will use their own DNS-entries, but you can also let Azure configure this. 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, 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’ and the Provider.

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

Go to the Azure Portal and select “Azure Active Directory”. This shows the overview of your Azure AD:

 

On this screen, go to the tab “Enterprise applications”. This will show a screen similar to this:

Getting the client identifier

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

Select the option “Application you’re developing” under the ‘Add your own app’ section. This will bring up a screen on the right where you can select “Ok, take me to App Registrations to register my new application”:

Then the following screen is shown:

Here you can click the “+ New application registration”. This shows a screen on the right side where the name and the sign-on URL can be provided.

The ‘Sign-on URL’ 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://keyhub13test.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:

On this screen, on the right side, go to “Settings” and then “Properties” to end up on a screen like this:

Here, the option “Multi-tenanted” should be set to Yes. After setting this to Yes, click on Save to save the changed setting.

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 “Keys”. The screen should look something like this:

A client identifier can be generated here. In order to do so, provide a ‘Key description’ and a ‘Duration’ in the appropriate fields. After you Save this information, a “Value” is generated. Be sure to copy this value directly, as it is not available anymore after you leave this screen.

This value should be entered as the “Client identifier” 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 left bottom side in Topicus KeyHub.

For other questions or to submit a ticket, see https://topicuskeyhub.freshdesk.com or visit our product website https://www.topicus-keyhub.com 

Topicus KeyHub Install Guide for Azure