This chapter describes the option of using an external RDBMS as a datastore for the authorization, role mapping, credential mapping, and certificate registry providers in WebLogic Server 10.3.6. This datastore, called the RDBMS security store, is strongly recommended for using SAML 2.0 security providers in production environments so that the data they manage can be synchronized across all the WebLogic Server instances that share that data. (Use LDAP as the security store with the SAML 2.0 security providers only in development environments.)
Note:In order to use the RDBMS security store, the preferred approach is first to create a domain in which the external RDBMS server is configured. Prior to booting the domain, you create the tables in the datastore that are required by the RDBMS security store. The WebLogic Server installation directory contains a set of SQL scripts that create these tables for each supported database.
The following sections explain how to configure and manage the RDBMS security store:
For the most up-to-date details about the specific database systems that are supported for use as the RDBMS security store for WebLogic Server, see "Supported Configurations" in What's New in Oracle WebLogic Server.
The following security providers use the RDBMS security store if that store is configured in a domain:
XACML Authorization provider
XACML Role Mapping provider
The following providers for SAML 1.1:
SAML Identity Assertion provider V2
SAML Credential Mapping provider V2
The following providers for SAML 2.0:
SAML 2.0 Identity Assertion provider
SAML 2.0 Credential Mapping provider
WebLogic Credential Mapping provider
PKI Credential Mapping provider
When the RDBMS security store is configured in a domain, an instance of any of the preceding security providers that has been created in the security realm automatically uses only the RDBMS security store as a datastore, and not the embedded LDAP server. WebLogic security providers configured in the domain that are not among those in the preceding list continue to use their respective default stores; for example, the Default Authentication provider continues to use the embedded LDAP server.
Oracle recommends that you configure the RDBMS security store at the time of domain creation. The Configuration Wizard has been enhanced to simplify this process. This utility includes an option for testing the RDBMS connection to help ensure that when the domain is booted, the security policies required to access the domain can be retrieved.
In addition to the Configuration Wizard, WebLogic Server also contains the
RDBMSSecurityStoreMBean, which is the interface for configuring the RDBMS security store via the WebLogic Scripting Tool (WLST).
To create and configuring the RDBMS security store in a domain, complete the tasks described in the following sections:
To use the RDBMS security store in a domain, Oracle recommends that you configure the RDBMS security store at the time you create that domain. Modifying an existing domain in place to use the RDBMS security store is possible; however, it is not recommended because if the database connection is not configured correctly, the policies necessary for granting access to the domain could become unavailable, resulting in a domain that cannot be used.
WebLogic Server provides two ways to create a domain in which the RDBMS security store may be configured:
By using the Configuration Wizard, which includes an option to configure the RDBMS security store. This option is available from the Customize Environment and Services Settings page.
If you choose this option, the Configuration Wizard displays subsequent windows in which you can:
Select the specific database system you wish to use as the RDBMS security store
Configure the database connection settings
Test the database connection
By using the WebLogic Scripting Tool (WLST) Offline. Operations for creating and configuring the RDBMS security store are available via the
Regardless of the method you choose to create the domain, be sure to configure the connection properties for the database that serves as the RDBMS security store as explained in the following sections.
When configuring the RDBMS security store in either the Configuration Wizard or WLST, you need to specify or configure the following:
The following RDBMS systems are supported for containing the RDBMS security store:
Oracle 9i, 10g, and 11g
MS-SQL 2000 and 2005
DB2 9.2 and 9.5
Note:When you use the Configuration Wizard to configure the RDBMS security store, the Configuration Wizard provides a drop-down list for selecting the database you want to use. The databases appearing in this drop-down list are not exclusive to only those supported for the RDBMS security store. Make sure you choose a database that is supported for this purpose (see "Supported Configurations" in What's New in Oracle WebLogic Server).
JDBC driver and class name for connecting to the RDBMS
RDBMS name, host, port, and URL
Username and password of the domain user who can access the RDBMS system
Caution:For clarity, the WLST examples provided in this section show passing username and password credentials of the RDBMS system user in clear text. However, you should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead.
Optionally, any properties that need to be passed to the RDBMS system
The parameters that you specify in the JDBC driver connection properties attribute must be a comma-separated list. The following examples show the use of WLST to configure the database connection properties for Oracle, MS-SQL, and DB2.
Example 10-1 shows an example of configuring Oracle for the RDBMS security store.
create('base_domain','SecurityConfiguration') cd('/SecurityConfiguration/base_domain') a=get('DefaultRealm') cd('Realm/myrealm') rdbms = create("myRDBMSSecurityStore", "RDBMSSecurityStore") rdbms.setUsername('ortiz') rdbms.setPassword('welcome1') rdbms.setConnectionURL('jdbc:bea:oracle://avitek21:1521') rdbms.setDriverName('weblogic.jdbc.oracle.OracleDriver') rdbms.setConnectionProperties('user=ortiz,portNumber=1521,SID=pint101a,serverName=avitek21')
Example 10-2 shows an example of configuring MS-SQL for the RDBMS security store.
create('base_domain','SecurityConfiguration') cd('/SecurityConfiguration/base_domain') a=get('DefaultRealm') cd('Realm/myrealm') rdbms = create("myRDBMSSecurityStore", "RDBMSSecurityStore") rdbms.setUsername('garnett') rdbms.setPassword('welcome1') rdbms.setConnectionURL('jdbc:bea:sqlserver://avitek6:1433') rdbms.setDriverName('weblogic.jdbc.sqlserver.SQLServerDriver') rdbms.setConnectionProperties('user=garnett,portNumber=1433,databaseName=wls3,serverName=avitek6')
Example 10-3 shows an example of configuring DB2 for the RDBMS security store.
Note:If you choose DB2, you have the option of selecting the WebLogic Type 4 JDBC driver for DB2 that is provided in WebLogic Server. However, if you use this JDBC driver, you must also specify the additional property
BatchPerformanceWorkaroundand set it to
true. If you do not set the
truein this configuration, WebLogic Server may fail to boot, generating a SecurityServiceException message.
create('base_domain','SecurityConfiguration') cd('/SecurityConfiguration/base_domain') a=get('DefaultRealm') cd('Realm/myrealm') rdbms = create("myRDBMSSecurityStore", "RDBMSSecurityStore") rdbms.setUsername('brady') rdbms.setPassword('welcome1') rdbms.setConnectionURL('jdbc:bea:db2://avitek3:50000') rdbms.setDriverName('weblogic.jdbc.db2.DB2Driver') rdbms.setConnectionProperties('user=brady,portNumber=50000,databaseName=wls,serverName=avitek3,batchPerformanceWorkaround=true')
For more information about specifying connection properties for the WebLogic Type 4 JDBC driver for DB2, see "Using WebLogic-branded DataDirect Drivers" in Programming JDBC for Oracle WebLogic Server.
Internally, the RDBMS security store uses Oracle Kodo to connect to and interoperate with the database using the WebLogic Type 4 JDBC driver for DB2. The attributes set on the
RDBMSSecurityStoreMBean are converted into attributes set on the properties of Kodo's
For more information about these attributes, see the following topics:
For more information about the attributes you can set on the
RDBMSSecurityStoreMBean, see "RDBMSSecurityStoreMBean" in the Oracle WebLogic Server MBean Reference.
For information about the default database connection properties in the Kodo DataDource, see "Using the Kodo DataSource" in the JDBC chapter of the Kodo JPA/JDO Reference Guide.
During the process of configuring the RDBMS security store via the Configuration Wizard, you are presented with the option of testing the database connection. Oracle strongly recommends using this option because it can verify that the connection is set up properly. If there were a problem with the database connection, you might not be able subsequently to boot the domain if the security providers that control access to that domain are unable to obtain the necessary security policies.
For information about configuring the RDBMS security store via the Configuration Wizard, see "Select Optional Configuration" in Creating Domains Using the Configuration Wizard.
Prior to booting the domain, the database administrator needs to run the SQL script that creates the RDBMS tables in the datastore used by the RDBMS security store. A set of SQL scripts for creating these tables for, and also removing them from, each supported RDBMS system is available in the following WebLogic Server installation directory:
When running the appropriate SQL script for the database serving as the RDBMS security store, be sure to specify the same connection properties, including the credentials of the user who has access, the database URL, etc., as specified for that RDBMS during domain creation.
Table 10-1 identifies the name of each of these SQL scripts.
|RDBMS||Script for Creating Datastore Tables||Script for Removing Datastore Tables|
Oracle 9i, 10g, 11g
MS-SQL 2000, 2005
DB2 9.2, 9.5
If the RDBMS security store is configured in a domain that includes two or more WebLogic Server instances, or a cluster, Oracle strongly recommends that you also perform the following tasks:
Enable JMS notifications for that domain.
Configure a JMS topic that can be used by the RDBMS security store.
JMS notifications enable the security data that is contained in the RDBMS security store, and that is managed by security providers in the realm, to be synchronized among all server instances in the domain.
Caution:If you do not configure a JMS topic that can be used by the RDBMS security store when configured in a multi-server or clustered domain, care should be taken when making security policy or security configuration updates. If no JMS topic is configured, it may be necessary to reboot the domain to ensure that all server instances function consistently with regards to those security updates.
You can enable JMS notifications by booting the domain in which the RDBMS security store has been configured, and configuring attributes on the
RDBMSSecurityStoreMBean via either of the following mechanisms:
WebLogic Scripting Tool
The Security Realms > RealmName > RDBMS Security Store page in the Administration Console
The attributes of the
RDBMSSecurityStoreMBean that must be set to enable JMS notifications are listed and described in Table 10-2.
The JMS topic to which the Kodo remote commit provider should publish notifications and subscribe for notifications sent from other JVMs. The target JMS topic needs to be pre-deployed.
The JNDI name of a
The topic "Connection Factory Configuration" in Configuring and Managing JMS for Oracle WebLogic Server describes the WebLogic JMS connection factory,
A comma-delimited list of key-value properties to pass to the JNDI InitialContext on construction, in the form of xx
The identity of any valid user in the security realm who has access to JNDI.
The password of the user specified in the
The number of reconnect attempts to be made if the JMS system notifies Kodo of a serious connection error. The default is 0, which causes an error to be logged, but does not result in a reconnect attempt.
For more information, see the following topics:
"Configure topics" in the Oracle WebLogic Server Administration Console Help
"Configuring Basic JMS System Resources" in Configuring and Managing JMS for Oracle WebLogic Server
"Configure the RDBMS security store" in the Oracle WebLogic Server Administration Console Help
"RDBMSSecurityStoreMBean" in the Oracle WebLogic Server MBean Reference
Normally, the WebLogic Security Service contained in each WebLogic Server instance in a multi-node domain connects at startup to the JMS server. If a security provider that uses the RDBMS security store makes a change to its security data, all WebLogic Server instances are notified via JMS, and the local caches used by the WebLogic Security Service in each server instance are synchronized to that change.
If the JMS connection fails in a WebLogic Server instance that has been successfully started, the WebLogic Security Service associated with that server instance starts the JMS connection recovery process. The recovery process sleeps one second between reconnect attempts. The recovery process is stopped if the JMS connection failure persists after the number of reconnect attempts with which the
JMSExceptionReconnectAttempts property has been configured is reached. No further reconnect attempts are made: If a change is made to the security data in one WebLogic Server instance, the local caches managed by the WebLogic Security Service in other WebLogic Server instances are not synchronized to that change. However, if the JMS connection is successfully recovered by other means (such as a server reboot), those caches become synchronized.
If the JMS connection is not successfully started at the time a WebLogic Server instance is booted, a timer task that makes reconnect attempts is automatically started. The timer task is cancelled once the connection is successfully made. Two system properties may be configured for this timer task:
Specifies the delay, in milliseconds, before the connection recovery task is executed. The default value is 1000, which causes the connection recovery process to be executed after a delay of one second.
Specifies the maximum number of reconnect attempts that can be made prior to cancelling the timer task. The default value is 3600, which causes the timer task to be cancelled once 3600 reconnect attempts have been made. No further reconnect attempts are made.
You can calculate the maximum connection polling duration by multiplying the values specified by each of the preceding system properties. For example, multiplying the default values of these two properties yields a maximum polling duration of one hour (1000 millisecond delay multiplied by 3600 reconnect attempts).
To upgrade a domain to use the RDBMS security store, Oracle recommends creating a new domain in which the RDBMS security store is configured. After you create the new domain, you should export the security data from the security realm of the old domain, and import it into a security realm of the new domain. When you import security data into a security realm in a domain that uses the RDBMS security store, the data for the security providers that use the RDBMS security store is automatically loaded into that datastore. Data for security providers that do not use the RDBMS security store is automatically imported into the stores that those providers normally use by default.
It is possible to selectively migrate security providers individually from one security realm to another. However, when migrating security data to a domain that uses the RDBMS security store, Oracle recommends migrating the security realm's data in a single operation.
For information about migrating security realms, see the following topics: