Active Directory users - Trustelem ADConnect Contents How does it work? Prerequisites Setup on Windows Setup on Linux Debug Updating the connector How does it work? The goal is to use Active Directory as an identity provider for Trustelem. To do so, a connector, Trustelem ADConnect, is installed on a customer Virtual Machine. Using this connector, Trustelem can synchronize and authenticate users selected by Trustelem administrators, based on their AD memberOf. 1/ During the setup, Trustelem ADConnect opens a websocket to admin.trustelem.com using port 443. Note: with the websocket, information is encrypted by TLS protocol and with an additional symmetric encryption. 2/ Trustelem sends search / authentication requests to Trustelem ADConnect using the websocket. 3/ Trustelem ADConnect sends the request to Active Directory using LDAP(S) with the service account running the connector. 4/ Active Directory replies to the request from Trustelem ADConnect using LDAP(S). 5/ Trustelem ADConnect sends the answer to admin.trustelem.com using the websocket Note: thanks to this connector Trustelem does not store any password for Active Directory users. Prerequisites Prepare a VM, Windows Server or Linux, with minimal resources for the OS If you have only one VM which is down, the link to your AD is down too.. The recommendation is 2 VM at least, to have a failover system Download Trustelem ADConnect on the VM (.exe or .tgz depending of the OS) https://dl.trustelem.com/adconnect/ If the VM isn't a Windows Server in the AD domain, you need to open the flow from the VM to a DC tcp port 389 or 636 The flow from the VM to https://admin.trustelem.com should be opened (IP: 185.4.44.22) tcp port 443 A service account with "read only" rights should be created on your Active Directory Setup on Windows Click on Create and select Active Directory. Give a name to the new directory, and optionally a description. Ensure Use a connector is checked. Write down the synchronization ID, then click on Save. On your VM, launch the installation software and paste the synchronization ID then click on Validate the Configuration Configure Trustelem Service. Open Windows Services Manager (you can click on Configure the service). Select Trustelem ADConnect ยป. Right-click, select Properties. On General tab, make sure that Startup type is set to Automatic (Delayed Start). On Log On tab, select This account and enter the technical user's credentials. If the machine is not on the AD domain, you can't use the Log On tab of the service. Create a config.ini file in Trustelem setup directory ldap_addr = ldap://ad_fqdn_or_ip ldap_port = 389 # use the UPN ldap_user = connector@ADdomain ldap_password = xxxx If you want to use LDAPs, change the configuration to: ldap_addr = ldaps://ad_fqdn_or_ip # or ldap_addr = ldaps://ad_fqdn_or_ip?tls_verify # certificate has to be in Trustelem setup directory ldap_port = 636 Launch the service Note: if you used a config.ini file (machine not in the AD domain), the 4th led will be red. Get back to the Trustelem admin dashboard, Directory tab Refresh the page: the connector should show up in the table. Once the connector is up, check the IP address, the server name and the service account (to avoid spoofing), then activate the connector by pushing the "No" button. Setup the appropriate synchronization frequency (nota: a high frequency increases the load of your domain controllers). Select the groups to be synchronized. WARNING: if you synchronize a user who has the same UPN/email as a local Trustelem account, then the 2 accounts will be merged and the password to use will be the one from Active Directory. This often happens when you have a local admin account, and then add new AD accounts. By checking Advanced options, you can define a list of Custom attributes (title, memberOf,objectGUID,userPrincipalName...) to import with the users. Click on Save. Setup on Linux Click on Create and select Active Directory. Give a name to the new directory, and optionally a description. Ensure Use a connector is checked. Write down the synchronization ID, then click on Save. On your VM, launch the installation software from the .tgz file, using ./setup.sh with root rights To complete the configuration, edit /opt/wallix/trustelem-adconnect/config.ini file containing the synchronization id. A sample minimal config.ini would be: service_id = 2jy34wpcohrhdytr6hutym6qfi2l7nnw state_dir = run/ ldap_addr = ldap://ad_fqdn_or_ip ldap_port = 389 # use the UPN ldap_user = connector@ADdomain ldap_password = xxxx # if there is a proxy proxy = https://username:password@proxy_IP:proxy_port If you want to use LDAPs: change the configuration to: ldap_addr = ldaps://ad_fqdn_or_ip # or ldap_addr = ldaps://ad_fqdn_or_ip?tls_verify ldap_port = 636 in order to set up the certificate validation correctly, you need to make sure the certificate is signed by a known CA. Check that the certificate is signed by a CA listed in /etc/ssl/certs. If you need to add it, you can either symlink it from /etc/ssl/certs (the CA will be installed system wide) : ln -nsf /path/to/public.crt /etc/ssl/certs/my-ca-name.crt or you can set an environment variable SSL_CERT_FILE=/path/to/public.crt in the trustelem-adconnect.service file (the CA will be installed only locally, for the trustelem service) : # in file /lib/systemd/system/trustelem-adconnect.service: [Service] Type = simple ExecStart = ... Environment = "SSL_CERT_FILE=/path/to/public.crt" # <- add this line After that, you can start the service with: systemctl start trustelem-adconnect.service Get back to the Trustelem admin dashboard, Directory tab Refresh the page: the connector should show up in the table. Once the connector is up, check the IP address, the server name and the service account (to avoid spoofing), then activate the connector by pushing the "No" button. Setup the appropriate synchronization frequency (nota: a high frequency increases the load of your domain controllers). Select the groups to be synchronized. WARNING: if you synchronize a user who has the same UPN/email as a local Trustelem account, then the 2 accounts will be merged and the password to use will be the one from Active Directory. This often happens when you have a local admin account, and then add new AD accounts. By checking Advanced options, you can define a list of Custom attributes (title, memberOf,objectGUID,userPrincipalName...) to import with the users. Click on Save. Debug The connector doesn't appear in the setup page on the admin page ping admin.trustelem.com on the machine running the connector to verify the outgoing flows verify the synchronization ID verify the proxy setup if the VM is a Windows machine, verify that you clicked on Validate on Trustelem ADConnect program There is no group when I click on Add on the field Sync groups on the field Connector list, click on the i in a circle there is an error on the line Server Link YES watch the error to understand the issue verify the flows from the VM running the connector to the Active Directory verify the service account used for Trustelem AD Connect (UserPrincipalName and password) verify if you have a replication delay between the DC. For example, if you change the service account password just before the setup, the connector may reach an outdated DC that refuses the password. NO verify if the service account has the right to search groups on Active Directory try to refresh the page My group doesn't contain all users If your group is Domain users, it's normal, it can't be used because it is not a real group Verify if the users doesn't have particular profiles which can't be found by the service account Verify if there is a replication delay between the DC. If you create users on a DC, it can take some time to replicate on the DC used by the connector. Verify if your service account has the right to search users in the selected groups Updating the connector The connector Trustelem ADConnect can be updated without any service interruption: Install the latest release of the connector in parallel with your current connector. In the directory tab of the Trustelem administration console, select the relevant directory and ensure the new connector is listed first in order to be used in priority. Ensure that the new connector is working fine by checking its usage statistics, then you can disable the previous connector in the administration console. Finally, you can uninstall the previous connector from your server and then it can be deleted from the Trustelem administration console.