ForgeRock DS Certificate Troubleshooting Scripts

Diagnose and fix the "PKIX path building failed: unable to find valid certification path to requested target" error in ForgeRock Directory Services (DS).

The Problem

javax.net.ssl.SSLHandshakeException: PKIX path building failed:
  sun.security.provider.certpath.SunCertPathBuilderException:
    unable to find valid certification path to requested target

This error occurs when AM, IDM, or another DS instance cannot verify the TLS certificate during LDAPS connections, replication, or admin operations.

Full Tutorial: ForgeRock DS PKIX Path Building Failed: Complete Certificate Troubleshooting Guide on IAMDevBox.com

Quick Start

# 1. Clone
git clone https://github.com/IAMDevBox/forgerock-ds-cert-troubleshoot.git
cd forgerock-ds-cert-troubleshoot

# 2. Run diagnostic
chmod +x scripts/*.sh
./scripts/diagnose.sh ds.example.com 1636

# 3. Fix (import DS cert into JVM truststore)
sudo ./scripts/fix-import-cert.sh ds.example.com 1636

Scripts

Script	Description
scripts/diagnose.sh	Comprehensive 9-point TLS/certificate health check (connectivity, chain, expiration, SANs, truststore, key strength)
scripts/fix-import-cert.sh	Export DS certificate and import into JVM truststore (with chain support)
scripts/fix-replication-certs.sh	Exchange certificates between DS replication peers
scripts/monitor-expiry.sh	Check certificate expiration across all DS instances (Prometheus-compatible output)

Diagnostic Output

╔══════════════════════════════════════════════════════════════╗
║  ForgeRock DS Certificate Diagnostic                         ║
║  Target: ds.example.com:1636                                 ║
╚══════════════════════════════════════════════════════════════╝

── Check 1: TCP Connectivity ──────────────────────────────────
[PASS]    TCP connection to ds.example.com:1636 succeeded

── Check 2: TLS Handshake ─────────────────────────────────────
[PASS]    TLS handshake completed (TLSv1.3, TLS_AES_256_GCM_SHA384)

── Check 3: Certificate Identity ──────────────────────────────
[WARNING] Certificate is SELF-SIGNED (Subject == Issuer)

── Check 5: Certificate Expiration ────────────────────────────
[PASS]    Certificate valid for 342 days

── Check 8: JVM Truststore ────────────────────────────────────
[FAIL]    Self-signed DS certificate NOT in JVM truststore
          FIX: keytool -importcert -alias forgerock-ds ...

Common Causes & Fixes

Cause	Fix Script
Self-signed DS certificate not in client truststore	fix-import-cert.sh
Missing intermediate CA in certificate chain	fix-import-cert.sh (imports full chain)
Replication peer certificates not trusted	fix-replication-certs.sh
Expired certificate	Renew via dskeymgr (see full tutorial)
Wrong truststore configured	Check boot.json / system.properties (see tutorial)

Certificate Monitoring

# Plain text alerts
./scripts/monitor-expiry.sh --alert-days 30

# Prometheus metrics
./scripts/monitor-expiry.sh --prometheus
# Output:
# forgerock_ds_cert_days_remaining{host="ds-1.example.com",port="1636",label="LDAPS"} 342

Kubernetes

The kubernetes/cert-manager-ds.yaml provides a complete cert-manager setup for automated DS certificate management:

• Internal CA ClusterIssuer
• DS server certificate with proper SANs
• Automatic renewal 30 days before expiry

kubectl apply -f kubernetes/cert-manager-ds.yaml

Related Resources

• ForgeRock DS PKIX Troubleshooting Guide — Full step-by-step tutorial
• ForgeRock Backup and Restore Automation — Production backup scripts
• ForgeRock Config Promotion — CI/CD for ForgeRock configs
• ForgeRock DS Specialist Exam Guide — DS certification study guide
• ForgeRock Deep Dive — Architecture overview of AM, IDM, DS, and IG

License

MIT License — see LICENSE for details.