Tuesday, September 25, 2007

WebLogic Security: Configuring the Database Authentication Providers (SQL, Custom, DBMS)

I have gotten a lot of WebLogic security related questions offline as a result of my last blog post. A couple of people have asked for more details behind the WebLogic SQL Authenticator (a database authentication provider) that I mentioned. This blog entry will give deep background into your options when it comes to authenticating users from a database repository. I will finish by explaining how to configure the SQL Authenticator.

NOTE: this blog entry was originally posted September 25th, 2007 on my previous blogging system (dev2dev.bea.com).

First, a bit of terminology. When looking in the WebLogic Server documentation for a database authentication provider you will find at least a few names:

We all love choice, but what's up with all these names? Are they all the same thing, or does WLS provide multiple provider implementations?

In short, WebLogic does provide multiple database authentication provider implementations. This blog entry will sort out specifically what providers are available to you when authenticating from a database. We will look inside the WebLogic providers to understand what features are supported by which provider. After we have that covered, I will describe how to configure a SQL Authenticator provider in the WLS Console and how to provision the database.

Peter's Best Practice: Use a Database Backed Authentication Provider!

Before we dive into the details, I want to take a moment to congratulate you on reading more about this topic. I have worked at BEA many years, and I have been involved in many customer production escalations. When it comes to Authentication repositories, my experience tells me that you are safest performance-wise with a database backed authentication store. While customers have certainly been successful with other types of authentication repositories, if you want to minimize risk the database approach trumps all others. A database backed repository has few moving parts, and the query necessary to authenticate a user is a simple SELECT. So if you want my opinion, I say go with a database when you have the option.

The Official Flavors of WebLogic Database Authentication Providers

Back to the topic at hand - what are the WebLogic database authentication providers? The official documentation source, edocs.bea.com, will get us started. The docs explain what is provided for you:

Weblogic Security Providers

A set of Database Management System (DBMS) authentication providers that access user, password, group, and group membership information stored in databases for authentication purposes. Optionally, WebLogic Server can be used to manage the user, password, group, and group membership information. The DBMS Authentication providers are the upgrade path from the RDBMS security realm. The following DBMS Authentication providers are available:

  • SQL Authentication provider - A manageable authentication provider that supports the listing and editing of user, password, group, and group membership information.
  • Read-only SQL Authentication provider - An authentication provider that supports authentication of users in a database and the listing of the contents of the database through the WebLogic Server Administration Console. The authentication provider requires a specific set of SQL statements so it might not meet all customer needs.
  • Custom DBMS Authentication provider - A run-time authentication provider that only supports authentication. This provider require customer-written code that handles querying the database to obtain authentication information.This authentication provider is a flexible alternative that allows customer to adapt a DBMS Authentication provider to meet their special database needs.

The documentation is reflected by the WebLogic Console, which provides the following dropdown of authentication providers to choose from. Notice that the three database authentication provider types appear.


While the above descriptions provide some information about the difference between these providers, we can do better. Because you are a developer, you probably want the inside story. Today is your lucky day!

Inside the WebLogic Database Authentication Providers

To get the inside story let's head straight for the source - the authentication provider configuration files. You will find them here:

  • BEA_HOME/WL_HOME/server/lib/mbeantypes/cssWlSecurityProviders.jar

If you open up this JAR, you will find 4 files of interest: DBMSAuthenticator.xml, CustomDBMSAuthenticator.xml, ReadOnlySQLAuthenticator.xml, and SQLAuthenticator.xml. Three of those map directly to the official authentication provider implementations, so those are obviously their configuration files. The fourth, DBMSAuthenticator - what is that? If you look into the XML files, you find that DBMSAuthenticator is the base class for the rest of the providers. By looking at the Extends attribute on the MBeanType element, you can derive the class hieararchy of the providers, shown below.


Now that you understand how the providers are related, how do you know which one you want? WLS/CSS authentication providers have two components - the JAAS code that actually performs the authentication at runtime, and then a set of management "mbeans" that the provider chooses to implement. Every management feature that a provider can support is surfaced as an mbean interface. The key to understanding what a provider can do for you is to look at the mbean interfaces that it implements. Each interface is optional, meaning a provider may choose what features it can support.

Here is the list of mbeans for authentication providers which provide the manageability around users and groups:

