OAM 11g Connecting to an LDAP ID store over SSL (LDAPS)

Connecting to an LDAP ID store in OAM 11g over SSL (LDAPS) is a common scenario that many customers may need to implement. Unfortunately the documentation on this subject is scant and can be misleading. So as part of the OAM 11g Academy series, I'd like to discuss this commom scenario. To view the first post on the OAM 11g policy model, as well as the index to the entire OAM 11g Academy series, click here: http://fusionsecurity.blogspot.com/2011/02/oracle-access-manager-11g-academy.html.

The documentation to manage data sources can be found in Chapter 3. The section titled "Managing User Identity Store and OAM Administration Registration" describes how to register a new identity store. Specifically, Table 3-2 describes all the possible elements required to register. Looking at the 'LDAP URL' element we have the following:

The URL for the LDAP host, including the port number.

For example, the default embedded LDAP host might be:
ldap://localhost:7001

You can also specify ldaps://, which supports SSL_NO_AUTH.

That's it! Good luck :)

So what does it all mean and what do I do if the LDAPS connection fails?

SSL_NO_AUTH basically means a self signed certificate, no authentication required. 1-way and 2-way SSL modes are not supported at this time.

Once you setup the identity store using LDAPS you should always test the connection via the 'Test Conenction' button located at the top as shown here:

If there are any issues with the connection you will see an error like the one below:

You may also find an exception in the oam-diagnostic logs as follows:

####<Oct 29, 2010 1:50:52 PM CDT>

<Error> <oracle.oam.user.identity.provider> <host> <AdminServer> <[ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)'> <user> <> <279b690d689ef829:-7e1652d1:12bcfcdf8f4:-8000-0000000000000c13> <1288378252365> <OAMSSA-20043> <Error validating LDAP URL and credentials : javax.naming.CommunicationException: <host>:636 [Root exception is javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target].>

This specific exception states that it cannot find the certificate in order to initiate the SSL handshake.

You may also find an error in the LDAP logs. These logs are from eDirectory for example:

12:47:42 41D15940 LDAP: New TLS connection 0xedd09c0 from IP:40557, monitor = 0x4b780940, index = 32
12:47:42 4B780940 LDAP: Monitor 0x4b780940 initiating TLS handshake on connection 0xedd09c0
12:47:42 4AF78940 LDAP: (IP:40557)(0x0000:0x00) DoTLSHandshake on connection 0xedd09c0
12:47:42 4AF78940 LDAP: (IP:40557)(0x0000:0x00) TLS accept failure 1 on connection 0xedd09c0, setting err = -5875. Error stack:
error:140760FC:SSL routines:SSL23_GET_CLIENT_HELLO:unknown protocol
12:47:42 4AF78940 LDAP: (IP:40557)(0x0000:0x00) TLS handshake failed on connection 0xedd09c0, err = -5875
12:47:42 4AF78940 LDAP: Server closing connection 0xedd09c0, socket error = -5875
12:47:42 4AF78940 LDAP: Connection 0xedd09c0 closed

Fortunately the solution is pretty simple and has two parts. First, OAM now uses the Java Key Store (JKS) format to store the certificates keys. OAM uses the JKS file 'cacerts' located at "$JAVA_HOME/lib/security/cacerts". This is where the certificate needs to be imported into. Secondly, make sure that the right certificate is imported via the keytool. For more information on how to use the keytool, you can go here. You will need to import the server certificate along with the CA Root cerficate into the keystore. Many customers make the mistake of importing only the CA Root certificate.

So to summarize, the two issues to be aware of are:

1) The difference from 10g, is that 11g now uses the default 'cacerts' location based on the $JAVA_HOME directory.

2) Make sure that both the CA Root certificarte and the server certificate (child) are imported into the keystore.