Introduction

Welcome to the Topicus KeyHub best practice guide.

Topicus KeyHub ensures the authentication and authorisations of users. This best practice guide gives examples on how to link applications to Topicus KeyHub.

Layout of this guide

This guide contains example configurations of Topicus KeyHub and linked applications. Every chapter will describe the configuration used in both KeyHub and the linked application. This guide does not provide a comprehensive list of all option. For those, please read our manual.

1. Deployment

Prior to installation, the Topicus KeyHub virtual machine needs to be deployed on a hypervisor or cloud platform. If this is already done you can skip the next segments and move directly to installation.

1.1. ESX

In the following example an ESX host managed by vSphere is used. Topicus KeyHub needs a minimum of 2 VPU’s, 6GB memory and 80GB disk space. This will be detected during verification of the uploaded image.

1.1.1. Step 1 - Download and deploy the image

Download the latest OVA from https://topicus-keyhub.com/download-keyhub/ Upload the image to the ESX host from vSphere. Select the ESX host, Actions and Deploy OVF template.

step1download
Figure 1. Download and deploy the image
Select an OVF template

Upload the OVA or enter the network location.

Select a name and folder

Specify a unique name and target location

Select a compute resource

Select the destination host for the Topicus KeyHub VM

Review details

Verify the template details.

step1deploy
Figure 2. Download and deploy the image

1.1.2. Step 2 - Configure storage & network

Select storage

Select the storage for the configuration and disk files

Select networks

Select the network where the VM will reside.

Ready to complete

Click Finish to start creation.

Once the OVA is uploaded you can start the VM. In vSphere you can monitor the VM boot process from a webconsole.

step2storage
Figure 3. Configure storage & network

After boot KeyHub will show the network configuration and the 6-digit password for first login on the console screen. Paste the given link in your browser to start the configuration.

terminal
Figure 4. Terminal welcome screen

1.1.3. Step 3 - Adjust network settings (optional)

If needed you can adjust the network settings here by pressing S.

step3network2
Figure 5. Adjust network settings (optional)

This guide explains how to setup a link between Topicus KeyHub and an Active Directory. This AD can then be used for dynamic and static account provisioning.

2.1. Configuration details

In this example we used the configuration below. You should replace this with the details for your configuration.

A guide on how to prepare your AD can be found here: prepare AD

You need a group in KeyHub to connect to your application. See how to create a group here

  • Name: Linked AD

  • Technical administration group: KeyHub Administrators

  • Primary Host: linked-ad.keyhub.test

  • Trusted Certificate: Click on download to get the server certificate.

  • Bind DN: CN=KeyHub, CN=Users, DC=keyhub, DC=test

  • Bind password: the password for user KeyHub

  • Base DN: CN=KeyHub, DC=KeyHub, DC=test

  • Group RDN: OU=Groups

  • User RDN: OU=Users

Detailed info per item can be found in the manual (chapter 14.2)

2.1.1. Step 1

  • Click MANAGE ACCESS

  • Click Add

link to ad001

2.1.2. Step 2

  • Choose Type: Active Directory

  • click NEXT

link to ad002

2.1.3. Step 3

  • Fill the details as mentioned above or your own

  • Click TEST

  • Click SAVE

link to ad003
link to ad004

To provision users to a group on the Active Directory you need to link it to a group in KeyHub.

  • Click your newly linked AD

  • Click Groups

  • Click ADD

  • Select the group you want to use

  • Select the group on the AD you want to use or select Create a new group

  • Click SAVE

link to ad005
link to ad006

2.1.5. Step 5

  • Done. Your linked Active Directory is ready for use

beacuse the group is provisioned dynamically by default it will appear on your dashboard where you can activate the group. If you want the group to be always 'on' you need to provision it statically. You can find how here

3. Configure client authentication for Active Directory

Client authentication is the most secure way of setting up a connection to the directory. This guide is split into 5 parts for setting up client authentication for Active Directory.

3.1. Prepare a client certificate

