How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure a CA Signed certificate for replication in DS 5.x or 6.x - [replication is NOT enabled]?

Last updated Apr 13, 2021

The purpose of this article is to provide assistance with configuring an external or CA Signed certificate for replication in DS. This allows you to use a certificate other than a self-signed one for increased security. This article assumes replication is not enabled.


Overview

The following process is only suitable for instances that are not yet replicating and assumes the instance only has the default DS created self-signed ads-truststore certificates. If this is not true, please see How do I replace the certificates (key pair) used for replication in DS 5.x or 6.x? for the correct process.

In summary, the steps are:

  • Backup the ads-truststore and ads-truststore.pin files.
  • Delete existing replication instance keys.
  • Delete existing ads-truststore certificates (or create a blank keystore).
  • Obtain signed CA certificate and create CA certificate chains.
  • Import the CA certificate chain.
  • Import the signed certificate.
  • Enable replication.

Configuring an external or CA Signed certificate for replication

This process refers to two masters (Master 1 and Master 2).

You can configure an external or CA Signed certificate for replication as follows:

  1. Make a backup copy of the ads-truststore and ads-truststore.pin files in case a rollback/recovery is needed. This step is highly recommended because this procedure requires deleting the existing self-signed ads-certificate in order to replace it with a CA-signed certificate of the same alias/nickname.
  2. Search for and delete the instance key in cn=admin data that matches the MD5 hash string of the ads-certificate held within the ads-truststore; this can be done on any instance: $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 2 entries Alias name: ads-certificate Creation date: Aug 9, 2016 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 207149be Valid from: Tue Aug 09 17:17:34 MDT 2016 until: Mon Aug 04 17:17:34 MDT 2036 Certificate fingerprints:     MD5: 0A:BC:37:0A:0A:1B:C8:B0:EB:C4:A2:91:E1:86:05:36 ... Alias name: 0abc370a0a1bc8b0ebc4a291e1860536 Creation date: Aug 9, 2016 Entry type: trustedCertEntry Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 207149be Valid from: Tue Aug 09 17:17:34 MDT 2016 until: Mon Aug 04 17:17:34 MDT 2036 Certificate fingerprints:      MD5: 0A:BC:37:0A:0A:1B:C8:B0:EB:C4:A2:91:E1:86:05:36 ...The above MD5 hash is 'MD5: 0A:BC:37:0A:0A:1B:C8:B0:EB:C4:A2:91:E1:86:05:36'; if you remove the colons (:) from the hash, you can determine the instance key (ds-cfg-key-id) this matches in the cn=admin data backend: dn: ds-cfg-key-id=0ABC370A0A1BC8B0EBC4A291E1860536,cn=instance keys,cn=admin data objectClass: top objectClass: ds-cfg-instance-key ds-cfg-public-key-certificate;binary:: MIIC/DCCAeSgAwIBAgIEIHFJvjANBgkqhkiG9w0BAQUFADBAMR8wHQYDVQQKExZPc<SNIP> ds-cfg-key-id: 0ABC370A0A1BC8B0EBC4A291E1860536 createTimestamp: 20160809231735Z creatorsName: cn=Internal Client,cn=Root DNs,cn=config entryUUID: c2106051-7b4b-4188-adcd-01cf08f3f268You can now delete this instance key using ldapdelete, for example: $ ./ldapdelete --port 1389 --bindDN "cn=Directory Manager" --bindPassword password "ds-cfg-key-id=0ABC370A0A1BC8B0EBC4A291E1860536,cn=instance keys,cn=admin data"
  3. Delete the existing ads-certificate PrivateKeyEntry and its corresponding trustedCertEntry (shown in the above keytool -list output) or create a blank ads-truststore on the instance you want to configure with the external or CA Signed certificate:
    • Option 1: Delete existing certificates: $ keytool -delete -alias ads-certificate -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin [Storing ads-truststore] $ keytool -delete -alias 0abc370a0a1bc8b0ebc4a291e1860536 -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin [Storing ads-truststore] $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 0 entries
    • Option 2: Create a blank ads-truststore$ rm ads-truststore $ keytool -genkey -alias foo -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -dname "cn=dummy cert" $ keytool -delete -alias foo -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin
  4. Obtain a signed certificate from the CA and create your CA certificate chain before continuing. See the following section for a simple example of the steps involved, although they may vary depending on the certificate and/or CA you are using.
  5. Import the CA certificate chain (cacert.pem in this example) on Master 1: $ keytool -import -alias ca-cert -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -file cacert.pem Owner: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Issuer: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Serial number: 92d5b8cc173128b4 Valid from: Wed Jul 15 10:48:11 MDT 2015 until: Sat Jul 14 10:48:11 MDT 2018 Certificate fingerprints:     MD5: DC:3E:00:6B:AE:D7:76:AC:D2:A1:84:E4:C3:02:AD:C1 ... Trust this certificate? [no]: yes Certificate was added to keystoreYou can re-check the certificate in the ads-truststore; it should now look similar to this, where the Owner and Issuer have the same value for the ads-certificate (the CA is self-signed in this example which is why the certificate chain length is 1, but there could be more certificates in a deeper CA hierarchy): $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 3 entries Alias name: af431bf5bb3a41fd83aff213feb1623a Creation date: Aug 12, 2016 Entry type: trustedCertEntry Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:     MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ... Alias name: ads-certificate Creation date: Aug 12, 2016 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:      MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ... Alias name: ca-cert Creation date: Aug 12, 2016 Entry type: trustedCertEntry Owner: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Issuer: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Serial number: 92d5b8cc173128b4 Valid from: Wed Jul 15 10:48:11 MDT 2015 until: Sat Jul 14 10:48:11 MDT 2018 Certificate fingerprints:      MD5: DC:3E:00:6B:AE:D7:76:AC:D2:A1:84:E4:C3:02:AD:C1 ...
  6. Import the signed certificate received from the CA (newcert.pem in this example) on Master 1: $ keytool -import -trustcacerts -alias ads-certificate -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -file newcert.pem Certificate reply was installed in keystoreYou can re-check the certificate in the ads-truststore; it should now look similar to this, where the Owner and Issuer have different values. The Issuer is now the Certificate Authority for the ads-certificate. $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 3 entries Alias name: ads-certificate Creation date: Aug 12, 2016 Entry type: PrivateKeyEntry Certificate chain length: 2 Certificate[1]: Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Serial number: 92d5b8cc173128b9 Valid from: Fri Aug 12 12:04:21 MDT 2016 until: Sat Aug 12 12:04:21 MDT 2017 Certificate fingerprints:     MD5: 1E:5C:27:F6:2F:E2:1A:77:E7:CB:4C:12:A7:AB:08:4A ... Alias name: af431bf5bb3a41fd83aff213feb1623a Creation date: Aug 12, 2016 Entry type: trustedCertEntry Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:      MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ... Alias name: ca-cert Creation date: Aug 12, 2016 Entry type: trustedCertEntry Owner: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Issuer: CN=ForgeRock CA, O=ForgeRock AS, ST=California, C=US Serial number: 92d5b8cc173128b4 Valid from: Wed Jul 15 10:48:11 MDT 2015 until: Sat Jul 14 10:48:11 MDT 2018 Certificate fingerprints:      MD5: DC:3E:00:6B:AE:D7:76:AC:D2:A1:84:E4:C3:02:AD:C1 ...
  7. Stop the DS server and restart to load the new certificates into the server. $ ./stop-ds --restart
  8. Repeat steps 1 and 7 to create new PrivateKeyEntry and trustedCertEntry truststore entries on Master 2 (CN = ds2.example.com).
  9. Enable replication on Master 1 using the dsreplication command, for example: $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 ds2.example.com --port2 5444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 9989 --trustAll --no-prompt
  10. Initialize Master 1 using the dsreplication initialize command, for example: $ ./dsreplication initialize --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostSource ds2.example.com --portSource 5444 --hostDestination ds1.example.com --portDestination 4444 --trustAll --no-promptYou can then check the replication status to ensure it is successful: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll Fri Aug 12 16:46:45 MDT 2016 Suffix DN : Server : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : Delay (ms) : Security (2) ------------------:----------------------:---------:---------------------:-------:-------:-------------:------------:-------------- dc=example,dc=com : ds1.example.com:4444 : 10002 : true : 15311 : 17455 : 8989 : 0 : false dc=example,dc=com : ds2.example.com:5444 : 10002 : true : 212 : 5611 : 9989 : 0 : falseThe Delay (ms) metric replaces the M.C.and A.O.M.C. metrics returned in pre-DS 6.5.

