Azure AD LDAP

This guide explains how to integrate HridaAI with Azure AD Domain Services (AAD DS) for secure LDAP (LDAPS) authentication.

1. Prerequisites

Item	Description
Azure Account	An account with permissions to deploy AAD DS and modify NSGs.
OpenSSL 3.x	Required to generate a self-signed PFX for testing.
Domain Name	We'll use hridaai.onmicrosoft.com as an example (your AAD primary domain).
HridaAI Server	A running instance of HridaAI, deployed via Docker or bare-metal.

caution

In a production environment, use a PFX certificate issued by a public Certificate Authority (CA) and set LDAP_VALIDATE_CERT=true.

2. Deploy Azure AD Domain Services

1. In the Azure Portal, search for and select Azure AD Domain Services.

2. Click Create.

3. Select your Subscription and Resource Group (or create a new one).

4. For DNS domain name, enter your domain (e.g., hridaai.onmicrosoft.com). This value will be used for LDAP_SEARCH_BASE later.

5. Keep the default settings for SKU, Replica Set, etc., and click Review + create.

   

6. After deployment, navigate to the Azure AD DS blade and note the Virtual network / Subnet. If your HridaAI server is not in the same VNet, you must create an NSG rule to allow traffic on port 636.

3. Find the Secure LDAP External IP

1. Navigate to your AAD DS Blade → Overview.

2. Under Secure LDAP, find the External IP addresses.

3. This IP (e.g., 1.222.222.222) will be your LDAP_SERVER_HOST value in the .env file.

   

4. Enable Secure LDAP (LDAPS)

4.1. Certificate (PFX) Requirements

Attribute	Requirement
Format	PKCS #12 (.pfx)
Encryption	RSA 2048 / SHA-256
Subject Alternative Name (SAN)	Must include wildcards: *.{your_domain}.onmicrosoft.com and {your_domain}.onmicrosoft.com.
Password	Required for upload. Make sure to remember it.

info

For production, we recommend using Let’s Encrypt or another public CA. The self-signed process below is for testing purposes only.

4.2. Generate a Wildcard PFX with OpenSSL (for testing)

1. Create openssl_wildcard.cnf:

   [ req ]
   distinguished_name = req_distinguished_name
   x509_extensions = v3_ca
   req_extensions  = v3_req
   prompt = no
   
   [ req_distinguished_name ]
   C  = US
   ST = CA
   L  = San Francisco
   O  = MyTestOrg
   OU = TestDepartment
   CN = *.{your_domain}.onmicrosoft.com
   
   [ v3_ca ]
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid:always,issuer
   basicConstraints     = critical, CA:FALSE
   keyUsage             = critical, digitalSignature, keyEncipherment
   extendedKeyUsage     = serverAuth
   subjectAltName       = @alt_names
   
   [ v3_req ]
   basicConstraints  = CA:FALSE
   keyUsage          = digitalSignature, keyEncipherment
   extendedKeyUsage  = serverAuth
   subjectAltName    = @alt_names
   
   [ alt_names ]
   DNS.1 = *.{your_domain}.onmicrosoft.com
   DNS.2 = {your_domain}.onmicrosoft.com

   Replace {your_domain} with your actual domain.

2. Generate Key & Certificate:

   # Generate a private key
   openssl genrsa -out privatekey_wildcard.key 2048
   
   # Create a Certificate Signing Request (CSR)
   openssl req -new -key privatekey_wildcard.key \
     -out wildcard.csr -config openssl_wildcard.cnf
   
   # Create a self-signed certificate (valid for 365 days)
   openssl x509 -req -days 365 -in wildcard.csr \
     -signkey privatekey_wildcard.key \
     -out certificate_wildcard.crt \
     -extensions v3_req -extfile openssl_wildcard.cnf
   
   # Package into a PFX file
   openssl pkcs12 -export -out certificate_wildcard.pfx \
     -inkey privatekey_wildcard.key -in certificate_wildcard.crt

