Tuesday, June 26, 2012

LibOVD: when and how

LibOVD, introduced in FMW, is a java library providing virtualization capabilities over LDAP authentication providers in Oracle Fusion Middleware. It is delivered as part of OPSS (Oracle Platform Security Services), who is available as part of the portability layer (also known as JRF – Java Required Files). In other words, if you are a JDeveloper, WebCenter, SOA or IAM customer, you already have libOVD.

LibOVD provides limited virtualization capabilities when compared to its big brother OVD (Oracle Virtual Directory), who is a full-blown server implementing the LDAP protocol with far more advanced virtualization features, including OOTB support for LDAP and database backend servers, advanced configuration for adapters, out-of-box plug-ins as well as a plug-in programming model allowing for almost limitless possibilities in transforming data and connecting to external data sources.

1. When

LibOVD is primarily designed to work as an embedded component for FMW components who need to look up users and groups across distinct identity providers. If you had a chance to look at this post, you already know the User/Role API can take into account only one authentication provider.

Take SOA’s Human Workflow component, for instance. Customers frequently have an external identity store, like OID or Active Directory, holding the application end users and related enterprise groups. But they also often want to keep Weblogic’s embedded LDAP server for administration accounts, like weblogic user.  Or they simply have an LDAP server in the US and another one in Brazil and want to bring all those users together. Using User/Role API alone is not enough.

That does not mean libOVD can be used only by FMW components. It is ok that your custom applications employ libOVD and that’s a given once you enable libOVD for a given domain. However, do not expect any of those features only available in OVD. A common mistake is expecting libOVD to work with a database authenticator. LibOVD is only for LDAP authenticators.

Another use case for libOVD is known as split profile, where information about the same identity exists in more than one LDAP-based identity store and your applications need a consolidated view. More information here: http://docs.oracle.com/cd/E21764_01/core.1111/e10043/apidvirtual.htm#CIHDGFIC

2. How

LibOVD is activated when you set the property virtualize=true for the identity store provider in jps-config.xml:

<serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
 <property name="idstore.config.provider" value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider"/>
 <property name="CONNECTION_POOL_CLASS" value="oracle.security.idm.providers.stdldap.JNDIPool"/>
 <property name="virtualize" value="true"/>
 <property name="OPTIMIZE_SEARCH" value="true"/>

It is possible to hand-edit jps-config.xml, but I recommend that you use Enterprise Manager to set it up, because the minimum mistake in jps-config.xml can get the WLS domain into a non-startable state.

Note: Unless your application makes explicit usage of a different JPS Context, this is domain-wide set up, impacting all applications deployed in that domain, both from authentication and user/group lookup perspectives.

Enabling libOVD using Enterprise Manager:

Navigate to the domain Security Provider Configuration screen and click the Configure button, as shown:


Then use the Add button to add the property.


When you enable the virtualize flag, a new folder structure along with some files are created under $DOMAIN_HOME/config/fmwconfig folder.


Notice the default folder name: it refers to the default JPS context in jps-config.xml, which in turn refers to the idstore service instance for which libOVD has been configured.

These are familiar files to readers used to OVD. adapters.os_xml, for instance, lists the configured adapters for libOVD. An adapter is created for each authenticator listed in Weblogic’s config.xml.

3. Be Aware

Within a single adapter, in order to search across both users and groups search bases, libOVD sets the adapter’s root to be the common base between them. For example, let’s say users and groups search bases are defined as cn=users,dc=us,dc=oracle,dc=com and cn=groups,dc=us,dc=oracle,dc=com, respectively. In this case, the adapter’s root is set to dc=us,dc=oracle,dc=com.

Such configuration may cause a performance overhead if customers happen to have more users and groups distributed across other nodes that are also children of the common root but who are not necessarily required by the applications running on Weblogic. Wasted LDAP queries.

Notice the undocumented property OPTIMIZE_SEARCH in the jps-config.xml snippet presented before. It is the solution to the problem just described because it forces libOVD to search only within the users and groups search bases defined in the authenticator providers. No searches are performed elsewhere.

In order to take advantage of OPTIMIZE_SEARCH, make sure to get the appropriate patch for the corresponding release of FMW:
  • FMW 14693648
  • FMW 14919780
  • FMW 14698340

4. Managing libOVD

libOVD can be managed via wlst.sh. When connected, type

> help(‘OracleLibOVDConfig’)

and check the available commands.

5. Debugging libOVD

To debug libOVD, create a logger for oracle.ods.virtualization package in your server’s logging.xml file. Here’s a snippet.

<logger name='oracle.ods.virtualization' level='TRACE:32'>
 <handler name='odl-handler'/>


  1. Pretty nice. This is an interesting feature, looks like a mini OVD functionality without OVD...

    One Question though, I see most of the config files are created (adapters.os_xml etc) that we use for OVD. However I assume, i can only create a join adapter between two LDAP Adapters. can I do more than two LDAP adapters that I can join?

    Thank you.


    1. Yes Vijay, documentation states it is possible having more than one secondary adapter in a join view. Please check the link on the "When" section above.
      I have not tried it though.

  2. Hi Andre,
    Very Informative post. Could you help me with following:
    I created authenticator provider for IPLANET using weblogic admin console (with SUFFICIENT flag).
    How can we refer it in jps-config.xml? My idea is to use both default authenticator and my iPlanet authenticator as identity store. After reading docs, I figure it is possible using virtualize=true. I tried examples from docs but no luck

    Thank you

  3. Ketan,

    it's not clear to me what exactly you're trying to accomplish. By setting vistualize=true, you are defining both Default Authenticator and iPlanet Authenticator as your identity stores. Any searches for users and groups performed by FMW components are going to leverage both.

    If you want to write your own code and leverage id store virtualization, take a look at my post about User/Role API (Couple of things you need to know about the User Role API) published quite some time ago on this blog.



    1. Thanks for the reply.
      Yes, I have now got it working using "exactly" what you've said. Setting only virtualize=true will do it.
      Guess I misunderstood the configurations and went on creating another ServiceInstance as idstore.virtualize.
      Many thanks.

  4. Thanks for a nice post. I have a question that would fall under the "When" section.
    Let's say you have one OID with users under a couple of different ou:s, and you would like to use the OID as Data Store for OAM.

    As far as I know, OAM only supports authenticating users in one single ou. (for example cn=Users,dc=mycompany,dc=com)

    Would it be possible to let libOVD present these different ou:s as one to OAM, or should it be solved in another way?


    1. Hey Henrik,

      libOVD is designed to help with searching across multiple authentication providers in Weblogic. It is an embedded component primarily leveraged by some FMW components who are "Weblogic authentication providers-aware".
      When you define an OAM identity store, you're not making use of the authentication providers defined in Weblogic. Therefore, libOVD is not applicable.
      One way to do what you want is simply defining the OAM user search base to be a common (top) entry across the scattered ou:s.
      Depending on the DIT structure, that can bring some performance issues, because OAM would end up searching through much more than what is actually needed.
      The other way is using OVD.

      Hope this helps,


    2. Thanks Andre! That helped me understand thinks better.
      // Henrik


Note: Only a member of this blog may post a comment.