Skip to main content

​
About Active Directory (on-prem)

Active Directory (AD) is Microsoft’s on-premises directory service used to manage users, groups, and resources across an organization. Connecting Active Directory to Serval enables automated user provisioning, group management, and access control directly from your service desk workflows.

​
What the Active Directory integration enables

CapabilityDescription
User ManagementSearch, create, modify, and deactivate AD user accounts
Group ManagementSearch groups, list members, add and remove users from groups
Access ManagementAutomate group-based access provisioning and deprovisioning
Directory SyncAutomatically sync AD users and groups into Serval
Custom OperationsCreate, modify, and delete arbitrary directory entries

​
Active Directory Configuration

​
1. Create a Service Account

Create a dedicated service account in Active Directory for Serval. This account will be used to bind (authenticate) to your directory.
  1. Open Active Directory Users and Computers
  2. Create a new user in an appropriate OU (e.g., OU=ServiceAccounts)
    • Example: CN=svc-serval,OU=ServiceAccounts,DC=corp,DC=example,DC=com
  3. Set a strong password and configure the account so the password does not expire
  4. Grant the account read access to the OUs containing your users and groups
  5. If you need Serval to manage group membership (add/remove users), grant write access to the relevant group objects
For read-only use cases (syncing users and groups), the default “Domain Users” membership is typically sufficient. For write operations (adding users to groups, resetting passwords), the service account needs delegated permissions on the target OUs.

​
2. Determine Your Connection Details

You’ll need the following information from your AD environment:
DetailExampleHow to find it
Server URLldaps://dc01.corp.example.com:636Your domain controller’s hostname or IP
Base DNDC=corp,DC=example,DC=comYour domain’s root distinguished name
Bind DNCN=svc-serval,OU=ServiceAccounts,DC=corp,DC=example,DC=comThe full DN of the service account created in step 1
Bind Password—The service account password
You can find your Base DN by running this command on a domain-joined machine: 
# PowerShell
(Get-ADDomain).DistinguishedName
Or from a Linux machine: 
ldapsearch -x -H ldap://dc01.corp.example.com -s base namingContexts

​
3. Choose a Connection Method

Serval supports two connection methods, both encrypted by default:
MethodURL schemeDefault portHow it works
LDAPS (recommended)ldaps://636TLS is established immediately on connect
StartTLSldap://389Connects on the plain LDAP port, then upgrades to TLS
By default, all connections require TLS (minimum TLS 1.2). When you use ldap://, Serval automatically upgrades the connection via StartTLS.

​
Allow Plaintext LDAP

If your environment cannot support TLS (e.g. certificate issues) and the connection is already secured at the network layer (VPN or tunnel), you can enable the Allow plaintext LDAP toggle in the integration configuration. This skips the StartTLS upgrade for ldap:// connections.
Enabling plaintext LDAP transmits credentials and data unencrypted. Only enable this when TLS is handled at the network layer. Some Active Directory operations such as password resets require TLS and will fail over plaintext LDAP.

​
Using a Custom CA Certificate

Most on-premises Active Directory environments use certificates signed by an internal Certificate Authority (CA). Since Serval’s worker won’t trust your internal CA by default, you need to provide the CA certificate so it can verify the domain controller’s identity during the TLS handshake.
You need the root CA certificate (or the full chain), not the domain controller’s own server certificate. If your CA hierarchy has intermediate CAs, include the entire chain in a single PEM file.
Finding Your CA Certificate
There are several ways to obtain the CA certificate, depending on what you have access to. Option 1: From the domain controller (simplest) Run this on the domain controller or any domain-joined machine with certutil available: 
certutil -ca.cert ca.pem
This exports the CA certificate directly in PEM format. Option 2: From the Windows certificate store On any domain-joined machine, find and export the root CA from the trusted root store: 
# List root CAs to find the correct one
Get-ChildItem Cert:\LocalMachine\Root | Format-Table Subject, Thumbprint

# Export it by matching the subject name (replace "YourCA" with your CA's name)
$cert = Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*YourCA*" }
Export-Certificate -Cert $cert -FilePath ca.cer
certutil -encode ca.cer ca.pem
Option 3: Using openssl from any machine with network access If you can reach the domain controller over the network but aren’t on a domain-joined Windows machine: 
# Connect to the LDAPS port and extract the CA certificate chain
openssl s_client -connect dc01.corp.example.com:636 -showcerts </dev/null 2>/dev/null \
  | sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' > chain.pem