SSPI MBean Quick Reference

Mapping out our providers into a table and the mbeans they implement shows the vast difference in manageability. You will want to select a provider based on your requirements for managing users and groups from WLS.


Using the CustomDBMSAuthenticator

This provider is obviously not for use in situations when manageability from WLS is important. It offers no management support. What it does offer is a lowest common denominator approach to integrating a database user repository. Employ this provider when you need to surface just authentication capabilities to WLS, and nothing else. You simply need to implement a plugin that answers the most basic of questions.

Configuring the SQL Authenticator

You are more likely to be using the Read-only SQL Authentication provider or the most powerful SQL Authentication provider. These providers give you manageability from the WLS Console (and WLP Console if using WLP). They are easy to instantiate - the UI surfaces the options you need to configure. I won't go into all the options, but it is important to see that you can change the SQL for each operation if you have a custom schema. The SQL for these providers is designed to be modified to allow you to retrofit a custom database schema. But you can also use the default schema if you are provisioning a brand new user repository (see below for the schema).


After configuring the provider, any deltas versus the defaults will be persisted into config.xml. You can see below, I updated the Datasource of course (this is required) but I also made an arbitrary change to the Create Group SQL. See how it wrote the update into config.xml.

<sec:authentication-provider xsi:type="wls:sql-authenticatorType">
INSERT INTO GROUPS VALUES ( 'arbitrary change' , ? )

The Default Schema DDL for the SQL Authenticator

You can define whatever schema you want to store users and groups when using the SQL Authenticators. But if you are starting fresh, why not just use the default schema and the default settings on the provider. I would highly recommend this approach.

It doesn't look like we officially document the default database schema so let me show you what it is. I list the Oracle DDL below, but you can find the official DDL for your database vendor in the following location in the WLS 10 install (and a similar location for other versions):

  • BEA_HOME/wlserver_10.0/common/p13n/db/DB_VENDOR/p13n9_create_tables.sql


A Few Details for WebLogic Portal Customers

This thread got started because I was discussing in my last blog how WLP 9.2+ by default uses the WebLogic SQL Authenticator. You can, of course, add more authentication providers and remove the SQL Authenticator if you like. When installing WLP, the installer (or you can use the createdb script) will lay down the default SQL Authenticator schema into the WLP schema. Therefore, by default, WLP uses just a single schema for both authentication and Portal operations. This is the most convenient option, but you can change this by switching out the configured datasource.

More Information

For further reading, I suggest these links:

Add to Technorati Favorites

Comments from the original blog:

  • Great article! I was able to successfully help my client configure one for their needs. Thanks again.

    Posted by: sghattu on November 11, 2007 at 6:57 PM

  • I just got a question offline that I will record here - the developer was having trouble creating an Ant build script for building a custom Atn provider.

    My answer:

    When building providers, I have always used the Sample SSPI download from dev2dev CodeShare. It contains a working build script so all of this is taken care of for you.

    SSPI Code Sample

    Posted by: plaird on October 19, 2007 at 10:21 AM

  • Hi Peter, Interesting post but I would like to get more details on your SQLAuthenticator console configuration screenshot. Could you provide me more details on the DataSource name you use. I'm running into troubles with that part! I've tried to provide a configured JDBC data source name but this does not work as the DS is not yet initialized when the security is initialized (not able to start the console anymore). I've tried to provide a Data Source Factory name also without any success!! (Can start the console, but error in the log saying: Connection Pool not usable) Any idea? I'm using Oracle 10g thin jdbc driver and WebLogic server 9.2 Thanks in advance Daniel

    Posted by: ni2corp on September 25, 2007 at 11:43 PM

Saturday, September 22, 2007

Discussion on WebLogic Security: Authentication Providers, Internal LDAP, JAAS, WebLogic Portal, Profile

This blog entry comes from an email thread I had with a fellow BEA colleague. We traded a number of emails - he asked a lot of great questions about how WebLogic Portal (WLP) supports various security features. Since WLP relies heavily on WebLogic Server for those features, my answers apply to WebLogic in general and not just Portal. I am posting the email thread here because I think that this discussion might be of interest to others.

NOTE: this blog entry was originally posted September 22nd, 2007 on my previous blogging system (dev2dev.bea.com).