Example for obtaining a signed certificate from the CA

The high level steps involved in obtaining a certificate from the CA are as follows:  

  1. Generate a new keypair.
  2. Generate a Certificate Signing Request.
  3. Export and import the certificate to create a trusted certificate entry.
  4. Have the CA sign the certificate request.
  5. Create a CA certificate chain.
Caution

Obtaining certificates from a CA and creating certificate chains is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Here is a simple worked example of the above steps on Master 1 (you would need to repeat them on Master 2): 

  1. Create new PrivateKeyEntry and trustedCertEntry truststore entries on Master 1 (CN = ds1.example.com): $ keytool -genkeypair -alias ads-certificate -keyalg RSA -validity 7300 -keysize 2048 -storetype JKS -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -dname "CN=ds1.example.com, O=OpenDJ RSA Certificate"You can check the certificate in the ads-truststore; it should now look similar to this: $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry Alias name: ads-certificate Creation date: Aug 12, 2016 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:     MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ...
  2. Create a Certificate Signing Request (CSR) from the above certificate on Master 1: $ keytool -certreq -alias ads-certificate -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -file newreq.pem
  3. Export and import the certificate to create a trusted certificate entry on Master 1. The trusted certificate entry requires a certificate alias using a lowercase hash with no colons (:) so an intermediate keytool and sed are used: $ keytool -export -alias ads-certificate -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -file ads-cert.crt Certificate stored in file <ads-cert.crt> $ export md5hash=`keytool -printcert -file ads-cert.crt | grep MD5 | awk '{print $2}' | tr [:upper:] [:lower:] | sed "s/://g"` $ keytool -import -trustcacerts -alias $md5hash -keystore ads-truststore -storepass:file ads-truststore.pin -keypass:file ads-truststore.pin -file ads-cert.crt Certificate already exists in keystore under alias <ads-certificate> Do you still want to add it? [no]: yes Certificate was added to keystoreYou can re-check the certificate in the ads-truststore; it should now look similar to this: $ keytool -list -storetype jks -keystore ads-truststore -v -storepass:file ads-truststore.pin Keystore type: JKS Keystore provider: SUN Your keystore contains 2 entries Alias name: ads-certificate Creation date: Aug 12, 2016 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:     MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ... Alias name: af431bf5bb3a41fd83aff213feb1623a Creation date: Aug 12, 2016 Entry type: trustedCertEntry Owner: CN=ds1.example.com, O=OpenDJ RSA Certificate Issuer: CN=ds1.example.com, O=OpenDJ RSA Certificate Serial number: 24a0d8df Valid from: Fri Aug 12 12:01:27 MDT 2016 until: Thu Aug 07 12:01:27 MDT 2036 Certificate fingerprints:      MD5: AF:43:1B:F5:BB:3A:41:FD:83:AF:F2:13:FE:B1:62:3A ...
  4. Pass the CSR in the newreq.pem file to the CA for signing. They will return a signed certificate (newcert.pem in this example).
  5. Create a CA certificate chain (cacert.pem in this example) containing the signed certificate (newcert.pem) and any other necessary certificates.

See Also

FAQ: SSL certificate management in DS 5.x or 6.x

How do I use externally created SSL keys with DS 5.x or 6.x?

Administration Guide › Setting Up Server Certificates

Administration Guide › Changing Server Certificates

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs

OPENDJ-5235 (Allow external certificates to be used for replication during setup)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.