Skip to main content

​
Overview

RDSWeb Custom uses LDAP to authenticate users against your Active Directory domain. This guide covers the setup of a service account and LDAP configuration.

​
Service Account Requirements

​
Why a Service Account?

The application uses a two-step authentication process:
  1. Service Account Bind: A read-only service account searches for the user in Active Directory
  2. User Credential Validation: The actual user credentials are validated with a direct bind
This is the standard enterprise AD authentication pattern and ensures the service account has minimal privileges.

​
Creating the Service Account

  1. Open Active Directory Users and Computers
  2. Create a new user (e.g., svc-rdweb)
  3. Set a strong password that never expires
  4. Add to Domain Users (no elevated permissions needed)
  5. Grant Read permissions on the directory (default for domain users)
The service account should NOT have Domain Admin privileges. It only needs read access to query user attributes.

​
Environment Configuration

Configure these settings in your .env file: 
# LDAP Connection
LDAP_URL=ldap://dc01.lab-mh.local
LDAP_BASE_DN=DC=lab-mh,DC=local
AD_DOMAIN=LAB-MH

# Service Account (read-only)
# Format: [email protected] or CN=user,OU=Services,DC=domain,DC=local
AD_SERVICE_USER=[email protected]
AD_SERVICE_PASS=YourSecurePassword123!

​
Configuration Parameters

​
LDAP_URL
string
required
LDAP server URL. Use ldap:// for unencrypted or ldaps:// for TLS.Example: ldap://dc01.contoso.local
​
LDAP_BASE_DN
string
required
Base Distinguished Name for LDAP searches.Example: DC=contoso,DC=local
​
AD_DOMAIN
string
required
NetBIOS domain name (used for user normalization).Example: CONTOSO
​
AD_SERVICE_USER
string
required
Service account username. Supports multiple formats:
  • [email protected] (recommended)
  • CN=svc-rdweb,OU=Services,DC=domain,DC=local
  • DOMAIN\svc-rdweb
​
AD_SERVICE_PASS
string
required
Service account password. Store securely and rotate regularly.

​
LDAP Attributes Retrieved

The service queries these Active Directory attributes:
  • sAMAccountName - Username
  • displayName - Full name
  • mail - Email address
  • userPrincipalName - User principal name
  • memberOf - Group memberships
These attributes are used to populate the JWT token and determine application access.

​
Username Formats

RDSWeb Custom accepts multiple username formats:
FormatExampleDescription
UPN[email protected]User Principal Name
Down-levelDOMAIN\userNetBIOS format
SimpleuserUsername only (domain from config)
All formats are normalized internally to query Active Directory correctly.

​
TLS/SSL Configuration

For production deployments, use LDAPS (LDAP over TLS): 
LDAP_URL=ldaps://dc01.contoso.local:636
The current implementation sets rejectUnauthorized: false for TLS connections. In production, you should:
  1. Set rejectUnauthorized: true in backend/src/services/adService.js:107
  2. Install your CA certificate on the Node.js server
  3. Ensure the LDAP server certificate is valid

​
Enabling TLS Certificate Validation

Edit backend/src/services/adService.js: 
const adOptions = {
    ldapOpts: {
        url: config.ldap.url,
        tlsOptions: { 
            rejectUnauthorized: true,  // Change to true
            ca: [fs.readFileSync('/path/to/ca-cert.pem')]
        },
    },
    // ...
};

​
Testing the Connection

Use the health endpoint to verify AD connectivity: 
curl http://localhost:3000/api/health
Then test authentication: 
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"password"}'

​
Troubleshooting

​
Error: “No se pudo conectar al servidor de Active Directory”

  • Verify the LDAP URL is correct and reachable
  • Check firewall rules (port 389 for LDAP, 636 for LDAPS)
  • Ensure DNS resolution works for the domain controller

​
Error: “Credenciales incorrectas”

  • Verify the service account credentials in .env
  • Check the user exists in Active Directory
  • Ensure the user account is not locked or disabled

​
Error: “Usuario no encontrado en Active Directory”

  • Verify LDAP_BASE_DN is correct
  • Check the username format matches AD
  • Ensure the user is in the correct OU within the base DN

​
Group-Based Access Control

User group memberships are extracted from the memberOf attribute and included in the JWT token. You can use these groups for:
  • Application filtering (future feature)
  • Role-based access control
  • Audit logging
See backend/src/services/adService.js:48-52 for the group extraction logic.

​
Security Best Practices

Strong Passwords

Use a complex password for the service account (min 20 characters)

Password Rotation

Rotate the service account password every 90 days

Monitor Access

Enable AD audit logging for the service account

Use LDAPS

Always use encrypted LDAPS in production

​
Related Pages

Build docs developers (and LLMs) love

Get started for freeTalk to us