Active Directory synchronization

How does it work?

The goal is to use Active Directory as an identity provider for Trustelem.

To do so, a connector, ADConnect, is installed on an Active Directory domain controller.

Using this connector, Trustelem synchronizes the users defined by Trustelem administrators.

1/ During the setup, ADConnect opens a websocket to Trustelem services using port 443.
Note: with the websocket, information is encrypted by TLS protocol and with an additional symmetric encryption.

2/ Trustelem sends the request of Active Directory users to ADConnect using the websocket.

3/ ADConnect asks the users to Active Directory using LDAPS.

4/ Active Directory sends the users to ADConnect using LDAPS.

5/ ADConnect sends the users to Trustelem services using the websocket

Note: the connector also does the authentication of Active Directory users:

an AD user tries to authenticate on Trustelem
Trustelem sends the user and his password to ADConnect using the websocket (encrypted with TLS and the additional symmetric encryption)
ADConnect sends the user and his password to Active Directory (encrypted with LDAPS)
Active Directory sends a validation to ADConnect
ADConnect sends the validation to Trustelem
Trustelem authenticates the user

Trustelem does not store any Active Directory password.

Trustelem AD Connect Setup

On your Windows Server, in « Active Directory Users and Groups »

Create a technical user (ex. connecteur@mycompany.com) with default privileges (read only) and a strong password, with no password update on next login and which never expires.

On Trustelem admin dashboard, « Directory » tab

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 each AD domain controller (typically 2 or 3)

Download the last version of the connector installer: https://dl.trustelem.com/adconnect/
Launch the installation software and paste the synchronization ID.
Configure the Trustelem Windows Service.
- Open Windows Services Manager.
- Select « Trustelem AD Connect ».
- 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 your doesn't use the Log On tab of the service (machine not in the AD domain), the 4th can 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.

By checking Advanced options, you can define a list of Custom attributes (title, memberOf,objectGUID,userPrincipalName...) to import with the users.
Click on « Save ».

The synchronization starts. It lasts a few seconds

Note :

The user identity on Trustelem is based on the email. In the case of AD users, Trustelem email will be the AD email adress if existing, and if not the UPN.
If a user already exists on Trustelem with this email adress, the 2 users will be merged.
It's usually the case with the first local admin created at the subscription creation.
In case of multiple AD connectors for a same Active Directory, Trustelem speaks with the first one (for synchronization and authentication) and if it is not responding, then Trustelem asks to the next one.

Trustelem AD Connect on a Unix machine

Follow the steps of the previous part, but instead of the AD setup :

Download the tgz version of the connector
Install the connector as a service with the setup.sh script.
To complete the configuration, please complete /opt/wallix/trustelem-connect/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

The run folder must have read write rights for the trustelem user.
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 cerificate 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-connect.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
If the target directory is not an Active Directory, provide your directory Base DN in the Trustelem directory setup page

Updating the connector

The connector 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.

Problem of missing users/groups from Active Directory sync/import

On some restricted configurations, the user running the Trustelem connector may not have enough rights to correctly list all users/groups from the directory.

To ensure that this user has the required rights:

On Windows Server 2008:
- Open "Active Directory Users and Groups".
- Right-click on your domain object.
- Go to Properties".
- Go to Security tab and click on Advanced.
- Click on "Add".
- Enter the user name used to run the connector.
- Click the "Properties" tab.
- In "Apply Onto" change the type to User.
- Ensure the "Read MemberOf" checkbox is checked.
On Windows Server 2012:
- Open ADSI Edit.
- Right-click on your domain object.
- Go to Properties.
- Go to Security tab and click on Advanced.
- Click on "Add".
- Click on "Select a Principal" and pick the user used by the connector.
- In 'Apply Onto' change the type to "This object only".
- Scroll to "Properties", find "Read MemberOf" and ensure it is checked.