Nestled snugly inside each and every instance of WebLogic Server is an embedded LDAP server, humming away and providing storage for the security realm. Even though it’s so central to WLS, the embedded LDAP very rarely makes its presence known. This article will describe what the embedded LDAP does and how you can leverage it.
Beginnings. Every story has one. This one starts out with a company (recently acquired by Oracle) named Octet String. BEA integrated Octet String’s embeddable Virtual Directory Engine (VDE) as part of WebLogic 7. This is why you sometimes see “octetstring” in the package names given in stack traces and files named vde*.* in the WebLogic directories. It doesn’t seem that the embedded VDE was used to its full potential given this Octet String blurb about it:
Real-time Access to Multiple Data Stores Powered by VDE
Regardless, I don’t know whether Octet String or BEA maintains the code base in WLS now, but Octet String was bought by Oracle in November 2005. Oops!
A Daily Dose o’ LDAP
A default WLS domain uses embedded LDAP to manage users, groups, roles, and security policies. In fact, most of the security providers prefixed with the word “Default” use the embedded LDAP as their database. So, unless you’ve set up other providers, working with user and group data in the WLS console is all backed by the embedded LDAP. Additionally, the security policies you define in your deployment descriptors and via the console are stored there, too.
Managing Embedded LDAP
For all practical purposes, the embedded LDAP is just another LDAP server. As a result, you can do the following things:
- Make backups
- Configure replication
- Configure caching
- Export/import data
- Set access control
- Browse the directory with an external LDAP viewer
All of these details are covered in BEA’s Managing the Embedded LDAP Server document so I won’t go into these items here. What I will talk about next is a few tips and tricks that I’ve learned over time.
Keep an Eye on Your Cache
By default, embedded LDAP caches data for 60 seconds. I’ve been burned by this cache more times than I’d care to admit. I guess I’m a slow learner.
What can happen is you make a change to the data, try your application expecting it to use that data, and then wonder why it didn’t. That’s the bite of the cache. You could temporarily disable caching or lower your cache TTL while you’re manipulating the data to minimize this problem.
Occasionally you might have difficulty starting the server due to an error message like this:
…myserver\ldap\ldapfiles\EmbeddedLDAP.lok (The process cannot access the file because it is being used by another process)
The EmbeddedLDAP.lok file ensures that only one WebLogic server can access an embedded LDAP instance. Double-check to make sure that the WLS instance is not already running. One easy way to do this is to try to pull up the WLS console in a browser. If it comes up, the server is running, of course. If it’s not, try deleting the EmbeddedLDAP.lok file.
By default, modifying the embedded LDAP’s schema is not possible. That makes sense since you don’t want to inadvertently break something in the security realm. However, with a minor configuration change you can make limited adjustments to the schema.
Edit the <domain_dir>\myserver\ldap\conf\vde.prop file and change vde.schemacheck to 0. Upon restarting the WebLogic server, you can now make some changes to the schema but to nowhere near the degree to which you can modify external LDAP directories.
In general, though, you probably don’t want to make any schema changes to embedded LDAP but it’s good to know that you can.
Embedded LDAP has log files for debug output and access events. The location and name of these files is set in the <domain_dir>/myserver/ldap/conf/vde.props file. Among other settings, in that file you will find
where vde.logfile points to the debug log and vde.accesslogfile points to the access log. You can change these entries if you’d like, but you’ll find the default log files in the <domain_dir>/myserver/ldap/log directory.
Now, if you check your domain for these files, you’ll find that they are there but that perhaps there’s nothing in them. The reason is that they are only written to under certain conditions.
The access log file is only written to when the access is from an external client. A WebLogic server calling its own embedded LDAP does not count. If you use an LDAP browser to view the contents of the embedded LDAP, for example, all accesses from the browser will be logged in the access log as you’d expect.
The debug log file is only written to when certain debug flags are set. To enable debug output, add the following stanza to the server element in config.xml:
The DebugEmbeddedLDAP element toggles LDAP debugging. When toggled on, the output goes to the log file defined in vde.props. The DebugEmbeddedLDAPLogToConsole optionally sends the same output to WebLogic’s standard out. Finally, DebugEmbeddedLDAPLogLevel sets the level of the events to log. The possible level values are:
- 0 = errors only
- 5 = normal
- 7 = verbose
- 9 = very verbose
You’ll need to change the Name attribute if your WebLogic server name is not “myserver.” After adding the debug flags to config.xml you’ll have to restart WebLogic for the changes to take effect.
How useful are these log files?
The access log can be very useful when you have external clients accessing embedded LDAP. The logging is just like what you’d find in an iPlanet LDAP server access log. On the other hand, the debug log file is not very useful at all. But for those exceedingly rare times when you need log output from embedded LDAP, it’s nice to know that you can get it.
Tales from the Crypt
I know you’re dying to know which encryption algorithm is used to secure the passwords in embedded LDAP. Maybe not, but I’ll tell you anyway. It’s SHA-1 with a 32 bit salt and 1,000 iterations. Don’t you feel better just knowing that? 😉
Some people don’t realize the power of the plug-and-play nature of the WebLogic security framework. Here’s a simple test you can do that demonstrates getting user information from an external data source. The only thing you need for this test is a WebLogic installation.
You need two WLS domains. One domain is your baseline domain. The second domain will simulate an external LDAP server that the first domain will use for access control. Build the domains and make sure that they have unique ports. I recommend setting the “LDAP” domain port to 389 (if you can) to drive home the point that this domain is simulating an LDAP server.
NOTE: The latest Firefox (22.214.171.124) won’t let you navigate to a web app on port 389. Upon trying to do so, it says: “This address uses a network port which is normally used for purposes other than Web browsing. Firefox has canceled the request for your protection.” Yes, 389 is the standard LDAP port but this is annoying. If you are using FireFox, use a port other than 389.
After starting your domains, add a user to the LDAP domain and then add this user to the Administrators group. Change the embedded LDAP password as specified in the Managing the Embedded LDAP Server document. You’ll need this password in a moment.
In the baseline domain, we want to configure the security framework to use the external LDAP server. To do this, we’ll add a new authentication provider that points to the LDAP domain.
In the WLS Console for the baseline domain, navigate to and click the authentication node in the Security section. On the right hand side, click on the Configure a new iPlanet Authenticator link. Set the Control Flag to Sufficient and click Create.
On the iPlanet LDAP tab, set the Principal to “cn=Admin” (without the quotes) and the two Credential fields to the password you specified for the embedded LDAP credential in the LDAP domain. Click Apply.
This paragraph assumes that your LDAP domain is named “LDAP.” If it’s not, substitute your LDAP domain name for “LDAP.” On the Users tab, set the User Base DN to ou=people,ou=myrealm,dc=LDAP and click Apply. Then, on the Groups tab, set the Group Base DN to ou=groups,ou=myrealm,dc=LDAP and click Apply.
Finally, click on the DefaultAuthenticator node, set the Control Flag field to Sufficient, and click Apply. If it’s left at Required, you won’t be able to authenticate with the user defined in the LDAP domain since the user is required to be in the baseline’s embedded LDAP. Can’t have that…
Changes to the security realm configuration require a server restart so do that now. Restart the LDAP domain, too. When both servers start, access the baseline domain’s Console application, but log in using the username and password of the user you created in the LDAP domain. If everything is configured correctly, you should gain access.
(Interestingly, you can have a look at the users in the baseline domain via the Console. You’ll see a list of all the users in the security realm broken out by data source. That way, you know which users are in your embedded LDAP and which ones are in the external LDAP. You can do the same thing for groups.)
What we’ve done with this little experiment is to demonstrate how easy it is to externalize your user and group data with the WebLogic security framework. The embedded LDAP server in the LDAP domain served as an external data store for the baseline domain’s security realm. I find that humorous for some reason.
An even simpler (yet very freaky!) experiment would be to just use the baseline domain. Set the LDAP credential and iPlanet authenticator as mentioned above but for the baseline domain. When you set the iPlanet authenticator, point it to the baseline server. The iPlanet authenticator is thus pointing to the server in which it’s running. Finally, remove the DefaultAuthenticator and DefaultAuthorizer and then restart the server.
I haven’t actually tried this one but it’s an interesting thought experiment, at least.
While I haven’t seen any official stance on this from BEA, I’ve heard more than once that the embedded LDAP shouldn’t be used for production. Instead, use an external LDAP or other data store for your users and groups.
I hope you found this brief tour of embedded LDAP useful. I’ve shown some ways in which you can leverage embedded LDAP and described a quick experiment for configuring the WebLogic security framework to use an external LDAP server.