Understanding mTLS LDAP connections in ForgeRock stack
PingAM (Formerly Access Management) and PingIDM (Formerly Identity Management) introduced support for mTLS connections to PingDS (Formerly Directory Services) in version 7.4.
https://backstage.forgerock.com/docs/am/latest/release-notes/whats-new.html#support-mtls
https://backstage.forgerock.com/docs/idm/7.4/release-notes/whats-new.html#mtls-auth-to-ds
Mutual TLS connections are beneficial as a client certificate is used during the connection, and the certificate details can be used to securely identify and authenticate the bind account used in system-to-system communications. This means that PingDS connections from PingAM and PingIDM no longer need a userid and password to connect to PingDS.
The documentation provides example steps on configuring the connections, but there are other options as well if you understand how the connections work.
The PingIDM documentation example creates a self-signed certificate with a known certificate subject and the PingAM example uses dskeymgr to create a keypair using the DS deployment key as the issuer (which is automatically trusted) and the actual LDAP dn of the bind account as the certificate subject. The certificate/keypair you use is irrelevant as long as it is trusted by PingDS (either through chain or explicitly). For production environments, customers will often use CA issued certificates.
PingDS Certificate Trust
PingDS has several different options for trusting the certificates or chains that can be configured using dsconfig. Trust Manager Provider :: PingDS
The File Based Trust Manager can be used for java trustores (jks or pkcs12 format).
In some cases, PEM Trust Manager may be more convenient (ie in kubernetes deployments where dynamic issuers like cert-manager can be mounted as files).
PingDS Certificate Mapping
PingDS also has several options for mapping the certificate to the bind account that can be configured using dsconfig: Certificate Mapper :: PingDS. You can choose to configure one or many depending on your needs.
Fingerprint Certificate Mapper requires an admin to identify a user attribute that will hold the fingerprint hash value of a specific certificate. In this scenario, there is no need for the certificate subject DN to match the user. The schema includes the ds-certificate-fingerprint attribute which can be used or you can configure a different attribute. This option is probably not practical for production as admins would need to update the bind account in LDAP any time the certificate is regenerated.
Subject DN To User Attribute Certificate Mapper allows you to specify a certificate subject value on a user ldap attribute that must match. In this scenario, the certificate subject would be added to the ds-certificate-subject-dn attribute of the bind account. This value can be anything as long as it matches.
Subject Equals DN Certificate Mapper will map if the subject of the certificate matches the LDAP DN of the bind account. This option requires the least amount of configuration to each user (only the requirement of adding the ds-certificate-user objectclass on each user that needs to bind using mTLS), but requires the certificate subject to EXACTLY match the user’s DN. This may be problematic depending on the suffix used by your directory as some tools like cert-manager don’t support all the naming elements in a X509Subject (unless enabling experimental features and using literalSubject).
All of the above can also have an issuer-dn added so in the case you trust multiple CAs/issuers, you can limit each mapping to working with only one.
Testing the bind
The cli tools bundled with PingDS have the ability to use mTLS. This is nice because you can test your PingDS trusts, mapping configuration and bind accounts prior to configuring the connections in PingAM or PingIDM.
The connection utilizes External SASL mechanism to perform authentication of the account after the mutual TLS connection is established.
This ldapsearch command will perform a bind to the directory and perform the search as the user in order to test the above configuration:
bin/ldapsearch \
--hostname localhost \
--port 1636 \
--useSsl \
--useJavaKeyStore cts-mtls.jks \
--keyStorePassword xxx \
--baseDn ou=tokens \
--certNickname certificate \
--saslOption mech=EXTERNAL \
--trustAll \
"(objectClass=*)"
The above example uses a JKS java keystore to source the private key for the client, but you can also use different keystore types by changing the arguments:
--useJavaKeyStore {keyStorePath}
JKS keystore containing the certificate which should be used for SSL client authentication
--useJceKeyStore {keyStorePath}
JCEKS keystore containing the certificate which should be used for SSL client authentication
--usePkcs11KeyStore
PKCS#11 keystore containing the certificate which should be used for SSL client authentication
--usePkcs12KeyStore {keyStorePath}
PKCS#12 keystore containing the certificate which should be used for SSL client authentication
-Rob Jackson
Ping Professional Services