3. Upload to AAD DS:

   1. Navigate to your AAD DS Blade → Secure LDAP.
   2. Click the Upload certificate button, select certificate_wildcard.pfx, and enter the password.
   3. Toggle Secure LDAP to Enabled and click Save.

   

5. Configure Network Security Group (NSG)

Setting	Example Value
Name	Allow-LDAPS
Priority	310
Source	Any
Destination Port	636
Protocol	TCP
Action	Allow

warning

If allowing access from the internet, restrict the source IP range to the minimum required for security. If HridaAI is in the same VNet, this step can be skipped.

6. Create a Service Account in Entra ID

1. In the Azure Portal, navigate to Entra ID → Users → New user.

2. Set the username (e.g., ldap@{your_domain}.onmicrosoft.com).

3. Set a strong password and uncheck User must change password at next sign-in.

4. Go to the Groups tab and add the user to the AAD DC Administrators group (required for querying all users).

   

7. Configure HridaAI Environment Variables (.env)

Here is an example configuration for your .env file:

###############################################

# LDAP

###############################################
ENABLE_LDAP="true"
LDAP_SERVER_LABEL="Azure AD DS"
LDAP_SERVER_HOST="1.222.222.222"
LDAP_SERVER_PORT="636"

# TLS Options
LDAP_USE_TLS="true"
LDAP_VALIDATE_CERT="false"          # Set to true for a public CA

#LDAP_CA_CERT_FILE="/etc/ssl/certs/hridaai_ca.crt"

# Bind Account
LDAP_APP_DN="ldap@{your_domain}.onmicrosoft.com"
LDAP_APP_PASSWORD="<STRONG-PASSWORD>"

# Search Scope
LDAP_SEARCH_BASE="DC={your_domain},DC=onmicrosoft,DC=com"
LDAP_ATTRIBUTE_FOR_USERNAME="sAMAccountName"
LDAP_ATTRIBUTE_FOR_MAIL="userPrincipalName"
LDAP_SEARCH_FILTER="(&(objectClass=user)(objectCategory=person))"

# Group Synchronization (Optional)

# ENABLE_LDAP_GROUP_MANAGEMENT="true"

# ENABLE_LDAP_GROUP_CREATION="true"

# LDAP_ATTRIBUTE_FOR_GROUPS="memberOf"

Replace placeholders like {your_domain} and <STRONG-PASSWORD> with your actual values.

8. Configure Group Synchronization (Optional)

HridaAI can synchronize group memberships directly from your LDAP directory. When a user logs in, their group information is fetched and updated within HridaAI.

To enable this feature, add the following environment variables:

• ENABLE_LDAP_GROUP_MANAGEMENT="true": Enables the group management feature.
• ENABLE_LDAP_GROUP_CREATION="true": If a group from LDAP does not exist in HridaAI, it will be created automatically.
• LDAP_ATTRIBUTE_FOR_GROUPS="memberOf": Specifies the LDAP attribute that contains the user's group memberships. memberOf is a standard attribute for this purpose in Active Directory environments.

9. Add CA Certificate to Server (Optional)

To enable full TLS validation (LDAP_VALIDATE_CERT="true"):

sudo cp certificate_wildcard.crt /usr/local/share/ca-certificates/hridaai.crt
sudo update-ca-certificates

Restart HridaAI after making this change.

10. Test LDAPS Connection

10.1. OpenSSL Handshake Check

openssl s_client -connect 1.222.222.222:636 -showcerts

Look for Verify return code: 0 (ok) to confirm the certificate is trusted.

10.2. ldapsearch (Bind Test)

ldapsearch -H ldaps://1.222.222.222 \
  -D "ldap@hridaai.onmicrosoft.com" -w '<PASSWORD>' \
  -b "DC=hridaai,DC=onmicrosoft,DC=com" \
  -s sub "(sAMAccountName=<test_user_id>)"

A successful search will return the details of the specified user.