Configuring RDBMS Authentication Providers

About Configuring the RDBMS Authentication Providers

WebLogic Server includes RDBMS Authentication providers for SQL database and relational databases. These providers include the following:

SQL Authenticator—Uses a SQL database and allows both read and write access to the database. This Authentication provider is configured by default with a typical SQL database schema, which you can configure to match your database's schema. See Configuring the SQL Authentication Provider.
Read-only SQL Authenticator—Uses a SQL database and allows only read access to the database. For write access, you use the SQL database's own interface, not the WebLogic security provider. See Configuring the Read-Only SQL Authenticator.
Custom RDBMS Authenticator—Requires you to write a plug-in class. This may be a better choice if you want to use a relational database for your authentication data store, but the SQL Authenticator's schema configuration is not a good match for your existing database schema. See Configuring the Custom DBMS Authenticator.

For information about adding an RDBMS Authentication provider to your security realm, see Configure Authentication and Identity Assertion providers in the Oracle WebLogic Server Administration Console Online Help. Once you have created an instance of the RDBMS Authentication provider, configure it on the RDBMS Authentication provider's Configuration > Provider Specific page in the WebLogic Server Administration Console.

Common RDBMS Authentication Provider Attributes

All three RDBMS Authentication providers included with WebLogic Server have configuration options for setting the data source name, the Group Membership Searching and Max Group Membership Search Level attributes, and the group caching attributes. These configuration options are described in the following topics:

Data Source Attribute

The Data Source Name specifies the WebLogic Server data source to use to connect to the database.

Group Searching Attributes

The Group Membership Searching and Max Group Membership Search Level attributes specify whether recursive group membership searching is unlimited or limited, and if limited, how many levels of group membership can be searched. For example, if you specify that Group Membership Searching is LIMITED, and the Max Group Membership Search Level is 0, then the RDBMS Authentication providers will find only groups that the user is a direct member of. Specifying a maximum group membership search level can greatly increase authentication performance in certain scenarios, since it may reduce the number of DBMS queries executed during authentication. However, you should only limit group membership search if you can be certain that the group memberships you require are within the search level limits you specify.

Note:

If the RDBMS contains cyclic groups, or groups that are defined to contain themselves, the RDBMS Authentication provider may be unable to complete the authentication process. Setting the Group Membership Searching and Max Group Membership Search Level attributes can help limit recursive group name lookups. However, the use of RDBMS Authentication providers with cyclic groups is not supported and must be avoided.

Group Caching Attributes

You can improve the performance of RDBMS Authentication providers by caching the results of group hierarchy lookups. Use of this cache can reduce the frequency with which the RDBMS Authentication provider needs to access the database. In the WebLogic Server Administration Console, you can use the Performance page for your Authentication provider to configure the use, size, and duration of this cache. See Security Realms: Security Providers: SQL Authenticator: Performance in the Oracle WebLogic Server Administration Console Online Help.

Configuring the SQL Authentication Provider

If you are using the SQL Authentication provider, you configure how the provider and its associated database handle user passwords, and you configure the SQL statement attributes needed for accessing user information in the database. Configuring these attributes is described in the following sections:

For detailed information about configuring a SQL Authentication provider, see Security Realms: Security Providers: SQL Authenticator: Provider Specific in the Oracle WebLogic Server Administration Console Online Help.

Password Attributes

The following attributes govern how the SQL Authentication provider and its underlying database handle user passwords:

Plaintext Passwords Enabled - Specifies whether you can use plain text passwords.
Password Style Retained - Controls how a password is stored in the database when updating an existing user's password. If enabled, the default, the password style and algorithm used for the original password in the database are used for the new password. If disabled, the provider uses the settings specified for the Password Algorithm and Password Style attributes for the new password.
Password Style - Specifies the password style to use when storing passwords for new users, and for updating the password of existing users if the Password Style Retained attribute is disabled. Valid options are PLAINTEXT, HASHED, or SALTEDHASHED.
Password Algorithm -The message digest algorithm used to hash passwords for storage. The value specified must be a standard algorithm name and must be recognized by a Java Cryptography Extension (JCE) provider that is available at runtime. Examples include SHA-1 and SHA-256.The Java Cryptography Architecture (JCA) defines the standard algorithm specifications, described at https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#algspec.

Note:
The SQL authenticator uses the following formula for the SALTEDHASHED password:
{SSHA} + plain text salt + base64Encode(sha-1{salt + plain text password})

The formula shown uses the default value of sha-1. If you specify a value other than SHA-1 for the password algorithm, then that value is used instead. Because the SQL Authenticator uses a string type to hold the hashed password value, this formula uses base64 encoding so that the bytes produced by the password algorithm can be stored as strings in the RDBMS tables.

SQL Statement Attributes

SQL statement attributes specify the SQL statements used by the provider to access and edit the username, password, and group information in the database. With the default values in the SQL statement attributes, it is assumed that the database schema includes the following tables:

users (username, password, [description])
groupmembers (group name, group member)
groups (group name, group description)

Note:

The tables referenced by the SQL statements must exist in the database; the provider will not create them. You can modify these attributes as needed to match the schema of your database. However, if your database schema is radically different from this default schema, you may need to use a Custom DBMS Authentication provider instead.

Configuring the Read-Only SQL Authenticator

The Read-Only SQL Authentication provider's configurable attributes include those that specify the SQL statements used by the provider to list the username, password, and group information in the database. You can modify these attributes as needed to match the schema of your database. For detailed information about configuring a Read-Only SQL Authentication provider, see Security Realms: Security Providers: Read Only SQL Authenticator: Provider Specific in the Oracle WebLogic Server Administration Console Online Help.

Configuring the Custom DBMS Authenticator

The Custom DBMS Authentication provider, like the other RDBMS Authentication providers, uses a relational database as its data store for user, password, and group information. Use this provider if your database schema does not map well to the SQL schema expected by the SQL Authenticator. In addition to the attributes described in Common RDBMS Authentication Provider Attributes, the Custom DBMS Authentication provider's configurable attributes include those for the plug-in class.

Plug-In Class Attributes

A Custom DBMS Authentication provider requires that you write a plug-in class that implements the weblogic.security.providers.authentication.CustomDBMSAuthenticatorPlugin interface. The class must exist in the system classpath and must be specified in the Plug-in Class Name attribute for the Custom DBMS Authentication provider. Optionally, you can use the Plugin Properties attribute to specify values for properties defined by your plug-in class.