Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

  • August 3, 2012

WebLogic JDBC Use of Oracle Wallet and tnsnames.ora

Stephen Felts


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 http://docs.oracle.com/cd/B28359_01/network.111/b28530/asowalet.htm 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/com.oracle.osdt_cert_1.0.0.0.jar $MW_HOME/modules/com.oracle.osdt_core_1.0.0.0.jar
    $MW_HOME/modules/com.oracle.oraclepki_1.0.0.0.jar (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: oracle.net.wallet_location=wallet_directory Alternatively, you can use the -Doracle.net.wallet_location 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 -Doracle.net.tns_admin=<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 http://docs.oracle.com/cd/B13789_01/network.101/b10776/tnsnames.htm).
  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 oracle.net.tns_admin and oracle.net.wallet_location are available starting with the 10.2 driver.

Join the discussion

Comments ( 5 )
  • guest Friday, August 3, 2012

    An interesting post Steve. It's not something I've tried before (or even knew you could do!) - what worries me is that the extra obfuscation might actually hinder a middleware administrator rather than help them. Plus I usually create data sources with WLST so whether I have a few or many it doesn't really matter. As you say you need to protect the wallet very carefully too. Perhaps I'm thinking about environments that aren't all that complex though - I wonder did you have a specific use-case in mind?

  • Steve Saturday, August 4, 2012

    The WebLogic Server (WLS) datasource team has seen multiple customer requests to simplify configuration when using an Oracle database and use of the wallet is popular. There is some good documentation about using the wallet but it is spread out so it took me a few hours to come up with a recipe for doing this with WLS.

    I included some of the motivation at the beginning of the article but let me take a different approach, focusing on roles.

    The key player is the Oracle DBA. He already has to deal with tnsnames.ora. Creating a wallet is simple and it's desirable to not hand out a clear text password. I talked with one DBA who told me that he hated to give out connection information (host/port/service) that then gets embedded in various proprietary configuration files for every product and sometimes descriptors in an EJB or WAR, making it very difficult to make subsequent changes. Using an alias with tnsnames.ora and the Oracle wallet involves simply replacing a couple of files on every computer that references the centralized database.

    Note that it should be possible to use this technique with any product that uses the Oracle thin driver.

    The other key player is the WLS administrator. Typing in an alias name is simpler than dealing with a full URL, especially the new long form syntax and dropping in two files is arguably easier to manage the update (assuming it’s not embedded in an EAR, you use WLST or the administration console or vi). Having a password that is encrypted specific to the domain is a pain for everyone – the descriptor can’t be copied to another domain and deployed. The goal is to get an external password store that can be shared across various domains – not just multiple WLS domains, but database and other applications. The wallet is one way to do that. The wallet can also be used for a trust store and key store for SSL (more about that in another article).

    Although the article correctly implies that you can use the wallet without tnsnames.ora, the clear benefit is to use both together. It’s a bigger benefit for larger organizations with lots of databases and/or lots of references to centralized databases.

  • Simon Haslam Saturday, August 4, 2012

    Thanks for the clarification Steve. I hadn't thought about SSL - if you use a wallet that instead of JKS (plus you may have wallets for OHS anyway) I can see the sense in trying to standardise on one configuration method.


  • Serge P. Friday, August 10, 2012

    Thanks for this interesting post Steve, it was missing : I have tested myself such a configuration earlier this year and I found no valuable information on the Internet. Eventually I managed to get this working by adapting the example found in the Thin Driver documentation.

    By the way I noticed the following :

    - you can really create the wallet with only the WebLogic 11g environment as the needed jars are present, mkstore can be replaced by "java oracle.security.pki.OracleSecretStoreTextUI" (the 3 jars you mentioned in $MW_HOME/modules must be added to the classpath)

    - apparently the URL is working even if a "/" is not added before the "@"


  • vinothbabu Tuesday, December 11, 2012

    Hi Steve,

    If we configure the wallet file configuration in weblogic server we are facing the below error message.

    ORA-01017: invalid username/password; logon denied <br/>oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:440)<br/>oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:389)<br/>oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:382)<br/>oracle.jdbc.driver.T4CTTIfun.processError(T4CTTIfun.java:573)<br/>oracle.jdbc.driver.T4CTTIoauthenticate.proces

    localhost:/u01/app/oracle/product/11.2.0/dbhome_1/bin/mkstore -wrl /var/tmp/wallet/ -create

    -rw------- 1 root root 3589 Dec 11 20:06 cwallet.sso

    -rw------- 1 root root 3512 Dec 11 20:06 ewallet.p12

    localhost:/u01/app/oracle/product/11.2.0/dbhome_1/bin/mkstore -wrl /var/tmp/wallet/ -createCredential localhost:1521/testdb test test_123

    we copy the wallet file into weblogic domain security directory

    localhost:/lapps/oracle/wls1034/domains/testdomain/security # ls -rlt

    total 48

    -rwxr-x--- 1 weblogic www 64 Mar 30 2012 SerializedSystemIni.dat

    -rwxr-x--- 1 weblogic www 4126 Mar 30 2012 DefaultAuthenticatorInit.ldift

    -rwxr-x--- 1 weblogic www 22654 Mar 30 2012 XACMLRoleMapperInit.ldift

    -rwxr-x--- 1 weblogic www 2398 Mar 30 2012 DefaultRoleMapperInit.ldift

    -rwxr-x--- 1 weblogic www 3896 Dec 11 20:14 ewallet.p12

    -rwxr-x--- 1 weblogic www 3973 Dec 11 20:14 cwallet.sso

    localhost:/lapps/oracle/wls1034/domains/testdomain/lib # ls -rlt

    total 2764

    -rwxr-x--- 1 weblogic www 261716 Mar 30 2012 com.oracle.osdt_core_1.0.0.0.jar

    -rwxr-x--- 1 weblogic www 169974 Mar 30 2012 com.oracle.osdt_cert_1.0.0.0.jar

    -rwxr-x--- 1 weblogic www 214202 Mar 30 2012 com.oracle.oraclepki_1.0.0.0.jar

    -rwxr-xr-x 1 weblogic www 2158945 Mar 30 2012 ojdbc6.jar

    Weblogic datasource configuration steps:-

    Driver Class Name: oracle.jdbc.OracleDriver

    URL: jdbc:oracle:thin:/@localhost:1521/testdb

    Properties: oracle.net.wallet_location=/lapps/oracle/wls1034/domains/empkg-domain/security

    System Properties: -Doracle.net.wallet_location=/lapps/oracle/wls1034/domains/empkg-domain/security/cwallet.sso

    How to resolve the issue in weblogic datasource configuration.

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.