Friday Aug 03, 2012

WebLogic JDBC Use of Oracle Wallet and tnsnames.ora


This entry describes using the Oracle wallet to store database credentials for WebLogic Server datasource definition.  The advantage of this feature is to be able to easily manage changes to database credentials when necessary by simply updating the wallet instead of having to change potentially many datasource definitions.  This feature can be taken a step further by also using the Oracle TNS (Transparent Network Substrate) administrative file to hide the details of the database connection string (host name, port number, and service name) from the datasource definition and instead use an alias.  If the connection information changes, it is simply a matter of changing the tnsnames.ora file instead of potentially many datasource definitions.  By using this approach, it removes the encrypted password from the datasource descriptor so that it is portable across domains and the same wallet and tnsnames.ora can be shared across multiple domains.  Finaly, there is no need for WebLogic users to manage the database information like clear text password and host/port/service - it's all hidden in the Oracle files.

Creating and Managing an Oracle Wallet

The easiest way to do this is to create and manage the wallet in a database environment - that way, the necessary commands and libraries will be available.  In particular, it's necessary to have access to the $ORACLE_HOME/bin/mkstore command.  It's also available by installing the Oracle Client Runtime package.   Often this task will be completed by a database administrator and provided for use by the client.  The "wallet" consists of two files in a wallet directory: cwallet.sso  and ewallet.p12

Create a wallet by using the following syntax at the command line:

mkstore -wrl <wallet_location> -create

where wallet_location is the path to the directory where you want to create and store the wallet. This command creates an Oracle wallet with the autologin feature enabled at the location you specify. The autologin feature enables the client to access the wallet contents without supplying a password.  You want to use an autologin wallet so that you don't need to expose the clear text password on the client.

This command will prompt for a password that is used for subsequent commands.  Passwords must have a minimum length of eight characters and contain alphabetic characters combined with numbers or special characters.  Note that using the wallet moves the security vulnerability from a clear text password in the configuration file to an encrypted password in the wallet file so make sure that the wallet file is protected.

You can store multiple credentials for multiple databases in one client wallet. You cannot store multiple credentials (for logging in to multiple schemas) for the same database in the same wallet. If you have multiple login credentials for the same database, then they must be stored in separate wallets.
To add database login credentials to an existing client wallet, enter the following command at the command line:

mkstore -wrl <wallet_location> -createCredential <db_connect_string> <username> <password> 

The wallet_location is the path to the directory where you created the wallet.
The db_connect_string must be identical to the connection string that you specify in the URL used in the datasource definition (the part of the string that follows the "@").  It can be either the short form or the long form of the URL.  For example,




You should enclose this value in quotation marks to escape any special characters from the shell.  Since this name is generally a long and complex value, an alternative is to use TNS aliases (see below). 
The username and password are the database login credentials.
Repeat this step for each database you want to use in a WebLogic datasource.

Refer to for more information about managing wallets.

Defining a WebLogic Server Datasource using the Wallet

There are two steps to set up to be able to use the wallet with WebLogic Server.

  1. Copy the wallet from the database machine to the client machine and locate it in a secure directory.  The "wallet" consists of two files in a wallet directory: cwallet.sso  and ewallet.p12.
  2. Update the WebLogic Server CLASSPATH to have three additional security files.
    The files that need to be added to the WLS CLASSPATH are $MW_HOME/modules/ $MW_HOME/modules/
    $MW_HOME/modules/ (if they are not in your WebLogic Server distribution, they will be in the Oracle client installation).  One way to do this is to add them to PRE_CLASSPATH environment variable for use with the standard WebLogic scripts.

When creating the WebLogic datasource, there are three additional steps.

  1. Do not enter a user or password in administration console when creating a datasource (or delete them for an existing datasource).  It's critical to not have a user or password or encrypted password in the configuration because these will take precedence over the Oracle wallet values.
  2. Modify the URL so that there is a "/" before the "@" (e.g., the short form of the URL should look like "jdbc:oracle:thin:/@myhost:1521/myservice").
  3. The following value must be added to the connection properties: Alternatively, you can use the system property (e.g., add it to JAVA_OPTIONS).

Using a TNS Alias instead of a DB Connect String

Instead of specifying a matching database connection string in the URL and in the Oracle wallet, it's possible to use an alias for this information.  This approach is much cleaner. The connection string information is stored in tnsnames.ora with an associated alias name.  The alias name is used both in the URL and the wallet.  

  1. Specify the system property<tns_directory> with the location of a tnsnames.ora file (this cannot be specified as a connection property).
  2. Create or modify a file named "tnsnames.ora" in the tns_directory.  The entry has the form alias=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=host)(PORT=port))(CONNECT_DATA=(SERVICE_NAME=service))) There are additional attributes that can be configured (see
  3. Use the alias in the datasource definition URL by replacing the connection string with the alias.  For example, change the URL in the administrative console to "jdbc:oracle:thin:/@alias".

Once this is set up, it should not be necessary to change the alias or the datasource definition again.  To change the user credential, modify the wallet.  To change the connection information, change the tnsnames.ora file.  In either case, the datasource must be re-deployed; the easiest way to do this is to un-target and re-target the datasource in the WebLogic administrative console.

The system properties and are available starting with the 10.2 driver.


The official blog for Oracle WebLogic Server fans and followers!

Stay Connected


« July 2016