LDAP Authenticator

The LDAP Authenticator is a utility component which enables users to login to the Iguana application with an organization’s Active Directory credentials using LDAP (Lightweight Directory Access Protocol) for external authentication of users. For use with other directory services, the LDAP Authenticator component will need to be modified.

When a user logs into Iguana through LDAP, Iguana assigns the User a Role Tag corresponding to the user’s Active Directory Group. For example, if in the Active Directory, user John was a member of the groups dev and support then in Iguana, John would have the tags #dev and #support.

If a Role matching the #tag already exists in Iguana, the defined permissions will be in effect. If a new #tag is assigned, a corresponding Role will need to be created with defined permissions.

Connecting the LDAP Authenticator component to your Active Directory

STEP 1: Create an Iguana Service Account in Active Directory Server

Prior to setting up the LDAP Authenticator component, you will need to create an Iguana Service account in your Active Directory. This user account will be used as a service account. Iguana will use this account’s credentials to authenticate the users trying to login and update the information of users logged in through LDAP.

In your Active Directory Server:

In the menu bar, click Actions > New > User
Provide a firstname, lastname, and user logon name - e.g., IguanaService@interfaceware.biz.
Configure a password. Review the user object details and click Finish.

STEP 2: Import the LDAP Authenticator Component and open the component card

On the Iguana Dashboard, go to +Component and search for “LDAP Authenticator“, select the component and click Add. See Create a Component if this is your first time.

STEP 3: Copy the Component GUID from the browser address bar

Copy your unique component GUID from the browser address bar. This will be used to create one of the Environmental Variables in the next step.

Screen Shot 2024-03-04 at 11.01.44 AM.png

STEP 4: Create two environmental variables in Iguana Settings > Environment

In Settings > Environment, click create and add the following variables:

Set IFW_EAUTH_COMPONENT to the Component GUID (copied in the last step)
Set IFW_EAUTH_POLL_INTERVAL to a frequency in seconds for the LDAP user cache refresh (default 60 seconds)

Screen Shot 2024-03-04 at 10.38.37 AM.png

STEP 5: Add the Active Directory Iguana Service account details to the LDAP Authenticator component card

In the LDAP Authenticator component card, set the following custom fields:

Set the HostUrl field. The host url must begin with ldap:// or ldaps:// and must contain the port number if you are not using the standard ldap ports.
Set the BaseDN field. The BaseDN is an LDAP Distinguished Name that identifies the base object that Iguana uses to search for users. When a user logs in to Iguana, the Iguana Service account will search for a user using the BaseDN as the root for the search.
Set the ServiceUsername and ServicePassword to the credentials of your Iguana Service account. The ServiceUsername must be fully qualified with the domain, for example IguanaService@example.com instead of just IguanaService.

Screen Shot 2024-03-04 at 11.08.27 AM.png

STEP 6: Create an #ldap role to restrict access to the component and its logs

To secure the LDAP component and it's logs, create a #ldap Component Role in Iguana Settings > Roles to match up with the #ldap component Tag. Using a component tag matched with a role tag, we can restrict the access to interact with the LDAP component to only the admin user and those users with the #ldap Role assigned to them.

Note: You can use any naming convention required to match a specific AD Group that exists, instead of #ldap. Only users in this group will have full access to the LDAP Authenticator component.

The #ldap Role should have all permissions applied:

Screen Shot 2024-03-22 at 2.15.28 PM.png

For Linux only, a manual build of curl to query the Active Directory server

The component uses curl to query the active directory server. For Windows, a version of the curl binary is shipped with the component.

Check if curl is installed on your Linux machine – if your system does not have a version of curl that supports ldap, follow the directions below to build curl.

curl --version

OUTPUT:
curl 8.6.0 (x86_64-pc-linux-gnu) libcurl/8.6.0 OpenSSL/3.0.8 OpenLDAP/2.4.57
Release-Date: 2024-01-31
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IPv6 Largefile NTLM SSL threadsafe TLS-SRP UnixSockets

These steps show building curl from source for Amazon Linux. For other flavours of linux, adjust the commands accordingly (some common alternatives are included after the steps).

Step 1: Get the latest curl download from the curl website download page.

wget https://curl.se/download/curl-8.11.0.tar.gz

Step 2: Use tar to extract the files.

tar -xzf curl-8.6.0.tar.gz

Step 3: cd into the curl folder.

cd curl-8.6.0/

Step 4: Install gcc if needed.

sudo yum install gcc

Step 5: Install openldap-devel.x86_64 if needed.

sudo yum install openldap-devel.x86_64

Step 6: Install openssl-devel.x86_64 if needed.

sudo yum install openssl-devel.x86_64

Step 7: Run the command to configure and enable ldap.

./configure --enable-ldap --with-openssl --without-libpsl

Step 8: Compile the source code.

make

Step 9: Install source code.

sudo make install

Step 10: Check curl version and make sure LDAP is present in the Protocols list.

curl --version

OUTPUT:
curl 8.6.0 (x86_64-pc-linux-gnu) libcurl/8.6.0 OpenSSL/3.0.8 OpenLDAP/2.4.57
Release-Date: 2024-01-31
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IPv6 Largefile NTLM SSL threadsafe TLS-SRP UnixSockets

Install commands will vary on ARM Amazon Linux etc., for example:

Step 4: Install gcc if needed.

Ubuntu ARM and Intel: sudo apt install gcc
Red Hat and Fedora ARM and Intel: sudo dnf install gcc

Step 5: Install openldap if needed.

Amazon ARM: sudo yum install openldap-devel
Ubuntu ARM and Intel: sudo apt install libldap2-dev
Red Hat and Fedora ARM and Intel: sudo dnf install openldap-devel

Step 6: Install openssl if needed.

Amazon ARM: sudo yum install openssl-devel
Ubuntu ARM and Intel: sudo apt install libssl-dev
Red Hat and Fedora ARM and Intel: sudo dnf install openssl-devel

STEP 7: Done! Logout and use your Active Directory credentials to login to Iguana

Users can now login to Iguana using their Active Directory credentials!

The component will start automatically and run whenever a user logs in to Iguana. The Iguana Service account will try to authenticate the user credentials using Active Directory. When logging in, you must use your Active Directory User Principal Name (UPN) as the username and password. UPN uses the standard format: username@domain_name.

When logged in as an externally authenticated user, you’ll see that any roles matching Active Directory groups are applied.