Skip to content

Keycloak + Active Directory LDAPS Integration Guide

Beginner Friendly – First Time Setup (10 Year Certificates)

This guide walks you step‑by‑step through integrating Keycloak with Microsoft Active Directory using LDAPS (LDAP over SSL/TLS).

By the end of this guide you will have:

  • Secure LDAPS communication
  • Keycloak authentication against Active Directory
  • Password reset from Keycloak into AD
  • A 10‑year internal PKI for LDAPS certificates

1. Architecture Overview

Users
│
▼
Keycloak (SelfService)
│
│ LDAPS (TCP 636)
▼
Active Directory Domain Controller
DC01.inst.edu.gh

2. Environment Used

Component Value
Domain inst.edu.gh
Domain Controller DC01.inst.edu.gh
Keycloak Server wskck
LDAP Port 636
Protocol LDAPS

3. Prerequisites

Before starting ensure the following:

Requirement Description
Windows Server Domain Controller installed
Domain Active Directory domain configured
Keycloak Installed on Linux
Admin Privileges Domain Admin
Network TCP 636 reachable from Keycloak

4. Install Active Directory Certificate Services

LDAPS requires a trusted certificate on the Domain Controller.

Install the Certificate Authority role.

Install-WindowsFeature ADCS-Cert-Authority -IncludeManagementTools

Configure an Enterprise Root CA with 10 year validity:

Install-AdcsCertificationAuthority `
-CAType EnterpriseRootCA `
-CryptoProviderName "RSA#Microsoft Software Key Storage Provider" `
-KeyLength 2048 `
-HashAlgorithmName SHA256 `
-ValidityPeriod Years `
-ValidityPeriodUnits 10

Open the CA console:

certsrv.msc

You should see your CA (example: inst-DC01-CA).

5. Create a 10 Year Domain Controller Certificate

Open the template manager:

certsrv.msc → Certificate Templates → Manage

Duplicate the template:

Domain Controller Authentication

Configure:

Template Name:

DC01-LDAPS-10Y

Settings:

  • Validity period: 10 years
  • Hash algorithm: SHA256
  • Key length: 2048
  • Allow Domain Controllers group
  • Read
  • Enroll
  • Autoenroll

Publish the template:

certsrv.msc
→ Certificate Templates
→ New
→ Certificate Template to Issue

Select:

DC01-LDAPS-10Y

6. Force the Domain Controller to Enroll the Certificate

gpupdate /force
certutil -pulse

Verify certificate:

Get-ChildItem Cert:\LocalMachine\My |
Where-Object {$_.Subject -match "DC01"} |
Select Subject, Issuer, NotAfter

The NotAfter date should be 10 years ahead.

7. Verify LDAPS Port

Check that the Domain Controller is listening on port 636.

netstat -ano | findstr :636

Confirm the process:

tasklist /fi "PID eq <PID>"

Expected process:

lsass.exe

8. Test LDAPS Locally

Run:

ldp.exe

Connection settings:

Server:

dc01.inst.edu.gh

Port:

636

Enable:

SSL

Expected result:

Host supports SSL
Established connection

9. Export the CA Certificate

Open:

certsrv.msc

Right click the CA → Properties

View Certificate → Details → Copy to File

Export format:

Base‑64 encoded X.509 (.CER)

Example file:

inst-DC01-CA.cer

10. Install CA Certificate on the Keycloak Server

Copy the file to the Linux server.

Install it into the trust store:

sudo cp inst-DC01-CA.cer /usr/local/share/ca-certificates/inst-DC01-CA.crt
sudo update-ca-certificates

Verify TLS trust:

openssl s_client -connect dc01.inst.edu.gh:636

Expected output:

Verify return code: 0 (ok)

11. Create LDAP Service Account

Open Active Directory Users and Computers:

dsa.msc

Create a user:

keycloak-ldap

Recommended configuration:

  • Password never expires
  • User cannot change password

User Principal Name:

keycloak-ldap@inst.edu.gh

12. Test LDAP Bind from Keycloak Server

ldapwhoami -H ldaps://dc01.inst.edu.gh:636 -D "keycloak-ldap@inst.edu.gh" -W

Expected output:

u:GARNET\keycloak-ldap

13. Delegate Password Reset Permissions

In Active Directory Users and Computers:

Right click the OU containing your users.

Select:

Delegate Control

Add:

keycloak-ldap

Choose:

Reset user passwords and force password change at next logon

Finish the wizard.

14. Configure LDAP Federation in Keycloak

Open Keycloak Admin Console.

Navigate to:

User Federation → Add Provider → LDAP

Configuration:

Vendor:

Active Directory

Connection URL:

ldaps://dc01.inst.edu.gh:636

Bind DN:

keycloak-ldap@inst.edu.gh

Users DN:

DC=inst,DC=edu,DC=gh

Recommended settings:

Edit Mode:

WRITABLE

Import Users:

ON

Use Truststore SPI:

Always
Keycloak Attribute LDAP Attribute
Username sAMAccountName
Email mail
First Name givenName
Last Name sn
UUID objectGUID

Object classes:

person
organizationalPerson
user

16. Test the Connection

In Keycloak click:

Test Connection

Then:

Test Authentication

Both should return Success.

17. Test Password Reset

In Keycloak:

Users → Select User → Credentials → Reset Password

Set a new password.

Verify using LDAP:

ldapwhoami -H ldaps://dc01.inst.edu.gh:636 -D "user@inst.edu.gh" -W

Login should succeed with the new password.

18. Notes About Active Directory Password Behavior

Immediately after a password reset, Active Directory may temporarily accept the previous password.

This is normal and usually lasts 1‑2 minutes.

Final Result

You now have:

  • Secure LDAPS authentication
  • Keycloak integrated with Active Directory
  • Password resets from Keycloak into AD
  • 10 year PKI infrastructure for LDAPS