10 Understanding Data Source Security

This chapter provides information on how to configure and use data source security in your application environment. Considerations include the number and volatility of WebLogic Server and Database users, the granularity of data access, the depth of the security identity (property on the connection or a real user), performance, coordination of various components in the software stack, and driver capabilities.

The following sections provide information with database security options:

Introduction to WebLogic Data Source Security Options

By default, you define a single database user and password for a datasource. You can store it in the datasource descriptor or make use of the Oracle wallet (see Creating and Managing Oracle Wallet). This is a very simple and efficient approach to security. All of the connections in the connection pool are owned by this user and there is no special processing when a connection is given out. That is, it's a homogenous connection pool and any request can get any connection from a security perspective (there are other aspects, such as affinity). Regardless of the end user of the application, all connections in the pool use the same security credentials to access the DBMS. No additional information is needed when you get a connection because it's all available from the datasource descriptor or wallet. For example:

java.sql.Connection conn =  mydatasource.getConnection();


You can enter the password as a name-value pair in the Properties field (this not permitted for production environments) or you can enter it in the Password field. The value in the Password field overrides any password value defined in the Properties passed to the JDBC Driver when creating physical database connections.

It is recommended that you use the Password attribute in place of the password property in the properties string because the Password value is encrypted in the configuration file (stored as the password-encrypted attribute in the jdbc-driver-params tag in the module file) and is hidden in the administration console. The Properties and Password fields are located on the administration console data source creation wizard or data source configuration page. See "JDBC Data Source: Configuration: Connection Pool" in Oracle WebLogic Server Administration Console Online Help.

The JDBC API can also be used to programmatically specify the database username and password as in the following.

java.sql.Connection conn = mydatasource.getConnection(”user”, ”password”);

Although the JDBC specification implies that the getConnection(”user”, ”password”) method should take a database user and associated password, software vendors have developed implementations according to their own interpretation of the specification. Oracle WebLogic Server, by default, treats this as an application server user and password:

  • The pair is authenticated to see if it is a valid user and that user is used for WebLogic security permission checks.

  • The user is then mapped to a database user and password using the data source credential mapper.

WebLogic Server's implementation generically follows the specification but the database credentials are one-step removed from the application code.

While the default approach is simple, it does mean that only one user is doing all of the work. You can't determine who actually did the update nor can you restrict SQL operations by who is running the operation, at least at the database level. Any type of per-user logic needs to be in the application code instead of relying on the database. There are various WebLogic datasource features that can be configured to provide per-user information about the operations.

WebLogic Data Source Security Options

The following table describes the various features available for WebLogic data sources to configure database security credentials.

Table 10-1 WebLogic Data Source Configuration Options for Security Credentials

Feature Description Can be used with . . . Can't be used with . . .

User authentication


Default getConnection(user, password) behavior – WebLogic validates the input and uses the user/password in the descriptor.

Set client identifier

Identity pooling, Use database credentials

Use database credentials

Instead of using the credential mapping, use the supplied user and password directly.

Set client identifier, Proxy session, Identity pooling

User authentication

Set Client Identifier

Set a client identifier property associated with the connection (Oracle and DB2 only).



Proxy Session

Set a light-weight proxy user associated with the connection (Oracle-only).

Set client identifier, Use database credentials

Identity pooling

Identity pooling

Heterogeneous pool of connections owned by specified users.

Set client identifier, Use database credentials

Proxy session, User authentication, Labeling, Active GridLink


All of these features are available with both XA and non-XA drivers.

All of these features are configurable on the Identity tab of the Data Source Configuration tab in the administration console. See "JDBC Data Source: Configuration: Identity Option" in Oracle WebLogic Server Administration Console Online Help.


Prior WebLogic Server release 12.1.2, the Proxy Session and Use Database Credentials options were only on the Oracle tab.

The following sections describe these features in more detail:

Credential Mapping vs. Database Credentials