The last certificate in the output is typically the root CA. If there are multiple certificates, save the full chain — Serval will use it to build the trust path. Option 4: From AD CS web enrollment If your organization runs Active Directory Certificate Services, the CA certificate is usually available at: 
http://<ca-server>/certsrv
Navigate to Download a CA certificate, certificate chain, or CRL, select the root CA, choose Base 64 encoded, and download it.
Converting to PEM Format
Serval requires the certificate in PEM format (a text file starting with -----BEGIN CERTIFICATE-----). If you have a certificate in DER (binary) format instead, convert it: Windows: 
certutil -encode ca.cer ca.pem
Linux / macOS: 
openssl x509 -inform der -in ca.cer -out ca.pem
Verifying the Certificate
Before entering the certificate into Serval, confirm it completes a TLS handshake with your domain controller: 
openssl s_client -connect dc01.corp.example.com:636 -CAfile ca.pem
Look for Verify return code: 0 (ok) in the output. If you see a verification error, the certificate may be incorrect or incomplete (e.g., missing an intermediate CA).
If LDAPS Is Not Enabled on Your Domain Controller
If your domain controller doesn’t have LDAPS enabled (port 636 is not listening), you’ll need to provision a server certificate for it before configuring the Serval integration. Common approaches:
  • Active Directory Certificate Services (AD CS): Install the AD CS role and configure auto-enrollment. Domain controllers will automatically request and install LDAPS certificates.
  • Manual certificate enrollment: Request a certificate from your internal CA with the domain controller’s FQDN as the subject, and install it in the domain controller’s personal certificate store.
  • Third-party CA: Obtain a certificate from an external CA for the domain controller’s FQDN and install it.
After the domain controller has a certificate, LDAPS becomes available automatically — no AD restart is required (it may take up to an hour, or you can restart the Active Directory Domain Services service).
Generating a self-signed certificate for LDAPS is not recommended. Active Directory clients and Serval both need to trust the issuing CA, and distributing self-signed trust is error-prone. Use your organization’s internal CA instead.

​
Serval Configuration

  1. In Serval, navigate to Apps → Available → Active Directory (on-prem) → Connect
  2. Enter the following information:
    FieldDescription
    Server URLYour domain controller URL (e.g., ldaps://dc01.corp.example.com:636)
    Base DNThe root DN for your domain (e.g., DC=corp,DC=example,DC=com)
    Bind DNThe full DN of your service account
    Bind PasswordThe service account password
    CA Certificate(Optional) PEM-encoded CA certificate for verifying the LDAP server’s TLS certificate
  3. Click Save
Serval will validate the connection by performing a test bind against your directory. If the connection succeeds, the integration is ready to use.
You should now be able to build workflows that manage Active Directory users, groups, and access.

​
How It Works

The Active Directory integration runs on your self-hosted worker. When a workflow executes an AD action:
  1. The worker’s LDAP proxy retrieves the stored connection credentials
  2. A TLS connection is established to your domain controller (LDAPS or StartTLS), unless plaintext LDAP is explicitly enabled
  3. The proxy binds using your service account credentials
  4. The requested LDAP operation is executed
  5. Results are returned to your workflow
Each operation uses a fresh connection (connect → bind → execute → close) to avoid stale connection issues. All credentials are stored encrypted and are only accessible to Serval’s internal credential proxy — they are never exposed to the workflow execution environment.

​
Troubleshooting

​
”Connection refused” or “No route to host”

The worker cannot reach the domain controller:
  • Verify the domain controller hostname/IP is correct
  • Confirm the correct port is open (636 for LDAPS, 389 for StartTLS/LDAP)
  • Check firewall rules between the worker host and the domain controller
  • Test connectivity from the worker host: telnet dc01.corp.example.com 636

​
”TLS handshake failure” or “Certificate verification failed”

The worker cannot verify the domain controller’s TLS certificate:
  • If your DC uses an internal CA, provide the CA certificate in the configuration (see Using a Custom CA Certificate above)
  • Ensure the certificate is in PEM format (starts with -----BEGIN CERTIFICATE-----)
  • Verify the certificate hasn’t expired: openssl x509 -in ca.pem -noout -dates
  • Check that the certificate’s subject or SAN matches the hostname in your Server URL
  • If your CA has intermediate certificates, include the full chain in the CA Certificate field
  • Verify the certificate works from the worker host: 
    openssl s_client -connect dc01.corp.example.com:636 -CAfile ca.pem

​
“How do I know which certificate to use?”

If you’re unsure which certificate to provide, inspect the certificate chain your domain controller presents: 
openssl s_client -connect dc01.corp.example.com:636 -showcerts </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -subject
The issuer field tells you which CA signed the domain controller’s certificate. You need to provide that CA’s certificate (and any intermediates in the chain) in the Serval configuration. See the Finding Your CA Certificate section for export instructions.

​
”Invalid credentials” or “Bind failed”

The service account credentials are incorrect:
  • Verify the Bind DN is the full distinguished name (not just the username)
  • Confirm the password is correct — test with ldapsearch from the worker host: 
    ldapsearch -x -H ldaps://dc01.corp.example.com:636 \
  -D "CN=svc-serval,OU=ServiceAccounts,DC=corp,DC=example,DC=com" \
  -W -b "DC=corp,DC=example,DC=com" "(objectClass=user)" dn
  • Check if the account is locked or disabled in AD

​
”No such object” or empty search results

The Base DN doesn’t match your directory structure:
  • Verify the Base DN matches your domain’s root (use (Get-ADDomain).DistinguishedName in PowerShell)
  • If searching for users in a specific OU, check that the OU path is correct

​
”Insufficient access rights”

The service account lacks permissions for the requested operation:
  • For read operations, ensure the account has read access to the target OUs
  • For group membership changes, delegate write access on the group objects
  • For password resets, delegate the “Reset Password” permission on user objects
Need help? Contact support@serval.com for assistance with your Active Directory integration.