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.
- 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.
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.
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.
1.1.3. Step 3 - Adjust network settings (optional)
If needed you can adjust the network settings here by pressing S.
2. Linking an Active Directory
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
2.1.2. Step 2
-
Choose Type:
Active Directory
-
click
NEXT
2.1.3. Step 3
-
Fill the details as mentioned above or your own
-
Click
TEST
-
Click
SAVE
2.1.4. Step 4
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
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)
3.1.2. Step 2
-
open
File
→Add /Remove Snap-in
3.1.3. Step 3
-
Select Certificates
-
Click
Add
-
Click
OK
3.1.4. Step 4
-
Select
My user account
-
Click
Finish
-
Click `OK
3.1.5. Step 5
-
Right click
Personal
(from Console root → Certificates - Current User) -
Select
All tasks
→Request New Certificate
3.1.6. Step 6
-
Click
Next
3.1.7. Step 7
-
Select
User
-
Expand
details
-
Click
Properties
3.1.8. Step 8
-
Select
Subject
tab -
Fill in
cn=keyhub
in the Full DN Value box -
Click
Add
-
Click
OK
3.1.9. Step 9
-
Click
Enroll
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
3.2.2. Step 2
-
Click
Next
3.2.3. Step 3
-
Select
Yes…
-
Click
Next
3.2.4. Step 4
-
Select
Personal Information Exchange
-
Click
Next
3.2.5. Step 5
-
Select
Password
-
Fill in your password
-
Click
Next
3.2.6. Step 6
-
Specify the name and location for your exported certificate
-
Click
Next
-
Click
Finish
-
Click
OK
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
3.4.2. Step 2
-
Select
Add
-
Browse to the and open the .pem certificate file
-
Click
OK
-
Click
OK
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
3.5.2. Step 2
-
From the TLS dropdown menu select
Client authentication
If you have a pinned certificate select Client authentication - Pinnned certificate
|
3.5.3. Step 3
-
Upload your public certificate, private key and fill in your private key password
3.5.4. Step 4
-
Click
TEST
-
Click
SAVE
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
withdn: cn=openssh-openldap,cn=schema,cn=config
-
Replace
cn: {1}openssh-lpk-openldap
withcn: openssh-openldap
-
Replace
cn=openssh-openldap
withcn=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
5. Link to Source Directory
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
5.1.2. Step 2
-
Click
Add
5.1.3. Step 3
-
Choose Type:
Source Directory
-
Click
NEXT
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
It’s a good idea to use a new OU |
5.1.5. Step 5
-
Click
TEST
-
Click
SAVE
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
clickGROUPS
6.1.2. Step 2
-
Click
ADD
6.1.3. Step 3
-
Fill in the desired group name
-
Select the initial manager
-
Click
SAVE
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.
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
7.1.2. Step 2
-
Select
Linked Systems
from the tabs
7.1.3. Step 3
-
Select the
Static account provisioning
box -
Click
SAVE
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.
8.1.2. Step 2
Create the following Organizational Units for provisioning.
-
Create an
OU=KeyHub
-
Create an
OU=groups
in theOU=KeyHub
-
Create an
OU=users
in theOU=KeyHub
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
-
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! |
-
Set your values
Use a generated OID. See Generating an OID.
-
In the container attributes browse to the newly created attribute and open properties.
-
Select "index this attribute"
9.2. Adding a custom Class
-
Set your values
Use a generated OID. See Generating an OID.
-
Add custom attributes as needed
9.3. Adding a auxiliary class to another class
-
Open the properties for the higher level class.
-
Add the class.
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
11.1.2. Step 2
-
Click
Add
-
Choose Type:
OAuth2/OIDC
-
Click
NEXT
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
andAccess your vaults
-
Click
SAVE
11.1.4. Step 4
-
Click your newly made OIDC application
-
Click
Groups
-
Click
ADD
-
Select the group you want
-
Click
SEND
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
11.2.2. Step 2
-
Select
Credential Entry
-
Select
Topicus KeyHub Credential Entry
-
Click
OK
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
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.
|
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
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 theType
dropdown
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
andAccess 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.
12.2.3. Step 3
-
Select the group tab
-
add the KeyHub group you want to use
-
Done!
12.3. In ASG Remote desktop manager
12.3.1. Step 1
-
Select
Tools
-
Select
Settings
12.3.2. Step 2
-
Under
Environment
chooseExtensions
-
Select
Topicus KeyHub integration
-
Click
OK
-
A popup will notify you that ASG needs to restart.
ClickYes
12.3.3. Step 3
-
Navigate back to
Tools
,Settings
and selectTopicus 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
12.3.4. Step 4
-
Create a new private folder
-
Right click the created folder and select
Properties
-
Select
Topicus KeyHub
-
Click
Synchronize now
A browsertab will open
-
Log in to KeyHub
-
Approve the access
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
-
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
-
In
Topicus KeyHub
you need to selectUse rotating password option
-
Click
OK
-
Rightclick the folder containing this credential and select
Get Rotating Password
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
13.1.2. Step2
-
Click
HTTP Event Collector
13.1.3. Step3
-
Click
New Token
13.1.4. Step4
-
Fill in a Name
-
Click
Next>
,Review>
andSubmit>
in the following screens
13.1.5. Step5
-
Navigate back to
HTTP Event Collector
(Steps 1 and 2) -
Copy the
Token Value
13.2. In KeyHub
13.2.1. Step1
-
From the menu
ADMINISTRATION
clickGROUPS
-
Select the
WEBHOOKS
tab -
Click
ADD
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
13.2.3. Step3
-
Done
You can review delivered webhooks by clicking on the newly made webhook |