Before I show the thread, I should provide a glossary of abbreviations and concepts:

  • WLS: WebLogic Server, the J2EE application server that most people associate with the name "WebLogic"
  • WLP: WebLogic Portal, the J2EE portal product built on top of WLS
  • CSS: in this context, not cascading style sheets. Common Security Service is the componentized security package that WLS uses for security.
  • SSPI: the pluggable security subsystem provided by CSS to WLS
  • ATN: authentication, which refers to the process of verifying who a user is (with a password perhaps)
  • ATZ: authorization, which refers to the process of deciding whether the authenticated user has the privilege to perform a certain action
  • UUP: a WLP feature that aggregates profile information for a user from a variety of backend sources using a plugin architecture
  • Internal LDAP: an LDAP repository embedded in CSS historically used for some default SSPI providers

Discussion Thread

From: Colleague

Quick follow-up to our discussion in the hall at BEAWorld, you said that WLP wants to stop using the internal LDAP server altogether and use the database instead. I forgot, though, did you say that had already happened in a previous release, or is that slated for the next release?

From: PJL

Yes and no.

For ATN, WLP does not use internal LDAP. WLP switched to the WLS/CSS provided SQLAuthenticator in WLP 9.2. This does not mean that customers must use it, it is merely the default. A customer may choose to toss the SQL ATN provider and plug in an LDAP, Active Directory, etc. provider instead.

Here is the WLS doc reference to SQL Authenticator: Configuring RDBMS Authentication Providers

As for ATZ (WLP entitlements and delegated administration), we rely on the default ATZ provider from WLS, which in turn uses the internal LDAP store. Currently, we are tightly bound to the default ATZ provider for various reasons, and so WLP therefore has a hard dependency on internal LDAP. This is not ideal, and so WLP wants to eliminate the internal LDAP dependency.

The forthcoming solution to this problem is for WLS to support a database as the backend store for the default ATZ provider. They should have this in the next WLS version (but no promises folks!), and so we will pick it up in a future release beyond Flatirons (the next WLP release).

From: Colleague

Right, makes sense. A couple more questions:

Can customers configure more than one ATN provider, e.g. extranet users in SQL and employees in Active Directory, is that a supported WLP configuration?

Do documents stored in WLP's virtual content repository (VCR) use the default ATZ provider as well?

Where does the Unified User Profile (UUP) fit into this picture?

From: PJL

>> Can customers configure more than one ATN provider, e.g. extranet users in SQL and employees in AD, is that a supported WLP configuration?
Yes, and you can do logic like AND and OR via the JAAS control flags (this is WLS/CSS doing that, not WLP).

>> Do documents stored in WLP's virtual content repository (VCR) use the default ATZ provider as well?
Yes, Entitlements defined on VCR documents are stored in the default ATZ provider. The documents and metadata themselves are in the WLP database if the BEA Repo is being used, or in third party systems like Documentum or Sharepoint.

>> Where does the Unified User Profile (UUP) fit into this picture?
Profile is the third leg to this: ATN, ATZ, and Profile. For WLP, all three are independent, and linked together just by username. So ATN could come from Active Directory, whereas profile can be aggregated from, for example, a mainframe, LDAP, and Siebel via UUP. WLP passes the UUP plugins the username that was authenticated, and then each plugin is responsible for retrieving the correct profile info.

From: Colleague

One piece I'm still a bit fuzzy on is how groups fit into this whole picture, I've been reading this section on edocs:

Adding and Managing Groups (WLP docs)

It sounds like WLP periodically syncs group info from the providers into some local store, which I'm guessing is the default RDBMS. Is that correct?

From: PJL

Good question.

Actually WLP doesn't really maintain its own group mapping. The ATN providers provided by WLS are responsible for doing that. We do some caching of the group tree because it can be expensive to build, so that is what those docs are talking about. But we don't write that in-memory cached tree out to the database or file system.

To see how an ATN provider is involved in group membership, look at how the SQL Authenticator gets configured as an example:

SQL Authenticator Configuration help

You can see that it has methods for managing group relationships. How this happens at runtime is a deeper dive into the WLS/CSS SSPI ...

WLS/CSS authentication providers have two components - the JAAS code that actually performs the authentication, and then a set of "mbeans" that the provider chooses to implement. Most of the mbeans are optional to implement. Here is the list for ATN providers which provide the manageability around users and groups:

