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
│
│ LDAPS (TCP 636)
▼
Active Directory Domain Controller
DC01.garnet.edu.gh
2. Environment Used¶
| Component | Value |
|---|---|
| Domain | garnet.edu.gh |
| Domain Controller | DC01.garnet.edu.gh |
| Keycloak Server | wskck |
| LDAP Port | 636 |
| Protocol | LDAPS |
3. Prerequisites¶
| 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¶
Install-WindowsFeature ADCS-Cert-Authority -IncludeManagementTools
Install-AdcsCertificationAuthority `
-CAType EnterpriseRootCA `
-CryptoProviderName "RSA#Microsoft Software Key Storage Provider" `
-KeyLength 2048 `
-HashAlgorithmName SHA256 `
-ValidityPeriod Years `
-ValidityPeriodUnits 10
Open:
certsrv.msc
5. Create a 10-Year Domain Controller Certificate Template¶
Open:
certsrv.msc → Certificate Templates → Manage
Duplicate:
Domain Controller Authentication
Template Name:
DC01-LDAPS-10Y
Configure:
- Validity: 10 years
- SHA256
- 2048-bit
- Security → Domain Controllers → Read, Enroll, Autoenroll
Publish template:
Certificate Templates → New → Certificate Template to Issue
Select:
DC01-LDAPS-10Y
6. Remove Existing Domain Controller Certificates (CRITICAL)¶
Open:
certlm.msc
Navigate:
Local Computer → Personal → Certificates
Delete certificates matching:
CN=DC01.garnet.edu.gh
Template: DomainController
⚠️ Do NOT delete:
CN=garnet-DC01-CA
Verify only CA certificate remains:
certutil -store My
7. Enroll the New 10-Year Certificate¶
gpupdate /force
certutil -pulse
Verify:
certutil -store My
Expected:
Template: DC01-LDAPS-10Y
NotAfter: 2036
8. Restart the Domain Controller¶
Restart-Computer
9. Verify LDAPS is Listening¶
netstat -ano | findstr :636
Expected process:
lsass.exe
10. Test LDAPS Locally¶
Run:
ldp.exe
Connect using:
- Server: dc01.garnet.edu.gh
- Port: 636
- SSL enabled
Expected:
Established connection
11. Export the CA Certificate¶
Right click CA → Properties → View Certificate → Copy to File
Export:
Base-64 encoded X.509 (.CER)
12. Install CA Certificate on Keycloak Server¶
sudo cp garnet-DC01-CA.cer /usr/local/share/ca-certificates/garnet-DC01-CA.crt
sudo update-ca-certificates
Verify:
openssl s_client -connect dc01.garnet.edu.gh:636
Expected:
Verify return code: 0 (ok)
Also, Even if Linux trusts the certificate, Java may not.
Keycloak runs on Java, which uses its own truststore.
Without this step Keycloak will show:
PKIX path validation failed
Path does not chain with any of the trust anchors
Copy the CA Certificate
sudo cp /usr/local/share/ca-certificates/garnet-DC01-CA.crt /opt/keycloak/conf/truststores/garnet-ad-ca.crt
Create a Keycloak Truststore
sudo keytool -importcert -noprompt -alias garnet-ad-ca -file /opt/keycloak/conf/truststores/garnet-ad-ca.crt -keystore /opt/keycloak/conf/truststores/ad-truststore.p12 -storetype PKCS12 -storepass ChangeThisPassword
Verify:
keytool -list -keystore /opt/keycloak/conf/truststores/ad-truststore.p12 -storetype PKCS12
Restart Keycloak:
sudo systemctl restart keycloak
13. Create LDAP Service Account¶
Create user:
keycloak-ldap
Recommended:
- Password never expires
- User cannot change password
UPN:
keycloak-ldap@garnet.edu.gh
14. Test LDAP Bind¶
ldapwhoami -H ldaps://dc01.garnet.edu.gh:636 -D "keycloak-ldap@garnet.edu.gh" -W
Expected:
u:GARNET\keycloak-ldap
15. Delegate Password Reset Permissions¶
Right click user OU → Delegate Control
Add:
keycloak-ldap
Select:
Reset user passwords and force password change at next logon
16. Configure LDAP Federation in Keycloak¶
Navigate:
User Federation → Add Provider → LDAP
Settings:
Vendor: Active Directory\ Connection URL:
ldaps://dc01.garnet.edu.gh:636
Bind DN:
keycloak-ldap@garnet.edu.gh
Users DN:
DC=garnet,DC=edu,DC=gh
Recommended:
- Edit Mode: WRITABLE
- Import Users: ON
- Use Truststore SPI: Always
17. Recommended Attribute Mapping¶
Keycloak LDAP
Username sAMAccountName Email mail First Name givenName Last Name sn UUID objectGUID
Object Classes:
person
organizationalPerson
user
18. Test in Keycloak¶
Click:
Test Connection
Test Authentication
19. Test Password Reset¶
Reset in Keycloak → Credentials.
Verify:
ldapwhoami -H ldaps://dc01.garnet.edu.gh:636 -D "user@garnet.edu.gh" -W
Final Result¶
You now have:
- Secure LDAPS authentication
- Keycloak integrated with Active Directory
- Password resets from Keycloak into AD
- 10-year PKI infrastructure