Each WebLogic data source has a credential map that is a mechanism used to map a key, in this case a WebLogic user, to security credentials (user and password). By default, when a user and password are specified when getting a connection, they are treated as credentials for a WebLogic user, validated, and are converted to a database user and password using a credential map associated with the data source. If a matching entry is not found in the credential map for the data source, then the user and password associated with the data source definition are used. Because of this defaulting mechanism, you should be careful what permissions are granted to the default user. Alternatively, you can define an invalid default user to ensure that no one can accidentally get through (in this case, you would need to set the initial capacity for the pool to zero so that the pool is populated only by valid users).

To create an entry in the credential map:

  1. Create a WebLogic user. In the administration console, go to Security realms, select your realm (for example, myrealm), select Users, and select New.

  2. Create the mapping as described in "Configure credential mapping for a JDBC data source" in Oracle WebLogic Server Administration Console Online Help.

The advantages of using the credential mapping are that:

  • You don't hard-code the database user/password into a program or need to prompt for it in addition to the WebLogic user/password.

  • It provides a layer of abstraction between WebLogic security and database settings such that many WebLogic identities can be mapped to a smaller set of DB identities, thereby only requiring middle-tier configuration updates when WebLogic users are added/removed.

You can cut down the number of users that have access to a data source to reduce the user maintenance overhead. For example, suppose that a servlet has the one pre-defined WebLogic user/password for data source access that is hardwired in its code using a getConnection(user, password) call. Every WebLogic user can reap the specific DBMS access coded into the servlet, but none has to have general access to the data source. For instance, there may be a Sales DBMS which needs to be protected from unauthorized eyes, but it contains some day-to-day data that everyone needs. The Sales data source is configured with restricted access and a servlet is built that hardwires the specific data source access credentials in its connection request. It uses that connection to deliver only the generally needed day-to-day info to any caller. The servlet cannot reveal any other data and no WebLogic user can get any other access to the data source. This is the approach that many large applications use and is the logic behind the default mapping behavior in WebLogic Server.

The disadvantages of using the credential map are that:

  • It is difficult to manage (create, update, delete) with a large number of users; it is possible to use WLST scripts or a custom JMX client utility to manage credential map entries.

  • You can't share a credential map between data sources so they must be duplicated.

Some applications prefer not to use the credential map. Instead, the credentials passed to getConnection(user, password) should be treated as database credentials and used to authenticate with the database for the connection, avoiding going through the credential map. This is enabled by setting the use-database-credentials to true. See "Configure Oracle parameters" in Oracle WebLogic Server Administration Console Online Help.

When use-database-credentials is enabled, it turns of credential mapping for the following attributes:

  • identity-based-connection-pooling-enabled

  • oracle-proxy-session

  • set client identifier


in the data source schema, the set client identifier feature is poorly named credential-mapping-enabled. The documentation and the console refer to it as set client identifier.).

To review the behavior of credential mapping and using database credentials:

  • If using the credential map, there needs to be a mapping for each WebLogic user to database user for those users that have access to the database; otherwise the default user for the data source is used. If you always specify a user/password when getting a connection, you only need credential map entries for those specific users.

  • If using database credentials without specifying a user/password, the default user and password in the data source descriptor are always used. If you specify a user/password when getting a connection, that user is used for the credentials. WebLogic users are not involved at all in the data source connection process.

Set Client Identifier on Connection

When this feature is enabled on the data source, a client property is associated with the connection. The underlying SQL user remains unchanged for the life of the connection but the client value can change. This information can be used for accounting, auditing, or debugging. The client property is based on either the WebLogic user mapped to a database user based on the credential map or the database user parameter directly from the getConnection() method, based on the use database credentials setting described earlier.

To enable this feature, select Set Client ID On Connection in the Administration Console. See "Enable Set Client ID On Connection for a JDBC data source" in Oracle WebLogic Server Administration Console Online Help.

