27 Managing the RDBMS Security Store

Oracle WebLogic Server provides an option of using an external RDBMS as a datastore for the authorization, role mapping, credential mapping, and certificate registry providers. This datastore, called the RDBMS security store, is strongly recommended for using SAML 2.0 services in two or more WebLogic Server instances in that domain, such as in a cluster.

The RDBMS security store is required by the 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.

This chapter presents the following topics:

• Security Providers that Use the RDBMS Security Store

• Configuring the RDBMS Security Store

• Upgrading a Domain to Use 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 Oracle Fusion Middleware Supported System Configurations.

Security Providers that Use the RDBMS Security Store

Some WebLogic security providers use the RDBMS security store, if that store is configured in a domain.

The following is a list of such security providers:

• 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

• Certificate Registry

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, and before booting the domain. WebLogic Server includes the RDBMSSecurityStoreMBean, which is the interface for configuring the RDBMS security store via the WebLogic Scripting Tool (WLST). (The Configuration Wizard does not provide the ability to configure the RDBMS security store.)

Configuring the RDBMS Security Store

To create and configure the RDBMS security store, you must perform several tasks including creating a domain with the RDBMS security store, creating RDBMS tables in the security datastore, configuring a JMS topic for the RDBMS security store, and so on.

The following topics describe the tasks you need to perform in order to configure the RDBMS security store:

• Create a Domain with the RDBMS Security Store

• Create RDBMS Tables in the Security Datastore

• Configure a JMS Topic for the RDBMS Security Store

Create a Domain with the RDBMS Security Store

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. Oracle does not recommend modifying an existing domain in place to use the RDBMS as the security store. 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.

The high-level process for creating a domain to use an RDBMS security store is as follows:

1. Create a new domain to use an RDBMS security store in either of the following ways:

   • Use WLST offline to create the domain and configure the RDBMS security store using a single script.

   • Create a new WebLogic domain using the Configuration Wizard or WLST. Then, before starting the domain, use WLST offline to configure the RDBMS security store. The Configuration Wizard does not provide the ability to configure the RDBMS security store. See Creating and Configuring the WebLogic Domain in .

   Sample scripts for configuring the RDBMS security store using WLST offline are provided in unresolvable-reference.html#GUID-347B49A7-E107-4FEB-90BF-89E60E846404.

2. Prior to starting the domain, create the RDBMS tables in your datastore. The WebLogic Server installation directory includes a set of scripts for each supported RDBMS system. Typically this step is performed by the database administrator. See Create RDBMS Tables in the Security Datastore.

3. Test the database connection using the Java utility dbping. See Testing the Database Connection.

4. Start the domain.

   Note:

   The domain will not start if the RDBMS tables are not created or the database connection is not available.

5. After you start the domain, you can manage the RDBMS configuration using WebLogic Remote Console. See Configure the RDBMS Security Store in .

6. 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 enable JMS notifications for that domain and configure a JMS topic that can be used by the RDBMS security store. See Configure a JMS Topic for the RDBMS Security Store.

7. If you are configuring single sign-on using SAML, see Configuring SAML 2.0 Services. The RDBMS security store is required by the 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.

Enabling Updates from Distribution Points

Updating CRLs from distribution points is enabled by default. If the appropriate CRL for a certificate being validated does not already exist in the local cache, the CRL is downloaded from an available distribution point.

WebLogic Server also allows you to configure a timeout interval for the CRL download from a distribution point. This timeout interval limits the wait time for CRL downloads, and also minimizes the risk of blocked threads and vulnerability to denial of service attacks. Note that if the CRL download times out, the CRL method reports that the revocation status is unknown; however, the CRL download continues in a separate thread until complete and the CRL becomes available for future CRL checking.

You can configure CRL distribution points for a WebLogic domain using the following MBean attributes:

Table 27-1 MBean Attributes

MBean Attribute	Description	Default Value
CertRevocMBean.CrlDpEnabled	Specifies whether CRL distribution points are enabled domain-wide.	true
CertRevocMBean.CrlDpDownloadTimeout	Specifies the overall timeout interval, domain-wide, for the distribution point CRL download, expressed in seconds. The valid range is between 1 and 300, inclusive.	10

You can also configure CA overrides for these MBean attributes. See Configuring CRL Properties in a Certificate Authority Override.

For information about how to use the WebLogic Server Administration Console to configure CRL distribution points for a WebLogic domain, see Configure domain-wide CRL settings in the .

Create Domain with RDBMS Security Store Example

Example 27-1 provides an example WLST script to create a domain named base_domain, and to configure an MS/SQL database as the RDBMS security store.

Example 27-1 Creating a Domain and Configuring MS-SQL as the RDBMS Security Store

# Select and load the template to use for creating the domain
selectTemplate('Basic WebLogic Server Domain')
loadTemplates()
cd('/')

# Set the name of the domain as base_domain
set('Name', 'base_domain')