SSPI MBean Quick Reference

  • GroupEditor Create a group. If the group already exists, an exception is thrown.
  • GroupMemberLister List a group's members.
  • GroupReader Read data about groups.
  • GroupRemover Remove groups.
  • MemberGroupLister List the groups containing a user or a group.
  • UserEditor Create, edit and remove users.
  • UserPasswordEditor Change a user's password.
  • UserReader Read data about users.
  • UserRemover Remove users.

So WLP uses methods from the GroupReader and GroupMemberListers mbeans on the ATN provider to have access to group membership. The SQL Authenticator implements the GroupReader and GroupMemberLister mbeans by using those SQL queries. The LDAP ATN provider GroupReader and GroupMemberLister mbeans derives Group structure from the directory structure.

That's a little abstract - it sometimes helps to see the code. Here is the javadoc for GroupReader and GroupMemberLister java interfaces that the ATN providers implement:

So WLP is not really managing it's own group repository, it's the ATN Providers that are storing that information. A little complicated, I know.

From: Colleague

So does the LDAP ATN provider support the GroupEditor as well? That is, can you write group membership changes back into external LDAP repositories?

From: PJL

The LDAP ATN provider that WLS/CSS provides is read only. You can see what mbeans it implements by looking here:

  1. Navigate to BEA-HOME\wlserver_10.0\server\lib\mbeantypes
  2. Open cssWlSecurityProviders.jar
  3. Find the .xml file that is associated with the provider you care about, in this case LDAPAuthenticator.xml
  4. In that xml file, you will see the mbean interfaces that it implements listed:

Name = "LDAPAuthenticator"

DisplayName = "LDAPAuthenticator"

Package =

Extends =

Implements =

PersistPolicy = "OnUpdate"

Since it does not include GroupEditor or UserEditor, you can infer that it is a read-only provider (aside from password). If you are a WLP customer, another way to see which mbeans are implemented for each ATN provider is through the Portal Administrator tool (PAT). Because the PAT disables certain user/group management functions in the tool depending on what mbeans are implemented on the selected provider, the PAT provides UI to show which mbeans are implemented. See the image below:


From: Colleague

Also, is there any way to create a group that includes members from more than one provider, e.g. "John" from the DB and "Bob" from LDAP? Or do you need to use roles for that scenario?

From: PJL

Yes, group membership is aggregated from the collection of installer providers. Multiple providers can contribute membership associations to a single group. Or how about this question: can "Bob" be authenticated by the SQL ATN provider, and put into the "Human Resources" group via the LDAP provider? I believe this does work.

More information...

I would encourage you to use these resources to learn more about WebLogic Security:

Add to Technorati Favorites

