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.