# Set the listen port for the Administration Server
cd('Servers/AdminServer')
set('Name', 'admin')
set('ListenPort',7001)

# Set the user name and password for the WebLogic Server administration user
cd('/')
cd('Security')
cd('base_domain')
cd('User/adminusername')
cmo.setName('adminusername')
cmo.setPassword('adminpassword')

# Create the RDBMS security store
print("configure RDBMS store")
create('base_domain','SecurityConfiguration') 
cd('/SecurityConfiguration/base_domain') 
cd('Realm/myrealm') 

# Specify the database attributes on the RDBMSSecurityStoreMBean 
rdbms.setUsername('DBuser')  
rdbms.setPasswordEncrypted('DBpassword')
rdbms.setConnectionURL('jdbc:weblogic:sqlserver://host.example.com:port) 
rdbms.setDriverName('weblogic.jdbc.sqlserver.SQLServerDriver') 
rdbms.setConnectionProperties('user=DBuser,portNumber=port,databaseName=DbName,serverName=host.example.com') 

# Write the domain 
writeDomain('/home/domains/base_domain')

# Exit WLST offline
exit()

Oracle Database Example

Example 27-2 shows an example WLST script for configuring an Oracle Database as the RDBMS security store. Execute this script after creating a new domain using the Configuration Wizard or WLST, and before starting the domain.

Example 27-2 Configuring Oracle Database for the RDBMS Security Store

# Read the domain using the complete path to the domain directory
readDomain(domainDirName)

# Create the RDBMS security store
create('DomainName','SecurityConfiguration') 
cd('/SecurityConfiguration/DomainName') 
cd('Realm/myrealm') 
rdbms = create('myRDBMSSecurityStore','RDBMSSecurityStore') 

# Specify the database attributes on the RDBMSSecurityStoreMBean
rdbms.setUsername('DBuser') 
rdbms.setPasswordEncrypted('DBpassword') 
rdbms.setConnectionURL('jdbc:oracle:thin:@hostname.domain:port:sid') 
rdbms.setDriverName('oracle.jdbc.OracleDriver') 
rdbms.setConnectionProperties('user=DBuser,portNumber=port,SID=sid,serverName=hostname.domain')

# Update the domain
updateDomain()

# Exit WLST offline
exit()

MS-SQL Example

Example 27-3 shows an example WLST script for configuring an MS-SQL database as the RDBMS security store. Execute this script after creating a new domain using the Configuration Wizard or WLST, and before starting the domain.

Example 27-3 Configuring MS-SQL for the RDBMS Security Store

# Read the domain using the complete path to the domain directory
readDomain(DomainDirName)

# Create the RDBMS security store
create('DomainName','SecurityConfiguration') 
cd('/SecurityConfiguration/DomainName')
cd('Realm/myrealm') 
rdbms = create('myRDBMSSecurityStore','RDBMSSecurityStore') 

# Specify the database attributes on the RDBMSSecurityStoreMBean
rdbms.setUsername('DBuser') 
rdbms.setPasswordEncrypted('DBpassword') 
rdbms.setConnectionURL('jdbc:weblogic:sqlserver://ServerName:port') 
rdbms.setDriverName('weblogic.jdbc.sqlserver.SQLServerDriver') 
rdbms.setConnectionProperties('user=DBuser,portNumber=port,databaseName=DBname,serverName=ServerName') 

# Update the domain
updateDomain()

# Exit WLST offline
exit()

DB2 Example

Example 27-4 shows an example WLST script for configuring DB2 as the RDBMS security store. Execute this script after creating a new domain using the Configuration Wizard or WLST, and before starting the domain.

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 BatchPerformanceWorkaround and set it to true. If you do not set the BatchPerformanceWorkaround to true in this configuration, WebLogic Server may fail to boot, generating a SecurityServiceException message.

Example 27-4 Configuring DB2 for the RDBMS Security Store

# Read the domain using the complete path to the domain directory
readDomain(domainDirName)

Create the RDBMS security store
create('DomainName','SecurityConfiguration') 
cd('/SecurityConfiguration/DomainName') 
cd('Realm/myrealm') 
rdbms = create('myRDBMSSecurityStore','RDBMSSecurityStore') 

# Specify the database attributes on the RDBMSSecurityStoreMBean
rdbms.setUsername('DBuser') 
rdbms.setPasswordEncrypted('DBpassword') 
rdbms.setConnectionURL('jdbc:weblogic:db2://ServerName:port') 
rdbms.setDriverName('weblogic.jdbc.db2.DB2Driver') 
rdbms.setConnectionProperties('user=DBuser,portNumber=port,databaseName=DBname,AlternateID=DBname-alt,serverName=ServerName,batchPerformanceWorkaround=true') 

# Update the domain
updateDomain()

# Exit WLST offline
exit()

For more information about specifying connection properties for the WebLogic Type 4 JDBC driver for DB2, see Using DataDirect Documentation in .

Testing the Database Connection

When you configure an RDBMS security store, Oracle strongly recommends testing the database connection to verify that the connection is set up properly. If there were a problem with the database connection, you might not be able to boot the domain if the security providers that control access to that domain are unable to obtain the necessary security policies.

You can test the database connection using the WebLogic Server Java utility dbping. The dbping command-line utility tests the connection between the RDBMS and your client machine using a JDBC driver. See dbping in .

Note:

Before running the dbping utility, be sure to include the JDK in your PATH environment variable, then run the setDomainEnv script to set up your environment.

The following example shows how to execute the dbping utility using an Oracle Thin Driver connected to an Oracle Database. The example includes steps for setting up your environment on a Linux host before executing the dbping utility.

$ bash
$ export PATH=$JAVA_HOME/bin:$PATH
$ cd myDomain/bin
$ . ./setDomainEnv.sh
$ java utils.dbping ORACLE_THIN DBuser DBpassword myhost.example.com:port:DemoDB

**** Success!!! ****

You can connect to the database in your app using:

  java.util.Properties props = new java.util.Properties();
  props.put("user", "DBuser");
  props.put("password", "DBpassword");
  java.sql.Driver d =
    Class.forName("oracle.jdbc.OracleDriver").newInstance();
  java.sql.Connection conn =
    Driver.connect("DBuser", props);

Create RDBMS Tables in the Security Datastore

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 each supported RDBMS system is available in the following WebLogic Server installation directory. SQL scripts for removing the tables are also provided.

WL_HOME/server/lib 

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, and so on, as specified for that RDBMS during domain creation.

Table 27-2 identifies the name of each of these SQL scripts. For specific database versions supported, see Oracle Fusion Middleware Supported System Configurations.

Table 27-2 SQL Scripts for Creating and Removing RDBMS Datastore Tables

RDBMS	Script for Creating Datastore Tables	Script for Removing Datastore Tables
Oracle	rdbms_security_store_oracle.sql	rdbms_security_store_oracle_remove.sql
MS-SQL	rdbms_security_store_sqlserver.sql	rdbms_security_store_sqlserver_remove.sql
DB2	rdbms_security_store_db2.sql	rdbms_security_store_db2_remove.sql
Derby	rdbms_security_store_derby.sql	rdbms_security_store_derby_remove.sql

Configure a JMS Topic for the RDBMS Security Store

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:

1. Enable JMS notifications for that domain.
2. 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.

Note:

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 using either of the following mechanisms:

• WebLogic Scripting Tool

• In WebLogic Remote Console, open the Edit Tree and go to Security, then Realms, then myRealm, then RDBMS Security Store.

The attributes of the RDBMSSecurityStoreMBean that must be set to enable JMS notifications are listed and described in Table 27-3.

Table 27-3 RDBMSSecurityStoreMBean Attributes for Configuring a JMS Topic

Attribute Name	Description
JMSTopic	The JMS topic to which notifications are published to and to which notifications sent from other JVMs are subscribed. The target JMS topic needs to be pre-deployed.
JMSTopicConnectionFactory	The JNDI name of a javax.jms.TopicConnectionFactory instance to use for finding JMS topics. The topic Connection Factory Configuration in describes the WebLogic JMS connection factory, weblogic.jms.ConnectionFactory, which is a javax.jms.TopicConnectionFactory instance. Refer to this topic for information about configuring a connection factory.
NotificationProperties	A comma-delimited list of key-value properties to pass to the JNDI InitialContext on construction, in the form of xxKey=xxValue, xxKey=xxValue. The following properties must be specified: java.naming.provider.url — Property for specifying configuration information for the service provider to use. The value of the property should contain a URL string. For example: iiops://localhost:7002 java.naming.factory.initial — Property for specifying the initial context factory to use. The value of the property should be the fully-qualified class name of the factory class that will create an initial context. For example: weblogic.jndi.WLInitialContextFactory
JNDIUserName	The identity of any valid user in the security realm who has access to JNDI.
JNDIPassword	The password of the user specified in the JNDIUserName attribute.
JMSExceptionReconnectAttempts	The number of reconnect attempts to be made if the JMS system detects a serious connection error. The default is 0, which causes an error to be logged, but does not result in a reconnect attempt.

See the following topics:

• Configure Resources for JMS System Modules in

• Configuring Basic JMS System Resources in

• Configure the RDBMS Security Store in

• RDBMSSecurityStoreMBean in the

Configuring JMS Connection Recovery in the Event of Failure

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:

• com.bea.common.security.jms.initialConnectionRecoverInterval

  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.

• com.bea.common.security.jms.initialConnectionRecoverAttempts

  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).

Upgrading a Domain to Use the RDBMS Security Store

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.

Note:

For details about creating a new domain and configuring the RDBMS security store, see Create a Domain with the RDBMS Security Store.

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 Migrating Security Data.