The Set Client Identifier feature is only available for use with the Oracle thin driver and the IBM DB2 driver, based on the following interfaces:

  • For pre-Oracle 12c, oracle.jdbc.driver.OracleConnection.setClientIdentifier(client) is used. For more information about how to use this for auditing and debugging, see "Using the CLIENT_IDENTIFIER Attribute to Preserve User Identity" in the Oracle Database Security Guide. You can get the value using getClientIdentifier() from the driver using the ojdbcN.jar or ojdbcN_g.jar files.


    Setting the client identifier using the Oracle driver is disabled if you are using ojdbcNdms.jar, the default jar file for Oracle Fusion MiddleWare and Oracle Fusion Applications. In this case, the Set Client Identifier feature is not supported.

    To get back the value from the database as part of a SQL query, use a statement like the following:

    select sys_context('USERENV','CLIENT_IDENTIFIER') from DUAL
  • Starting in Oracle 12c, java.sql.Connection.setClientInfo(”OCSID.CLIENTID", client) is used. This is a JDBC standard API, although the property values are proprietary. A problem with setClientIdentifier usage is that there are pieces of the Oracle technology stack that set and depend on this value. If application code also sets this value, it can cause problems. This has been addressed with setClientInfo by making use of this method a privileged operation. A well-managed container can restrict the Java security policy grants to specific namespaces and code bases, and protect the container from out-of-control user code. When running with the Java security manager, permission must be granted in the Java security policy file for:

    permission "oracle.jdbc.OracleSQLPermission" "clientInfo.OCSID.CLIENTID";

    Using the name OCSID.CLIENTID allows for upward compatible use of select sys_context('USERENV','CLIENT_IDENTIFIER') from DUAL or use the JDBC standard API java.sql.getClientInfo(”OCSID.CLIENTID") to retrieve the value.

  • Setting this value in the Oracle USERENV context can be used to drive the Oracle Virtual Private Database (VPD) feature to create security policies to control database access at the row and column level. Essentially, Oracle Virtual Private Database adds a dynamic WHERE clause to a SQL statement that is issued against the table, view, or synonym to which an Oracle Virtual Private Database security policy was applied. See "Using Oracle Virtual Private Database to Control Data Access" in the Oracle Database Security Guide. Using this data source feature means that no programming is needed on the WebLogic side to set this context. The context is set and cleared by the WebLogic data source code.

  • For the IBM DB2 driver, com.ibm.db2.jcc.DB2Connection.setDB2ClientUser(client) is used for older releases (prior to version 9.5). This specifies the current client user name for the connection. Note that the current client user name can change during a connection (unlike the user). This value is also available in the CURRENT CLIENT_USERID special register. You can select it using a statement like select CURRENT CLIENT_USERID from SYSIBM.SYSTABLES.

  • When running the IBM DB2 driver with JDBC 4.0 (starting with version 9.5), java.sql.Connection.setClientInfo(”ClientUser”, client) is used. You can retrieve the value using java.sql.Connection.getClientInfo(”ClientUser”) instead of the DB2 proprietary API (even if set using setDB2ClientUser()).

Oracle Proxy Session

Oracle proxy authentication allows one JDBC connection to act as a proxy for multiple (serial) light-weight user connections to an Oracle database with the thin driver. You can configure a WebLogic data source to allow a client to connect to a database through an application server as a proxy user. The client authenticates with the application server and the application server authenticates with the Oracle database. This allows the client's user name to be maintained on the connection with the database.


This feature is only supported when using the Oracle thin driver and a supported Oracle database (the database url must contain oracle.

Use the following steps to configure proxy authentication on a connection to an Oracle database.

  1. If you have not yet done so, create the necessary database users.

  2. On the Oracle database, provide CONNECT THROUGH privileges. For example:

    SQL> ALTER USER connectionuser GRANT CONNECT THROUGH dbuser;

    where connectionuser is the name of the application user to be authenticated and dbuser is an Oracle database user.

  3. Create a generic or Active GridLink data source and set the user to the value of dbuser.

  4. To use:

    • WebLogic credentials, create an entry in the credential map that maps the value of wlsuser to the value of dbuser, as described earlier.

    • Database credentials, enable ”Use Database Credentials”, as described earlier

  5. Enable Oracle Proxy Authentication, see "Configure Oracle parameters" in Oracle WebLogic Server Administration Console Help.

  6. Log on to a WebLogic Server instance using the value of wlsuser or dbuser.

  7. Get a connection using getConnection(username, password). The credentials are based on either the WebLogic user that is mapped to a database user or the database user directly, based on the ”use database credentials” setting.

You can see the current user and proxy user by executing:

select user, sys_context('USERENV','PROXY_USER') from DUAL


getConnection fails if Use Database Credentials is not enabled and the value of the user/password is not valid for a WebLogic user. Conversely, it fails if Use Database Credentials is enabled and the value of the user/password is not valid for a database user.

A proxy session is opened on the connection based on the user each time a connection request is made on the pool. The proxy session is closed when the connection is returned to the pool. Opening or closing a proxy session has the following impact on JDBC objects:

  • Closes any existing statements (including result sets) from the original connection.

  • Clears the WebLogic Server statement cache.

  • Clears the client identifier, if set.

  • The WebLogic Server test statement for a connection is recreated for every proxy session.

These behaviors may impact applications that share a connection across instances and expect some state to be associated with the connection.

Oracle proxy session is also implicitly enabled when use-database-credentials is enabled and getConnection(user, password) is called.

The exact definition of oracle-proxy-session is as follows:

  • If proxy authentication is enabled and identity based pooling is also enabled, it is an error.

  • If a user is specified on getConnection() and identity-based-connection-pooling-enabled is false, then oracle-proxy-session is treated as true implicitly (it can also be explicitly true).

  • If a user is specified on getConnection() and identity-based-connection-pooling-enabled is true, then oracle-proxy-session is treated as false.

Identity-based Connection Pooling

An identity based pool creates a heterogeneous pool of connections. This allows applications to use a JDBC connection with a specific DBMS credential by pooling physical connections with different DBMS credentials. The DBMS credential is based on either the WebLogic user mapped to a database user or the database user directly, based on the use-database-credentials. use-database-credentials=true is how some implementations interpret the JDBC standard—basically a heterogeneous pool with users specified by getConnection(user,password).

The allocation of connections is more complex if Enable Identity Based Connection Pooling attribute is enabled on the data source. When an application requests a database connection, the WebLogic Server instance selects an existing physical connection or creates a new physical connection with requested DBMS identity.

The following section provides information on how heterogeneous connections are created:

  1. At connection pool initialization, the physical JDBC connections based on the configured or default ”initial capacity” are created with the configured default DBMS credential of the data source.

  2. An application tries to get a connection from a data source.

  3. If:

    • use-database-credentials is not enabled, the user specified in getConnection is mapped to a DBMS credential, as described earlier. If the credential map doesn't have a matching user, the default DBMS credential is used from the data source descriptor.

    • use-database-credentials is enabled, the user and password specified in getConnection are used directly.

  4. The connection pool is searched for a connection with a matching DBMS credential.

  5. If a match is found, the connection is reserved and returned to the application.

  6. If no match is found, a connection is created or reused based on the maximum capacity of the pool:

    • If the maximum capacity has not been reached, a new connection is created with the DBMS credential, reserved, and returned to the application.

    • If the pool has reached maximum capacity, based on the least recently used (LRU) algorithm, a physical connection is selected from the pool and destroyed. A new connection is created with the DBMS credential, reserved, and returned to the application.

It should be clear that finding a matching connection is more expensive than a homogeneous pool. Destroying a connection and getting a new one is very expensive. If possible, use a normal homogeneous pool or one of the light-weight options (client identity or an Oracle proxy connection) as they are more efficient than identity-based pooling.

Regardless of how physical connections are created, each physical connection in the pool has its own DBMS credential information maintained by the pool. Once a physical connection is reserved by the pool, it does not change its DBMS credential even if the current thread changes its WebLogic user credential and continues to use the same connection.

To configure this feature, select Enable Identity Based Connection Pooling. See "Enable identity-based connection pooling for a JDBC data source" in Oracle WebLogic Server Administration Console Online Help.

You must make the following changes to use Logging Last Resource (LLR) transaction optimization with Identity-based Pooling to get around the problem that multiple users access the associated transaction table:

  • You must configure a custom schema for LLR using a fully qualified LLR table name. All LLR connections will then use the named schema rather than the default schema when accessing the LLR transaction table.

  • Use database specific administration tools to grant permission to access the named LLR table to all users that could access this table via a global transaction. By default, the LLR table is created during boot by the user configured for the connection in the data source. In most cases, the database will only allow access to this user and not allow access to mapped users.

Connections within Transactions

Connections associated with a transaction context on a particular WebLogic Server instance have the following behaviors:

  • When getting a connection with a data source configured with non-XA LLR or 1PC (JTS driver) with global transactions, the first connection obtained within the transaction is returned on subsequent connection requests regardless of the values of username/password specified and independent of the associated proxy user session, if any. The connection must be shared among all users of the connection when using LLR or 1PC.

  • For XA data sources, the first connection obtained within the global transaction is returned on subsequent connection requests within the application server, regardless of the values of username/password specified and independent of the associated proxy user session, if any. The connection must be shared among all users of the connection within a global transaction within the application server/JVM.

In summary, when you get a connection within a transaction, it is associated with the transaction context on a particular WebLogic Server instance.

WebLogic Data Source Resource Permissions

You can optionally restrict access to JDBC data sources. In WebLogic Server, security policies answer the question "who has access" to a WebLogic data source resource. A security policy is created when you define an association between a WebLogic data source resource and a user, group, or role. A WebLogic data source resource has no protection until you assign it a security policy. As soon as you add one policy for a permission, then all other users are restricted. For example, if you add a policy so that weblogic can reserve a connection, then all other users fail to reserve connections unless they are also explicitly added. The validation is done for WebLogic user credentials, not database user credentials. See ”Create policies for resource instances” in Oracle WebLogic Server Administration Console Online Help.

You can protect JDBC resource operations by assigning Administrator methods which can limit the actions that an administrator may take upon a JDBC data source. These resources can be defined on the Policies tab on the Security tab associated with the data source. When you secure an individual data source, you can choose whether to protect JDBC operations using one or more of the following administrator methods:

  • admin—The following methods on the JDBCDataSourceRuntimeMBean are invoked as admin operations: clearStatementCache, suspend, forceSuspend, resume, shutdown, forceShutdown, start, getProperties, and poolExists.

  • reserve—Applications reserve a connection in the data source by looking up the data source and then calling getConnection. Giving a user the reserve permission enables them to execute vendor-specific operations. Depending on the database vendor, some of these operations may have database security implications. See WebLogic Data Source Security Options.

  • shrink—Shrinks the number of connections in the data source to the maximum of the currently reserved connections or to the initial size.

  • reset—Resets the data source connections by shutting down and re-establishing all physical database connections. This also clears the statement cache for each connection. You can only reset data source connections that are running normally.

  • All—An individual data source is protected by the union of the Admin, reserve, shrink, and reset administrator methods.


    Be aware of the following:
    • If a security policy controls access to connections in a multi data source, access checks are performed at both levels of the JDBC resource hierarchy (once at the multi data source level, and again at the individual data source level). As with all types of WebLogic resources, this double-checking ensures that the most specific security policy controls access.

See "Java DataBase Connectivity (JDBC) Resources" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

The following table provides information on the user for permission checking when using the administrator method reserve:

Table 10-2 Determining the User when using the reserve Administration Method

API Use-database-credential User for permission checking


True or False

Current WebLogic user



User/password from API



Current WebLogic user

In summary, if a simple getConnection() is used or database credentials are enabled, the current user that is authenticated to the WebLogic system is checked. If database credentials are not enabled, then the user and password on the API are used. This feature is very useful to restrict what code and users can access your database.

For instructions on how to set up security for all WebLogic Server resources, see "Use roles and policies to secure resources" in Oracle WebLogic Server Administration Console Online Help. For more information about securing server resources, see Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Data Source Security Example

The following is an actual example of the interactions between identity-based-connection-pooling-enabled, oracle-proxy-session, and use-database-credentials.

On the database side, the following objects are configured:

  • users: scott; jdbcqa; jdbcqa3

  • alter user jdbcqa3 grant connect through jdbcqa;

  • alter user jdbcqa grant connect through jdbcqa;

The following WebLogic users are configured:

  • weblogic

  • wluser

The following WebLogic datasource objects are configured.

  • Credential mapping weblogic to scott

  • Credential mapping wluser to jdbcqa3

  • Datasource configured with user jdbcqa

  • All tests run with Set Client ID set to true.

  • All tests run with oracle-proxy-session set to false.

The test program:

  • Runs in servlet

  • Authenticates to WebLogic as user weblogic

Table 10-3 Comparing Identity, Proxy, and Database Credentials

Use DB Credentials Identity based getConnection (scott,***) getConnection (weblogic,***) getConnection (jdbcqa3,***) getConnection()



Identity scott

Client weblogic

Proxy null

weblogic fails – not a db user

User jdbcqa3

Client weblogic

Proxy null

Default jdbcqa

Client weblogic

Proxy null



scott fails – not a WebLogic user

User scott

Client scott

Proxy null

jdbcqa3 fails – not a WebLogic user

User scott

Client scott

Proxy null



Proxy for scott failed

weblogic fails – not a db user

User jdbcqa3

Client weblogic

Proxy jdbcqa

Default jdbcqa

Client weblogic

Proxy null



scott fails – not a WebLogic user

User jdbcqa

Client scott

Proxy null

jdbcqa3 fails – not a WebLogic user

Default jdbcqa

Client scott

Proxy null


  • Set Client ID is set to false, all cases would have Client set to null.

  • The Oracle thin driver is not used, the one case with the non-null Proxy would throw an exception because proxy session is only supported with the Oracle thin driver.

When oracle-proxy-session is set to true, the only cases that pass (with a proxy of jdbcqa) are:

  • Setting use-database-credentials to true and using getConnection(jdbcqa3,…) or getConnection().

  • Setting use-database-credentials is false and using getConnection(wluser, …) or getConnection().

Using SSL with Data Sources and Oracle Drivers

This section provides additional information on a variety of options that use SSL with data sources and Oracle drivers.

The general requirement when using SSL, regardless of the option, is that you must specify a protocol of tcps in any url.

For detailed information on configuring and using SSL with Oracle drivers, see:

Using SSL with Oracle Wallet

Oracle wallet can also be used with SSL. By using it correctly, clear text passwords can be eliminated from the JDBC configuration and client/server configuration can be simplified by sharing the wallet). The following is a list of basic requirements to use SSL with Oracle wallet.

  • Update the sqlnet.ora and listener.ora files with the location of the wallet. These files also indicate whether or not SSL_CLIENT_AUTHENTICATION is being used.

  • Oracle recommends using the auto-login wallet type so that clear text passwords are not needed in the datasource configuration to open the wallet. The store type for an auto-login wallet is SSO (not JKS or PKCS12) and the file name is cwallet.sso.

  • You must enable the Oracle PKI provider. This can either be done statically by updating the java.security file under the JRE or dynamically by setting it in a WLS startup class using:

    Security.insertProviderAt(new oracle.security.pki.OraclePKIProvider (), 3);
  • For encryption and server authentication, use the datasource connection properties:

    javax.net.ssl.trustStore=location of wallet 
  • For client authentication, use the datasource connection properties:

    javax.net.ssl.keyStore=location of wallet
  • Wallets are created using the orapki. They need to be created based on the usage (encryption or authentication).

Common use cases are:

  • Encryption and server authentication, which requires just a trust store.

  • Encryption and authentication of both tiers (client and server), which requires a trust store and a key store.

Active GridLink ONS over SSL

You can use SSL to secure communication between an Active GridLink (AGL) data source and the Oracle Notification Service (ONS) which is use to provide load balancing information and notification of node up/down events.

Use the following basic steps:

  • Create an auto-login wallet and use the wallet on the client and server. The following is a sample sequence to create a test wallet for use with ONS.

    orapki wallet create -wallet ons -auto_login -pwd ONS_Wallet
    orapki wallet export -wallet ons -dn "CN=ons_test,C=US" -cert ons/cert.txt -pwd ONS_Wallet
    orapki wallet export -wallet ons -dn "CN=ons_test,C=US" -cert ons/cert.txt -pwd ONS_Wallet
  • On the database server side:

    1. Define the wallet file directory in the file $CRS_HOME/opmn/conf/ons.config.

    2. Run onsctl stop/start

  • When configuring an AGL datasource, the connection to the ONS must be defined. In addition to the host and port, the wallet file directory must be specified. If you do not provide a password, a SSO wallet is assumed.