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 FileAdd /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 tasksRequest 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.

ad add attributes ee394
  • Add the class.

ad add attributes d4f28
ad add attributes d37ef

9.4. Generating an OID

  • Run the following commands in the terminal. You can copy this code block and paste it in. The Microsoft OID Prefix is used for the automated OID Generator.

$Prefix="1.2.840.113556.1.8000.2554"
$GUID=[System.Guid]::NewGuid().ToString()
$Parts=@()
$Parts+=[UInt64]::Parse($guid.SubString(0,4),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(4,4),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(9,4),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(14,4),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(19,4),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(24,6),"AllowHexSpecifier")
$Parts+=[UInt64]::Parse($guid.SubString(30,6),"AllowHexSpecifier")
$OID=[String]::Format("{0}.{1}.{2}.{3}.{4}.{5}.{6}.{7}",$prefix,$Parts[0],$Parts[1],$Parts[2],$Parts[3],$Parts[4],$Parts[5],$Parts[6])
$oid

9.5. sshPublicKey Attribute for KeyHub provisioning in Active Directory

When enabling Public Key provisioning in a linked directory KeyHub will expect the follwowing Class and Attribute in the AD.

When adding classes and attributes in Active Directory it is unmutable after creation. Make a backup and test in a lab before going to production!
Attribute:
Common Name: sshPublicKey
X_500 OID: 1.3.6.1.4.1.24552.500.1.1.1.13
Description: 'MANDATORY: OpenSSH Public key'
Syntax: octetString
Multi-Valued: yes
Class:
Common Name: ldapPublicKey
X_500 OID: 1.3.6.1.4.1.24552.500.1.1.2.0
Description: 'MANDATORY: OpenSSH LPK objectclass'
Class type: Auxiliary
Parrent Class: Top
Optional Attribute: sshPublicKey

10. Convert pfx certificate container to PEM format certificate and key

If you have a .PFX certificate container you can extract the certificate and key with openssl.

Extract the certificate:

openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem

Extract the key:

openssl pkcs12 -in filename.pfx -nocerts -out key.pem

11. Connecting Devolutions Remote Desktop Manager to KeyHub

in this guide you will be taken through the steps to:

  • Create an OIDC application in KeyHub.

  • Create a credential entry linked to KeyHub in RDM.

You need a group in KeyHub to connect to your application.

11.1. In KeyHub

11.1.1. Step 1

  • Click MANAGE ACCESS

devo oidc001

11.1.2. Step 2

  • Click Add

  • Choose Type: OAuth2/OIDC

  • Click NEXT

devo oidc002

11.1.3. Step 3

  • Choose a name

  • Select your Technical administrators group

  • Select the group with ownership

  • Deselect Confidential (RDM does not support this)

  • Fill in the application URI (this can be found in the create credential window in RDM)

  • Select Allowed scopes: Profile and Access your vaults

  • Click SAVE

devo oidc003

11.1.4. Step 4

  • Click your newly made OIDC application

  • Click Groups

  • Click ADD

  • Select the group you want

  • Click SEND

devo oidc005

11.1.5. Step 5

  • Done. Your OIDC Application is ready for use

11.2. In Devolutions RDM

11.2.1. Step 1

In the dashboard Tab

  • Click New Entry

devo001

11.2.2. Step 2

  • Select Credential Entry

  • Select Topicus KeyHub Credential Entry

  • Click OK

devo002

11.2.3. Step 3

  • Choose a Name

  • Fill in the Server URL

  • Fill in the Application ID

  • Choose a Mode

    • Default will let you select a specific record form the vault

    • Always prompt with list will prompt when you start a RDP session

    • Rotating password will get your KeyHub username and rotating password

  • Click OK

devo003
If you are not logged in to KeyHub you will be prompted to login in your browser.
You can copy the Application ID in KeyHub. Go to MANAGE ACCESS and select the Devolutions OIDC application you allready made. The Application ID is the Client Identifier you’ll find at the bottom.
devo004

11.2.4. Step 4

Test your credential.

  • In the Navigation Pane right click your newly made credential

  • Select View Password

  • A window pops up and shows the credentials from you’re vault

devo005

11.2.5. Step 5

  • Done. You can now use your newly made credential

12. ASG remote desktop integration with KeyHub

ASG remote desktop can read vault records from KeyHub. This includes the rotating password. The following steps will guide you through the process of configuring ASG remote desktop and KeyHub.