Comments from original blog

  • Carlo -

    OK, good to hear that it worked for you!

    We don't certify any other authorizers/role mappers. It sounds like at least some use cases work.

    Where my comment comes from is the fact that historically we had code that went around the SSPI and directly to embedded LDAP. Based on your feedback, I looked through the current code base and didn't find anything like that. I will check with the engineer who owns that code to verify. So I might have been wrong in saying it will not work at all.

    I did find a couple of places where you may see odd behavior:

    • There is code to check if the Admin server is running when doing any policy updates. This is because embedded LDAP relies on the Admin server for distribution of updates in the embedded LDAP replicates in a cluster. You will probably see errors in your logs if your Admin server is down, even if you aren't using embedded LDAP.

    • WLP has a class called LDAPChangeListener which flushes a role policy cache entry if a role policy has been updated in embedded LDAP. If you are running in a cluster, and are not using embedded LDAP, it looks like you will have to redeploy the application to get the updated role policy recognized across the cluster. Can you verify if this is true with your system?

    Thanks for the correction!

    Regards - PJL

    Posted by: plaird on January 2, 2008 at 11:31 PM

  • Hi Peter thank you for your answer. Why should the protection of WLP assets (e.g. Portlets) not work? I have written my own XACML Authorizer (based on the OpenSource SUN XACML implementation) and a RoleMapper also and it works. If WLP correctly use the WebLogic Security framework, it should work and fortunately it does ;-) Did you mean that in a future version it will not work? This scaries me because we are strongly basing our security on these implementations (and on XACML). ciao carlo

    Posted by: cdrcdr on December 21, 2007 at 6:19 AM

  • Carlo -

    What types of resources do you wish to manage with the Role and Access policies? Do you wish to entitle WLP assets such as portlets and content items, or JEE assets? For JEE assets, you could use an external repository by plugging in additional providers into the SSPI.

    But as for WLP assets, first the bad news. You will not be able to replace the entitlement engine that WLP uses for WLP assets. But I would actually argue that you don't want to replace the entitlements engine, you really want to replace the runtime policy repository. Unfortunately, WLP does not currently support storing WLP policies in anything other than embedded LDAP, except in one case (see ALES link below).

    While this isn't great news, WLP will at least remove the embedded LDAP dependency when WLP ships on WLS 10.3. You will be able to store your runtime ploicy repository in a DB then.

    Now for the good news...

    There is a solution available today. I would encourage you to look at ALES, because it does what you want to do. It centralizes role and policy management in an external repository.

    But if ALES is not suitable, there is another potential workaround here. It is possible to *manage* the policies in your external system, and then periodically sync the policies into the *runtime* repository (the embedded LDAP now, DB in a later release). An issue will be figuring out how to author WLP policies; specifically being able to create the WLP asset resource strings. Also, you will need to figure out how to allow for the external management tool to discover the set of manageable resources that do not already have policies.

    Hope this helps... PJL

    Posted by: plaird on December 14, 2007 at 8:34 AM

  • Great article! One question: we have our RoleAssignmentPolicies (XACML)as well as the AccessPolicies (XACML)in differnet repositories: we need to wtite our own XACML based authorizer (and Entitlements engine) and (possibly) remove the BEA one from the realm. Would it be possible? There would be problem/limitation doing so? regards carlo

    Posted by: cdrcdr on December 13, 2007 at 5:26 AM

  • Josh - I haven't worked with the LDAP providers in years, so I can't comment on the specifics. But in the follow up blog entry to this one, I explain how to dive into the cssWlSecurityProviders.jar to find the implementations of the BEA Atn Providers and how providers often extend other providers.

    By doing that now, I see that the BEA IPlanetAuthenticator extends the base LDAPAutenticator, which already implements UserEditor and GroupEditor. If you wish to implement custom logic for those mbeans, extending the BEA IPlanetAuthenticator provider is probably the way to go. You would create a subclass overriding the UserEditor and GroupEditor methods as necessary, and then wire it up using an XML descriptor.

    Look to the IPlanetAuthenticator itself as an example of how to wire up a provider subclass. Put your custom atn provider in its own JAR in the same directory as cssWlSecurityProviders.jar and you should be good to go.


    Posted by: plaird on October 18, 2007 at 9:15 AM

  • Hi Peter, What steps would I need to take to add the UserEditor and GroupEditor MBeans to the IPlanetAuthenticator? If I intend for users to be created using a custom objectClass defined in the iPlanet Directory Server that has custom attributes, I'm assuming that I'll have to customize the MBean to do this. Is this correct? Thanks, Josh

    Posted by: joshbrookes on October 17, 2007 at 11:28 AM

  • Hi Luciano - yes, this is why we are keen to eliminate internal LDAP as the repository for ATZ. The best way is to have a Propagation inventory that contains a backup of your policies. In that case, you can wipe it clean, and then reapply the inventory (this is not so simple if you do admin work in production, you will need to be careful about the merge). Also, a colleague was looking into a more fine grained fix (directly updating internal LDAP to fix the problem records). I don't know off-hand where he ended up with that - I will point him to this entry. Ciao, PJL

    Posted by: plaird on September 24, 2007 at 11:40 PM

  • Hello Peter, very interesting reading. I wish that more articles like this one could be published by Bea. I take advantage of this blog to ask you a question: we have hit on a Portal9.2Mp1 production installation the infamous out of sync between embedded Ldap and the portal db (p13n tables). Result, Delegated Admin page fails with a NPE and Entitlements also are not very well. It's easy to fix this problem in a non prod environment (wipe p13n tables, wipe ldap files) but which is the recommended way to deal with this issue in a clustered production environment? Thanls a lot Luciano Fiandesio

    Posted by: koevet on September 24, 2007 at 11:21 PM