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:
- Database Base Management System (DBMS) authentication providers
- SQL Authenticator
- SQL Authentication provider
- RDBMS Authentication providers
- Read-only SQL Authentication provider
- Custom DBMS Authentication provider
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:
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:
- GroupReader Read data about groups.
- GroupMemberLister List a group's members.
- MemberGroupLister List the groups containing a user or a group.
- UserReader Read data about users.
- UserPasswordEditor Change a user's password.
- GroupEditor Create a group. If the group already exists, an exception is thrown.
- GroupRemover Remove groups.
- UserEditor Create, edit and remove users.
- UserRemover Remove users.
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.
- CustomDBMSAuthenticatorPlugin Javadoc - explains what needs to be implemented
- Sample CustomDBMSAuthenticator provider - the MedRecDBMSPlugin from the MedRec sample (found in your install at BEA_HOME/WL_HOME/samples/server/medrec/src/security/com/bea/medrec/security)
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">
<sec:control-flag>
SUFFICIENT
</sec:control-flag>
<wls:enable-group-membership-lookup-hierarchy-caching>
false
</wls:enable-group-membership-lookup-hierarchy-caching>
<wls:data-source-name>
p13nDataSource
</wls:data-source-name>
<wls:sql-create-group>
INSERT INTO GROUPS VALUES ( 'arbitrary change' , ? )
</wls:sql-create-group>
</sec:authentication-provider>
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
CREATE TABLE USERS (
U_NAME VARCHAR(200) NOT NULL,
U_PASSWORD VARCHAR(50) NOT NULL,
U_DESCRIPTION VARCHAR(1000))
;
ALTER TABLE USERS
ADD CONSTRAINT PK_USERS
PRIMARY KEY (U_NAME)
;
CREATE TABLE GROUPS (
G_NAME VARCHAR(200) NOT NULL,
G_DESCRIPTION VARCHAR(1000) NULL)
;
ALTER TABLE GROUPS
ADD CONSTRAINT PK_GROUPS
PRIMARY KEY (G_NAME)
;
CREATE TABLE GROUPMEMBERS (
G_NAME VARCHAR(200) NOT NULL,
G_MEMBER VARCHAR(200) NOT NULL)
;
ALTER TABLE GROUPMEMBERS
ADD CONSTRAINT PK_GROUPMEMS
PRIMARY KEY (
G_NAME,
G_MEMBER
)
;
ALTER TABLE GROUPMEMBERS
ADD CONSTRAINT FK1_GROUPMEMBERS
FOREIGN KEY ( G_NAME )
REFERENCES GROUPS (G_NAME)
ON DELETE CASCADE
;
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:
- Security Fundamentals - official WebLogic security primer
- WebLogic Server SSPI - the CSS security architecture
- SSPI Provider Samples - reading aboout the SSPI is good, but coding is even better. Try building your own ATN provider.
- Foundations of WLP Security - official doc about how WLP integrates into WLS Security
- Implementing SSO with the WLS SSPI - my dev2dev blog on SSO with Identity Asserters
- JAAS Fundamantals - a dev2dev article by Bill Kemp and Rich Helton
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.
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