12.1. Prerequisite

  • a KeyHub group for the application

you can either use an existing group or create a new one. The members of this group will be able to read their vaults using ASG remote desktop.

12.2. in the KeyHub console

12.2.1. Step 1

Create a new OIDC app

  • Select MANAGE ACCESS

  • Click ADD

  • Select OAuth2/OIDC from the Type dropdown

add oidc001

12.2.2. Step 2

  • Choose an appropriate name (eg. ASG remote desktop)

  • Choose the technical administration group (can be the group you chose earlier)

  • Choose the ownership group (can be the same group)

  • In the Application URIs you need to add "http://localhost:3017"

  • In scope you need to select Profile and Access your vaults

  • Click SAVE

You need to copy the Secret to add to ASG remote desktop now. It will not be visible again.

You can also make note of the Client identifier. You will need it later.

group001

12.2.3. Step 3

  • Select the group tab

  • add the KeyHub group you want to use

group004
  • Done!

12.3. In ASG Remote desktop manager

12.3.1. Step 1

  • Select Tools

  • Select Settings

asg guide002

12.3.2. Step 2

  • Under Environment choose Extensions

  • Select Topicus KeyHub integration

  • Click OK

  • A popup will notify you that ASG needs to restart.
    Click Yes

asg guide003

12.3.3. Step 3

  • Navigate back to Tools, Settings and select Topicus KeyHub

  • Fill in your KeyHub host URL (in our case "https://test.topicus-keyhub.com")

  • Fill in the Client ID noted earlier

  • Fill in the Client secret noted earlier

  • Click OK

asg guide005

12.3.4. Step 4

  • Create a new private folder

asg guide011
asg guide012
  • Right click the created folder and select Properties

asg guide014
  • Select Topicus KeyHub

  • Click Synchronize now

asg guide017

A browsertab will open

  • Log in to KeyHub

  • Approve the access

asg screens dl2006
You can ignore the unreachable webpage that pops up.

ASG will show a popup that the sychronization has finished

  • Click OK twice

You will see that the vaults you are allowed to access in KeyHub now show up in the created folder.

12.3.5. Step 5

create a credential for your KeyHub rotating password

  • Right click the created folder and select New, Credential

  • In General you only need to fill in a name

asg guide007
  • In Options you will need to fill in your KeyHub username

  • You will also need to fill in a password.
    this can be anything as it will be overwritten by the rotating password on synchronization

  • For domain accounts you will also need to fill in the domain name

asg guide008
  • In Topicus KeyHub you need to select Use rotating password option

asg guide009
  • Click OK

  • Rightclick the folder containing this credential and select Get Rotating Password

get rotating
You can ignore the unreachable page.

ASG will show a popup that the sychronization has finished

  • All done!

13. Creating webhooks in KeyHub for Splunk

In KeyHub you can send audit log events to applications that can receive webhooks. This guide takes you through the steps to send audit log events from KeyHub to Splunk using webhooks.

13.1. In Splunk

13.1.1. Step1

  • Log in to Splunk

  • Navigate to Settings

  • Click Data inputs

keyhub splunk005

13.1.2. Step2

  • Click HTTP Event Collector

keyhub splunk006

13.1.3. Step3

  • Click New Token

keyhub splunk007

13.1.4. Step4

  • Fill in a Name

  • Click Next>, Review> and Submit> in the following screens

keyhub splunk008

13.1.5. Step5

  • Navigate back to HTTP Event Collector (Steps 1 and 2)

  • Copy the Token Value

keyhub splunk012

13.2. In KeyHub

13.2.1. Step1

  • From the menu ADMINISTRATION click GROUPS

  • Select the WEBHOOKS tab

  • Click ADD

keyhub splunk001

13.2.2. Step2

  • Fill in the URL with <FQDN> your Splunk server
    http://<FQDN>:8088/services/collector/raw

  • If you have a certificate installed on your Splunk server use TLS Yes

  • Select Custom at Authentication scheme

  • Fill in Authorization at Header name

  • Fill in Splunk <Splunk Token> with <Splunk Token> the copied token from Splunk Step5

  • Select the Events you want to sent to Splunk

  • Click SAVE

keyhub splunk002

13.2.3. Step3

  • Done

keyhub splunk003
You can review delivered webhooks by clicking on the newly made webhook
keyhub splunk004