Setting up LDAP in the Terracotta Management Console (TMC)

Knowledge base
1

In this article, you will discover every step and commonissues with configuring a Terracotta Management Console to use LDAP(S) as its authentication / authorization source (default is a simple ini file)

This article does not replace the official Terracotta Documentation; it just tries to complement it

Connect the TMC to an LDAP directory
#

In this example, I will assume the LDAP directory is anonymously browsable

If you already set up an authentication mechanism for the TMC, head to the security tab (as an admin user)

And then, choose LDAP or Active Directory as your authorization method :

image.png698×407 31 KB

Now you can fill in the required details, for example :

image.png677×981 90.2 KB

This configuration would match an LDAP setup like this one : (screenshot from Apache Directory Studio, that I highly recommend if you test LDAP)

image.png806×402 43.5 KB

And then, you would just need to restart the TMC to start logging your TMC users against such an LDAP directory.

Connect the TMC to an LDAPS (SSL / TLS) directory
#

If your LDAPS directory is using a certificate signed by a known authority, well, everything should work fine, as described in the previous chapter.

Now, if your LDAPS directory is using a self signed certificate, read on.

Create a keystore, with a myAgent alias
#

This keystore could be used by your LDAP directory, for SSL.

$ keytool -keystore keystore-file.jks -genkey -alias myAgent
Enter keystore password:
Keystore password is too short - must be at least 6 characters
Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:
What is the name of your organizational unit?
  [Unknown]:
What is the name of your organization?
  [Unknown]:
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes

Enter key password for <myAgent>

(RETURN if same as keystore password):

If you're using Apache Directory Studio for example, you can tell it to use this keystore to serve LDAPS :

image.png932×561 54 KB

Export the keystore myAgent alias to a certificate
# 

$ keytool -export -alias myAgent -keystore keystore-file.jks -file myAgentCert.cert
Enter keystore password:
Certificate stored in file <myAgentCert.cert>

Import the keystore myAgent alias to a truststore (if it does not exist, it will be created) #

This is the most important part : the then created trustore will recognize the LDAPS  certificate as legitimate :

$ keytool -import -trustcacerts -alias myAgent -file myAgentCert.cert -keystore {{{~/.tc/mgmt/tms-truststore
Enter keystore password:Re-enter new password:Owner: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=UnknownIssuer: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=UnknownSerial number: 15153d9bValid from: Thu Feb 25 11:43:18 EST 2016 until: Wed May 25 12:43:18 EDT 2016Certificate fingerprints: MD5: 32:FC:19:1C:BA:95:9B:B8:5F:AB:68:92:49:10:35:01 SHA1: 22:75:FB:D8:B8:DD:91:00:42:41:E3:40:99:15:41:F1:F1:70:84:BE SHA256: 15:77:AD:BD:16:86:04:22:1A:BC:2F:99:69:41:A8:7D:3E:B7:90:20:FD:5F:88:B7:7A:BE:5F:D0:D0:CC:FA:DA Signature algorithm name: SHA1withDSA Version: 3Extensions:#1: ObjectId: 2.5.29.14 Criticality=falseSubjectKeyIdentifier No InterWiki reference defined in properties for Wiki called "KeyIdentifier [0000"!Trust this certificate? no: yesCertificate was added to keystore 
}}}

Add the truststore password to a new (obfuscated) keychain #

For the TMS to use this new truststore, you need to add the truststore password to a keychain, that will be loaded by the TMS : 

bigmemory-max-4.1.5/tools/security$
bin/keychain.sh -c -O ~/.tc/mgmt/keychain file:/Users/anthony/.tc/mgmt/tms-truststore
Terracotta Command Line Tools - Keychain ClientJava HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=128m; support was removed in 8.0KeyChain file successfully created in /Users/anthony/.tc/mgmt/keychainEnter the password you wish to associate with this URL:Confirm the password to associate with this URL:Password for file:/Users/adah/.tc/mgmt/tms-truststore successfully stored

From now on, you should be able to configure the TMS with the LDAPS directory

image.png681×982 90.5 KB

Configure the TMC with a password protected LDAPS directory #

In that use case, I'll assume that the LDAPS directory is not anonymously browsable : you need to set up a system username.

The keychain should know about this system user password, so let's first add this new entry to the keychain : 

bigmemory-max-4.1.5/tools/security$ bin/keychain.sh -O ~/.tc/mgmt/keychain ldaps://ludovic@localhost:10636
Terracotta Command Line Tools - Keychain Client

Java HotSpot™ 64-Bit Server VM warning: ignoring option MaxPermSize=128m; support was removed in 8.0


Enter the password you wish to associate with this URL:


Confirm the password to associate with this URL:


Password for ldaps://ludovic@localhost:10636 successfully stored

Restart your TMS and setup the LDAP configuration with the system user :

image.png679×984 92 KB

Troubleshooting
#


Your TMS truststore was found, but did not contain the certificate exposed by the LDAPS directory : either add the LDAPS certificate to the trusstore, or use -Dtc.ssl.trustAllCerts=true (not recommended though, it's defeating the SSL trust)

In this case, the keychain does not contain an entry with the system username and password; you need to add it.

[ERROR]     [com.terracotta.management.security.impl.CustomTrustStoreSSLSocketFactory]{}
Impossible to initialize the SSLSocketFactory
java.lang.IllegalArgumentException: Error reading truststore at location : /Users/anthony/.tc/mgmt/tms-truststore

Make sure the tms-trusstore exists at the specified location AND the keychain contains an entry to it (with the right password)