3.1.1. Step 1

  • log in to the Active Directory with the user "keyhub" (see Prepare AD)

  • open Microsoft Management Console (mmc.exe)

client cert ad001

3.1.2. Step 2

  • open File → Add /Remove Snap-in

client cert ad002

3.1.3. Step 3

  • Select Certificates

  • Click Add

  • Click OK

client cert ad003

3.1.4. Step 4

  • Select My user account

  • Click Finish

  • Click `OK

client cert ad004
client cert ad005

3.1.5. Step 5

  • Right click Personal (from Console root → Certificates - Current User)

  • Select All tasks → Request New Certificate

client cert ad006

3.1.6. Step 6

  • Click Next

client cert ad007

3.1.7. Step 7

  • Select User

  • Expand details

  • Click Properties

client cert ad008

3.1.8. Step 8

  • Select Subject tab

  • Fill in cn=keyhub in the Full DN Value box

  • Click Add

  • Click OK

client cert ad009
client cert ad0010

3.1.9. Step 9

  • Click Enroll

client cert ad0011

3.1.10. Step 10

  • Done. Your client certificate is created

3.2. Export the client certificate and key

From the management console with user certificate snap in (see step 1 through 4 here )

3.2.1. Step 1

  • Right click the certificate you want to export

  • Select All tasks

  • Select Export

export cert ad001

3.2.2. Step 2

  • Click Next

export cert ad002

3.2.3. Step 3

  • Select Yes…​

  • Click Next

export cert ad003

3.2.4. Step 4

  • Select Personal Information Exchange

  • Click Next

export cert ad004

3.2.5. Step 5

  • Select Password

  • Fill in your password

  • Click Next

export cert ad005

3.2.6. Step 6

  • Specify the name and location for your exported certificate

  • Click Next

  • Click Finish

  • Click OK

export cert ad006
export cert ad007
export cert ad008

3.2.7. Step 7

  • Done. Your certificate and key are packed in a .pfx file

3.3. Convert the PFX to a certificate and private key

To concert PFX to PEM you can use OpenSSL. OpenSSL is availlable for different platforms. An example for Powershell is included. If you have access to a system with OpenSSL installed you can find the commands to convert a PFX here.

Powershell

  • Install chocolaty following the instructions on their website

  • Change into the OpenSSL bin directory

cd C:\Program Files\OpenSSL\bin

  • Run the commands as mentioned here.

3.4. Prepare the Active Directory user

3.4.1. Step 1

  • Open Active Directory Users and Computers

  • Find the user keyhub

  • Right click and select Name Mappings

client auth ad user001

3.4.2. Step 2

  • Select Add

  • Browse to the and open the .pem certificate file

  • Click OK

  • Click OK

client auth ad user002
client auth ad user003
client auth ad user004

3.4.3. Step 3

  • Done. The user keyhub can now use a client certificate to bind.

3.5. Configure KeyHub

3.5.1. Step 1

  • From the menu select MANAGE ACCESS

  • Find and click the Active Directory you want to configure

client auth ad001

3.5.2. Step 2

  • From the TLS dropdown menu select Client authentication

If you have a pinned certificate select Client authentication - Pinnned certificate
client auth ad002

3.5.3. Step 3

  • Upload your public certificate, private key and fill in your private key password

client auth ad003

3.5.4. Step 4

  • Click TEST

  • Click SAVE

client auth ad004

3.5.5. Step 5

  • Done. You are now using client authentication instead of a bind with username and password.

4. OpenLDAP install guide

This guide describes the steps needed to install and configure OpenLDAP on Centos 7 for use as a linked system with KeyHub.

4.1. Installing OpenLDAP

This part is based on the excellent guide provided at server world. Original can be found here.

you will need sudo rights throughout this guide. Either change into root or use sudo for all commands below.
In this guide we use vi as a text editor. You can offcourse replace it by your favorite text editor.

4.1.1. Step 1

  • Update your OS

yum update -y && yum upgrade -y

  • Install OpenLDAP Server and Client tools

yum -y install openldap-servers openldap-clients

  • Copy initial database configuration

cp /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/DB_CONFIG

  • Adjust rights

chown ldap: /var/lib/ldap/DB_CONFIG

  • Start OpenLDAP

systemctl start slapd

  • Enable OpenLDAP start at system boot

systemctl enable slapd

4.1.2. Step 2

  • Create a directory for the ldif files

mkdir /root/ldap

  • Change into this directory

cd ldap

  • Set OpenLDAP admin password
    You might want to create a vault record in KeyHub and generate a password there ;)
    Note the output for the next step.

slappasswd

  • Create chrootpw.ldif configuration file

vi chrootpw.ldif

  • Content of chrootpw.ldif
    Use the output from the slappasswd step to replace the value in olcRootPW.

dn: olcDatabase={0}config,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {SSHA}xxxxxxxxxxxxxxxxxxxxxxxx

  • Apply configuration

ldapadd -Y EXTERNAL -H ldapi:/// -f chrootpw.ldif

4.1.3. Step 3

  • Import basic schemas

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/nis.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif

4.1.4. Step 4

Set your domain name in the OpenLDAP database.

  • Generate OpenLDAP manager’s password
    You might want to create a vault record in KeyHub and generate a password there ;)
    Note the output for the next step.

slappasswd

  • Create chdomain.ldif configuration file

vi chdomain.ldif

  • Content of chdomain.ldif
    Use the output from the slappasswd step to replace the value in olcRootPW.

Make sure you replace dc=<MY_DOMAIN>, dc=<MY_TLD> with your own domain components. eg. dc=topicus-keyhub, dc=com 
dn: olcDatabase={1}monitor,cn=config
changetype: modify
replace: olcAccess
olcAccess: {0}to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth"
  read by dn.base="cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD>" read by * none

dn: olcDatabase={2}hdb,cn=config
changetype: modify
replace: olcSuffix
olcSuffix: dc=<MY_DOMAIN>,dc=<MY_TLD>

dn: olcDatabase={2}hdb,cn=config
changetype: modify
replace: olcRootDN
olcRootDN: cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD>

dn: olcDatabase={2}hdb,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {SSHA}xxxxxxxxxxxxxxxxxxxxxxxx

dn: olcDatabase={2}hdb,cn=config
changetype: modify
add: olcAccess
olcAccess: {0}to attrs=userPassword,shadowLastChange by
  dn="cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD>" write by anonymous auth by self write by * none
olcAccess: {1}to dn.base="" by * read
olcAccess: {2}to * by dn="cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD>" write by * read

  • Apply configuration

ldapmodify -Y EXTERNAL -H ldapi:/// -f chdomain.ldif

  • Create basedomain.ldif configuration file

vi basedomain.ldif

  • Content of basedomain.ldif

Make sure you replace dc=<MY_DOMAIN>, dc=<MY_TLD> with your own domain components. 
dn: dc=<MY_DOMAIN>,dc=<MY_TLD>
objectClass: top
objectClass: dcObject
objectclass: organization
o: Server World

dn: cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD>
objectClass: organizationalRole
cn: Manager
description: Directory Manager

dn: ou=People,dc=<MY_DOMAIN>,dc=<MY_TLD>
objectClass: organizationalUnit
ou: People

dn: ou=Group,dc=<MY_DOMAIN>,dc=<MY_TLD>
objectClass: organizationalUnit
ou: Group

  • Apply configuration

Make sure you replace dc=<MY_DOMAIN>, dc=<MY_TLD> with your own domain components. Use directory manager’s password when prompted. 
ldapadd -x -D cn=Manager,dc=<MY_DOMAIN>,dc=<MY_TLD> -W -f basedomain.ldif

4.1.5. Step 5

If a firewall is running you need to allow LDAP service. LDAP uses 389/TCP. Firewalld is the default firewall serice for Centos 7. The commands below will open port 389 on Firewalld.

firewall-cmd --add-service=ldap --permanent
firewall-cmd --reload

4.2. Configuring TLS

For a secure connection between KeyHub and OpenLDAP we advise to use StartTLS.

4.2.1. Step 1

Create certificates and keys if you don’t want to or can’t use an existing one. Otherwise you can use your own certificate and skip this step.

  • Create Server certificate

Replace <HOSTNAME>, <MY_DOMAIN> and <MY_TLD> with the host and domain name you used for your OpenLDAP installation. eg. ldap_server, topicus-keyhub and com

  • Create root certificate and key

openssl genrsa -des3 -out rootCA.key 4096
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt

  • Create server private key

openssl genrsa -out <HOSTNAME>.key 2048

  • Create the server certificate configuration file

vi <HOSTNAME>.conf

  • Content

Don’t forget to change at least the CN. Other values can be changed to your liking. 
[req]
default_bits=2048
prompt = no
default_md = sha256
distinguished_name = dn
[dn]
C = NL
ST = Overijssel
L = Deventer
O = Topicus KeyHub
OU = KeyHub
emailAddress = info@<MY_DOMAIN>.<MY_TLD>
CN = <HOSTNAME>.<MY_DOMAIN>.<MY_TLD>

  • Create the server certificate signing request

openssl req -new -key <HOSTNAME>.key -out <HOSTNAME>.csr -config <HOSTNAME>.conf

  • Create the configuration for the alternative name

vi <HOSTNAME>.ext

  • Content

Change the DNS value to yours. eg. ldap_server.topicus-keyhub.com 
subjectAltName = DNS:<HOSTNAME>.<MY_DOMAIN>.<MY_TLD>

  • Create the server certificate

openssl x509 -req -in <HOSTNAME>.csr -CA ./rootCA.crt -CAkey ./rootCA.key -CAcreateserial -out <HOSTNAME>.<MY_DOMAIN>.<MY_TLD>.crt -days 500 -sha256 -extfile <HOSTNAME>.ext

  • Optionaly verify your certificate

openssl x509 -in <HOSTNAME>.<MY_DOMAIN>.<MY_TLD>.crt -text -noout

4.2.2. Step 2

Move the created certificates to the OpenLDAP directory and adjust the rights.

  • Move the certificates to /etc/openldap/certs

mv <HOSTNAME>* /etc/openldap/certs/
mv rootCA.* /etc/openldap/certs/

  • Set the rights for the certificates

chown ldap: /etc/openldap/certs/*

4.2.3. Step 3

Create the OpenLDAP configuration.

  • Create tlsverify.ldif configuration file

The order of the configuration lines in tlsverify.ldif is very important. 
vim tlsverify.ldif

  • Content of tlsverify.ldif

Check if the paths and names of the certificates exist and adjust if needed. The "-" in rule 20 is not a typo ;) 
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/openldap/certs/rootCA.crt

dn: cn=config
changetype: modify
add: olcTLSCipherSuite
olcTLSCipherSuite: HIGH:+SSLv3:+TLSv1:+SASL:MEDIUM:+SSLv2:@STRENGTH:+SHA:+MD5:!NULL

dn: cn=config
changetype: modify
add: olcTLSVerifyClient
olcTLSVerifyClient: try

dn: cn=config
changetype: modify
replace: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/openldap/certs/<HOSTNAME>.key
-
replace: olcTLSCertificateFile
olcTLSCertificateFile: /etc/openldap/certs/<HOSTNAME>.<MY_DOMAIN>.<MY_TLD>.crt

4.3. Step 4

  • Run the configuartion

ldapmodify -Y EXTERNAL -H ldapi:/// -f tlsverify.ldif

4.4. Enable public Key provisioning

This step is needed to enable public key provisioning from KeyHub

4.4.1. Step 1

  • Install openssh-ldap.
    This is needed for adding the ssh key schema

yum -y install openssh-ldap

4.4.2. Step 2

Create the OpenLDAP configuration.

  • Create openssh-ldap.conf file (in this example this is done in /root/ldap)

vim /root/ldap/openssh-ldap.conf

  • Content of openssh-ldap.conf

The path of the files to be included depends on the installed version. 
include /etc/openldap/schema/core.schema
include /usr/share/doc/openssh-ldap-7.4p1/openssh-lpk-openldap.schema

  • Create the cn=config directory and files using slapcat
    slapcat reads from the current database based on the created config file and outputs to the specified directory.

slapcat -f /root/ldap/openssh-ldap.conf -F /root/ldap -n 0

  • Copy /root/ldap/cn=config/cn=schema/cn={1}openssh-lpk-openldap.ldif to /root/ldap/openssh-ldap.ldif

cp cn\=config/cn\=schema/cn\=\{1\}openssh-lpk-openldap.ldif /root/ldap/openssh-ldap.ldif

  • Edit /root/ldap/openssh-ldap.ldif

  • Remove the lines similar to these

structuralObjectClass: olcSchemaConfig
entryUUID: 02a17a84-79a3-103b-9158-15bfba5efd60
creatorsName: cn=config
createTimestamp: 20210715102733Z
entryCSN: 20210715102733.168332Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20210715102733Z

  • Replace dn: cn={1}openssh-lpk-openldap with dn: cn=openssh-openldap,cn=schema,cn=config

  • Replace cn: {1}openssh-lpk-openldap with cn: openssh-openldap

  • Replace cn=openssh-openldap with cn=openssh-openldap,cn=schema,cn=config

The resulting file should look similar to this

# AUTO-GENERATED FILE - DO NOT EDIT!! Use ldapmodify.
# CRC32 d4505710
dn: cn=openssh-openldap,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: openssh-openldap
olcAttributeTypes: {0}( 1.3.6.1.4.1.24552.500.1.1.1.13 NAME 'sshPublicKey' D
 ESC 'MANDATORY: OpenSSH Public key' EQUALITY octetStringMatch SYNTAX 1.3.6.
 1.4.1.1466.115.121.1.40 )
olcObjectClasses: {0}( 1.3.6.1.4.1.24552.500.1.1.2.0 NAME 'ldapPublicKey' DE
 SC 'MANDATORY: OpenSSH LPK objectclass' SUP top AUXILIARY MUST ( sshPublicK
 ey $ uid ) )

4.4.3. Step 3

  • Apply configuration

ldapadd -Y EXTERNAL -H ldapi:/// -f openssh-ldap.ldif

4.4.4. Step 4

  • Restart OpenLDAP

systemctl restart slapd

4.5. Install PBKDF2 module on OpenLDAP

OpenLDAP is not able to use PBKDF2 out of the box. PBKDF2 is a strong hashing algorithm using 64k iterations of SHA512. KeyHub is able to provision password hashes in PBKDF2 format.

4.5.1. Step 1

  • Download the PBKDF2 module from the Topicus servers
    md5sum 198056d220b0d94750a05fa9c0dade6f pw-pbk2.tar.gz

wget https://files.topicus-keyhub.com/download/pw-pbk2.tar.gz

4.5.2. Step 2

  • Unpack pw-pbk2.tar.gz
    This wil unpack in /usr/lib64/openldap/

tar xvfz ~/ldap/pw-pbk2.tar.gz

4.5.3. Step 3

  • If SELinux is enabled (this is default for Centos 7) you will need to set a context for these files

restorecon -v /usr/lib64/openldap/pw-pbkdf2.*

4.5.4. Step 4

  • Create the configuration file pbk.ldif
    with the following content:

dn: cn=module{1},cn=config
objectClass: olcModuleList
cn: module{1}
olcModulePath: /usr/lib64/openldap
olcModuleLoad: pw-pbkdf2.la

  • Apply the configuration

ldapadd -Y EXTERNAL -H ldapi:/// -f pbk.ldif

If your using the same Directory for Authenticating (Identity Provider) as for provisioning you can use the source directory option.

5.1. In KeyHub

5.1.1. Step 1

  • Click MANAGE ACCESS

source dir001

5.1.2. Step 2

  • Click Add

source dir002

5.1.3. Step 3

  • Choose Type: Source Directory

  • Click NEXT

source dir003

5.1.4. Step 4

  • Choose a name

  • Select your Source Directory

  • Give the location of the OU in the Source Directory where your groups are stored

source dir004
It’s a good idea to use a new OU

5.1.5. Step 5

  • Click TEST

  • Click SAVE

source dir005

5.1.6. Step 6

  • Done. Your linked Source Directory is ready for use

To provision users to a group on the Source Directory you need to link it to a group in KeyHub. See how here

6. Create a group in KeyHub

With Topicus KeyHub access rights are distributed via groups. Detailed information about groups can be found in the manual (chapter 11)

6.1. In KeyHub

6.1.1. Step 1

  • From the menu ADMINISTRATION click GROUPS

create group001

6.1.2. Step 2

  • Click ADD

create group002

6.1.3. Step 3

  • Fill in the desired group name

  • Select the initial manager

  • Click SAVE

create group003
It’s advised to add at least one more manager after creation

6.1.4. Step 4

  • Done. You can now use your newly made group.

create group004

7. Making an existing group static.

Sometimes it is desirable to have a group always available without the need to for users to activate the group on the dashboard. To achieve this you can make the group static. In KeyHub this is called static account provisioning.

Detailed info can be found in the manual (chapter 6.4)

7.1. In KeyHub

7.1.1. Step 1

  • Select GROUPS from the administration menu

  • Select the group you want to make statically provisioned

static group001

7.1.2. Step 2

  • Select Linked Systems from the tabs

static group002

7.1.3. Step 3

  • Select the Static account provisioning box

  • Click SAVE

static group003

7.1.4. Step 4

  • Done. The group will have disappeared from the dashboard as it is now always active.

8. Prepare the Active Directory

For reading accounts, provisioning accounts and provisioning groups to Active Directory KeyHub needs to bind to the directory.

In this example all parameters can be interchanged with parameters applicable to your existing AD configuration.

8.1. In Active Directory

8.1.1. Step 1

  • Create a user KeyHub with privileges higher or equal to the highest privilege it needs to provision.
    eg. for provisioning Domain admin rights you need Domain admin rights

  • Give this user a strong password. The limit in Active Directory is 256 characters.

  • Store this password in a safe place.

prep ad005
prep ad006
prep ad007
prep ad008

8.1.2. Step 2

Create the following Organizational Units for provisioning.

  • Create an OU=KeyHub

  • Create an OU=groups in the OU=KeyHub

  • Create an OU=users in the OU=KeyHub

prep ad001
prep ad002
prep ad003
prep ad004
For a linked directory: 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 (minimum password length) should be configured in Topicus KeyHub. The typical error message for issues concerning password policies is Server is unwilling to perform.

9. Active Directory Schema Attributes and Classes

9.1. Adding a custom attribute

To be able to edit the AD schema you need to run the following command. You only need to do this once. You can run it from an elevated PowerShell Terminal.

PS> regsvr32 schmmgmt.dll
ad add attributes 7fc0c

  • run mmc

PS> mmc

The MMC console will pop up. From here you can add the Active Directory Schema snap-in.

  • File > add / remove snap-in

  • Add Active Directory Schema snap-in

  • OK

  • Right click attributes > create attribute

Read and understand the warning. This one matters. After creating the Class or Attribute you can not modify or delete it!
ad add attributes aa7b2
ad add attributes 8d4d8

  • In the container attributes browse to the newly created attribute and open properties.

  • Select "index this attribute"

ad add attributes c6d2d

9.2. Adding a custom Class

ad add attributes 6cc3a

  • Add custom attributes as needed

ad add attributes 1da8a

9.3. Adding a auxiliary class to another class

  • Open the properties for the higher level class.