Topicus KeyHub
99
Topicus KeyHub The key to next level security keyhub-20.0-2
Transcript of Topicus KeyHub
Topicus KeyHubkeyhub-20.0-2
1. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. ESX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Configuration details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Prepare a client certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Export the client certificate and key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3. Convert the PFX to a certificate and private key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4. Prepare the Active Directory user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5. Configure KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1. Installing OpenLDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.2. Configuring TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.3. Step 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5. Install PBKDF2 module on OpenLDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5. Link to Source Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
8.1. In Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
9. Active Directory Schema Attributes and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.1. Adding a custom attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.2. Adding a custom Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
9.3. Adding a auxiliary class to another class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
9.4. Generating an OID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.5. sshPublicKey Attribute for KeyHub provisioning in Active Directory . . . . . . . . . . . . . . . . . . . . . 69
10. Convert pfx certificate container to PEM format certificate and key . . . . . . . . . . . . . . . . . . . . . . . . . 70
11. Connecting Devolutions Remote Desktop Manager to KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
11.1. In KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
12. ASG remote desktop integration with KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
12.1. Prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
12.3. In ASG Remote desktop manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
13. Creating webhooks in KeyHub for Splunk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
13.1. In Splunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
13.2. In KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
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.
Figure 1. Download and deploy the image
Select an OVF template
Select a name and folder
Specify a unique name and target location
Select a compute resource
Review details
1.1.2. Step 2 - Configure storage & network
Select storage
Select networks
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.
3
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.
4
1.1.3. Step 3 - Adjust network settings (optional)
If needed you can adjust the network settings here by pressing S.
5
6
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
• 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 DN: OU=Groups
• User DN: OU=Users
Detailed info per item can be found in the manual (chapter 14.2)
2.1.1. Step 1
• Click MANAGE ACCESS
• 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
• 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
12
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.
• Prepare a client certificate
• Convert the PFX to a certificate and private key
• Prepare the Active Directory user
• Configure KeyHub
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
13
• Select All tasks → Request New Certificate
16
• Fill in cn=keyhub in the Full DN Value box
• Click Add
• Click OK
• 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
• Select All tasks
• 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
• 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
• Find the user keyhub
• 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
• Find and click the Active Directory you want to configure
31
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
32
3.5.5. Step 5
• Done. You are now using client authentication instead of a bind with username and password.
33
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 -y install openldap-servers openldap-clients
• Copy initial database configuration
systemctl enable slapd
mkdir /root/ldap
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
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
4.1.3. Step 3
• Import basic schemas
35
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
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
36
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
• Create basedomain.ldif configuration file
• Content of basedomain.ldif
Make sure you replace dc=<MY_DOMAIN>, dc=<MY_TLD> with your own domain components.
37
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
38
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
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
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
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
40
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
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
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
42
4.4.3. Step 3
4.4.4. Step 4
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
wget https://files.topicus-keyhub.com/download/pw-pbk2.tar.gz
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
44
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
• 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
46
• 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
47
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
6.1.2. Step 2
• Select the initial manager
• Click SAVE
It’s advised to add at least one more manager after creation
6.1.4. Step 4
49
50
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 the group you want to make statically provisioned
7.1.2. Step 2
51
• Click SAVE
7.1.4. Step 4
• Done. The group will have disappeared from the dashboard as it is now always active.
52
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.
53
54
55
• Create an OU=KeyHub
56
57
58
59
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.
60
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
• 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!
61
• Set your values Use a generated OID. See Generating an OID.
• In the container attributes browse to the newly created attribute and open properties.
62
63
64
9.3. Adding a auxiliary class to another class • Open the properties for the higher level class.
65
66
67
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],$P arts[2],$Parts[3],$Parts[4],$Parts[5],$Parts[6]) $oid
68
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
69
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:
Extract the key:
70
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
• 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
• Click Groups
• Click ADD
73
11.2. In Devolutions RDM
• Click OK
• 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
76
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
78
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
• Select MANAGE ACCESS
79
• 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.
80
• Done!
12.3.1. Step 1
• Click OK
• A popup will notify you that ASG needs to restart. Click Yes
83
• 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
84
85
86
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
• Right click the created folder and select New, Credential
• In General you only need to fill in a name
88
• 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
89
• In Topicus KeyHub you need to select Use rotating password option
90
• 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!
91
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
93
• Navigate back to HTTP Event Collector (Steps 1 and 2)
• Copy the Token Value
• Select the WEBHOOKS tab
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
• Done
You can review delivered webhooks by clicking on the newly made webhook
96
2.1. Configuration details
3.1. Prepare a client certificate
3.2. Export the client certificate and key
3.3. Convert the PFX to a certificate and private key
3.4. Prepare the Active Directory user
3.5. Configure KeyHub
4.5. Install PBKDF2 module on OpenLDAP
5. Link to Source Directory
5.1. In KeyHub
6.1. In KeyHub
7.1. In KeyHub
8.1. In Active Directory
9.1. Adding a custom attribute
9.2. Adding a custom Class
9.3. Adding a auxiliary class to another class
9.4. Generating an OID
9.5. sshPublicKey Attribute for KeyHub provisioning in Active Directory
10. Convert pfx certificate container to PEM format certificate and key
11. Connecting Devolutions Remote Desktop Manager to KeyHub
11.1. In KeyHub
12.1. Prerequisite
12.3. In ASG Remote desktop manager
13. Creating webhooks in KeyHub for Splunk
13.1. In Splunk
13.2. In KeyHub
1. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. ESX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Configuration details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Prepare a client certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Export the client certificate and key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.3. Convert the PFX to a certificate and private key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4. Prepare the Active Directory user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.5. Configure KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.1. Installing OpenLDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.2. Configuring TLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.3. Step 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.5. Install PBKDF2 module on OpenLDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5. Link to Source Directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.1. In KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
8.1. In Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
9. Active Directory Schema Attributes and Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.1. Adding a custom attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.2. Adding a custom Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
9.3. Adding a auxiliary class to another class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
9.4. Generating an OID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.5. sshPublicKey Attribute for KeyHub provisioning in Active Directory . . . . . . . . . . . . . . . . . . . . . 69
10. Convert pfx certificate container to PEM format certificate and key . . . . . . . . . . . . . . . . . . . . . . . . . 70
11. Connecting Devolutions Remote Desktop Manager to KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
11.1. In KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
12. ASG remote desktop integration with KeyHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
12.1. Prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
12.3. In ASG Remote desktop manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
13. Creating webhooks in KeyHub for Splunk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
13.1. In Splunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
13.2. In KeyHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
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.
Figure 1. Download and deploy the image
Select an OVF template
Select a name and folder
Specify a unique name and target location
Select a compute resource
Review details
1.1.2. Step 2 - Configure storage & network
Select storage
Select networks
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.
3
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.
4
1.1.3. Step 3 - Adjust network settings (optional)
If needed you can adjust the network settings here by pressing S.
5
6
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
• 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 DN: OU=Groups
• User DN: OU=Users
Detailed info per item can be found in the manual (chapter 14.2)
2.1.1. Step 1
• Click MANAGE ACCESS
• 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
• 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
12
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.
• Prepare a client certificate
• Convert the PFX to a certificate and private key
• Prepare the Active Directory user
• Configure KeyHub
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
13
• Select All tasks → Request New Certificate
16
• Fill in cn=keyhub in the Full DN Value box
• Click Add
• Click OK
• 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
• Select All tasks
• 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
• 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
• Find the user keyhub
• 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
• Find and click the Active Directory you want to configure
31
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
32
3.5.5. Step 5
• Done. You are now using client authentication instead of a bind with username and password.
33
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 -y install openldap-servers openldap-clients
• Copy initial database configuration
systemctl enable slapd
mkdir /root/ldap
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
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
4.1.3. Step 3
• Import basic schemas
35
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
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
36
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
• Create basedomain.ldif configuration file
• Content of basedomain.ldif
Make sure you replace dc=<MY_DOMAIN>, dc=<MY_TLD> with your own domain components.
37
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
38
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
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
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
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
40
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
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
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
42
4.4.3. Step 3
4.4.4. Step 4
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
wget https://files.topicus-keyhub.com/download/pw-pbk2.tar.gz
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
44
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
• 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
46
• 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
47
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
6.1.2. Step 2
• Select the initial manager
• Click SAVE
It’s advised to add at least one more manager after creation
6.1.4. Step 4
49
50
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 the group you want to make statically provisioned
7.1.2. Step 2
51
• Click SAVE
7.1.4. Step 4
• Done. The group will have disappeared from the dashboard as it is now always active.
52
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.
53
54
55
• Create an OU=KeyHub
56
57
58
59
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.
60
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
• 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!
61
• Set your values Use a generated OID. See Generating an OID.
• In the container attributes browse to the newly created attribute and open properties.
62
63
64
9.3. Adding a auxiliary class to another class • Open the properties for the higher level class.
65
66
67
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],$P arts[2],$Parts[3],$Parts[4],$Parts[5],$Parts[6]) $oid
68
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
69
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:
Extract the key:
70
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
• 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
• Click Groups
• Click ADD
73
11.2. In Devolutions RDM
• Click OK
• 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
76
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
78
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
• Select MANAGE ACCESS
79
• 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.
80
• Done!
12.3.1. Step 1
• Click OK
• A popup will notify you that ASG needs to restart. Click Yes
83
• 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
84
85
86
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
• Right click the created folder and select New, Credential
• In General you only need to fill in a name
88
• 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
89
• In Topicus KeyHub you need to select Use rotating password option
90
• 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!
91
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
93
• Navigate back to HTTP Event Collector (Steps 1 and 2)
• Copy the Token Value
• Select the WEBHOOKS tab
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
• Done
You can review delivered webhooks by clicking on the newly made webhook
96
2.1. Configuration details
3.1. Prepare a client certificate
3.2. Export the client certificate and key
3.3. Convert the PFX to a certificate and private key
3.4. Prepare the Active Directory user
3.5. Configure KeyHub
4.5. Install PBKDF2 module on OpenLDAP
5. Link to Source Directory
5.1. In KeyHub
6.1. In KeyHub
7.1. In KeyHub
8.1. In Active Directory
9.1. Adding a custom attribute
9.2. Adding a custom Class
9.3. Adding a auxiliary class to another class
9.4. Generating an OID
9.5. sshPublicKey Attribute for KeyHub provisioning in Active Directory
10. Convert pfx certificate container to PEM format certificate and key
11. Connecting Devolutions Remote Desktop Manager to KeyHub
11.1. In KeyHub
12.1. Prerequisite
12.3. In ASG Remote desktop manager
13. Creating webhooks in KeyHub for Splunk
13.1. In Splunk
13.2. In KeyHub
