The chapter includes the following sections:
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 (seeCreating 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 WebLogic Server Administration Console. The
Password fields are located on the WebLogic Server 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.
The following table describes the various features available for WebLogic data sources to configure database security credentials.
Table 13-1 WebLogic Data Source Configuration Options for Security Credentials
|Feature||Description||Can be used with . . .||Can't be used with . . .|
Proxy session, 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
Set Client Identifier
Set a client identifier property associated with the connection (Oracle and DB2 only).
Set a light-weight proxy user associated with the connection (Oracle-only).
User authentication, Set client identifier, Use database credentials
Heterogeneous pool of connections owned by specified users.
Set client identifier, Use database credentials
Proxy session, User authentication, Labeling, Active GridLink
Note: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 WebLogic Server Administration Console. See "JDBC Data Source: Configuration: Identity Option" in Oracle WebLogic Server Administration Console Online Help.
Note: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:
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:
Create a WebLogic user. In the WebLogic Server Administration Console, go to Security realms, select your realm (for example, myrealm), select Users, and select New.
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
) 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
) 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
true. See "Configure Oracle parameters" in Oracle WebLogic Server Administration Console Online Help.
use-database-credentials is enabled, it turns of credential mapping for the following attributes:
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.
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 WebLogic Server 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
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
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
Use the following steps to configure proxy authentication on a connection to an Oracle database.
If you have not yet done so, create the necessary database users.
On the Oracle database, provide CONNECT THROUGH privileges. For example:
SQL> ALTER USER connectionuser GRANT CONNECT THROUGH dbuser;
connectionuser is the name of the application user to be authenticated and
dbuser is an Oracle database user.
Create a generic or Active GridLink data source and set the user to the value of dbuser.
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
Enable Oracle Proxy Authentication, see "Configure Oracle parameters" in Oracle WebLogic Server Administration Console Help.
Log on to a WebLogic Server instance using the value of
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
oracle-proxy-session is treated as
true implicitly (it can also be explicitly
If a user is specified on
oracle-proxy-session is treated as
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=true is how some implementations interpret the JDBC standard—basically a heterogeneous pool with users specified by
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:
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.
An application tries to get a connection from a data source.
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.
The connection pool is searched for a connection with a matching DBMS credential.
If a match is found, the connection is reserved and returned to the application.
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 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.
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
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
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
Table 13-2 Determining the User when using the reserve Administration Method
|API||Use-database-credential||User for permission checking|
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.
The following is an actual example of the interactions between
On the database side, the following objects are configured:
alter user jdbcqa3 grant connect through jdbcqa;
alter user jdbcqa grant connect through jdbcqa;
The following WebLogic users are configured:
The following WebLogic datasource objects are configured.
Datasource configured with user
All tests run with
Set Client ID set to
All tests run with
oracle-proxy-session set to
The test program:
Runs in servlet
Authenticates to WebLogic as user
Table 13-3 Comparing Identity, Proxy, and Database Credentials
|Use DB Credentials||Identity based||getConnection (scott,***)||getConnection (weblogic,***)||getConnection (jdbcqa3,***)||getConnection()|
Set Client ID is set to
false, all cases would have
Client set to
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.
oracle-proxy-session is set to
true, the only cases that pass (with a proxy of
true and using
false and using
getConnection(wluser, …) or
As part of a secure configuration, it may be necessary to provide one or more connection property values that should not appear as clear text in the connection properties of the data source descriptor file. These properties can be added using the
Encrypted Properties attribute. See "Encrypt connection properties" in Oracle WebLogic Server Administration Console Online Help.
You cannot encrypt connection properties when creating a data source in the WebLogic Server Administration Console. It can only be done when updating an existing data source configuration.
The following section provides information on best practices and tips when encrypting connection properties in the WebLogic Server Administration Console:
When creating a data source:
Create it without the encrypted property and do not target the data source.
It may not be possible to test the connection without the encrypted property. You might want to temporarily test with a clear text property, then replace the clear text property with the encrypted property later.
Edit the data source by going to Summary of JDBC Data Sources page, select the Data Source, go to the Configuration tab and then select the Connection Pool tab.
To enter values without clear text values displayed on the screen:
Save any other changes that you wish to make to this page and click the Add Securely button next to the Encrypted Properties text box.
On the Add a new Encrypted Property page, enter the property name and masked value, and click OK.
Repeat for additional encrypted property values.
Click Save when you have finished entering encrypted properties.
You can enter several values at once if it is appropriate in your environment to display the encrypted values on the screen until the changes are saved.
property=value pair on a separate line in the Encrypted Properties field.
Click Save to encrypt the values.
Activate your changes:
If the data source was untargeted: Go to the Targets tab, target the data source, and click Save.
If the data source was already active when the encrypted property values were added: Go to the Targets tab, untarget the data source, click Save, retarget the data source, and click Save.
The following sections provide examples of WLST scripts that encrypt connection properties:
The following is an online WLST script shows how to add an encrypted property to an existing data source named genericds.
connect('admin','password','t3://localhost:7001') edit() startEdit() cd('JDBCSystemResources/genericds/JDBCResource/genericds/JDBCDriverParams/genericds/Properties/genericds/Properties') create('encryptedprop','Property') cd('encryptedprop') cmo. setEncryptedValueEncrypted(encrypt('foo')) save() activate()
The following WLST script creates encrypted properties:
. . . create('myProps','Properties') cd('Properties/NO_NAME_0') . . . # Create other properties . . . p=create('javax.net.ssl.trustStoreType', 'Property') p.setValue('JKS') p=create('javax.net.ssl.trustStorePassword', 'Property') p.setEncryptedValueEncrypted(encrypt('securityCommonTrustKeyStorePassPhrase')) . . .
Oracle Advanced Security provides both data encryption and strong authentication for network connections to the database server. The following sections provide additional information on using these features with WebLogic Server.
For more information, see "JDBC Client-Side Security Features" in the Oracle® Database JDBC Developer's Guide.
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:
If you use a provider that requires a password, such as the
javax.net.ssl.keyStorePassword, the value should be stored as an encrypted property. See Using Encrypted Connection Properties.
Oracle wallet can also be used with SSL. By using it correctly, 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.
listener.ora files with the location of the wallet. These files also indicate whether or not
SSL_CLIENT_AUTHENTICATION is being used.
If you use an auto-login wallet type, a password is not needed in the data source 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. If you use another provider type, use the encrypted property type to store the password as an encrypted value in the data source configuration.
Enable the Oracle PKI provider 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 javax.net.ssl.trustStoreType="SSO"
For client authentication, use the datasource connection properties:
javax.net.ssl.keyStore=location of wallet javax.net.ssl.keyStoreType="SSO"
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.
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:
Define the wallet file directory in the file
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.
To use data encryption with the Oracle Thin driver, you must specify several connection properties, see "Configuration Parameters" in Oracle® Database Advanced Security Administrator's Guide. The following table maps the encryption and checksum configuration parameters to the string constants required when configuring data source descriptors using the Administration Console or WLST:
Table 13-4 Connection Encryption Parameters and WebLogic Configuration Constants
|Client Configuration Parameter||WebLogic Server Configuration String Constant|