11 Creating and Managing Oracle Wallet

This chapter describes how to create and manage an Oracle Wallet to store database credentials for WebLogic Server datasource definitions.

What is Oracle Wallet

Oracle Wallet provides an simple and easy method to manage database credentials across multiple domains. It allows you to update database credentials by updating the Wallet instead of having to change individual datasource definitions. This is accomplished by using a database connection string in the datasource definition that is resolved by an entry in the wallet.

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.

The wallet can be used to have common credentials between different domains. That includes two different WLS domains or sharing credentials between WLS and the database. When used correctly, it makes having passwords in the datasource configuration unnecessary.

Where to Keep Your Wallet

Oracle recommends that you create and manage the Wallet in a database environment. This environment provides all the necessary commands and libraries, including the $ORACLE_HOME/oracle_common/bin/mkstore command. Often this task is completed by a database administrator and provided for use by the client. A configured Wallet consists of two files, cwallet.sso and ewallet.p12 stored in a secure Wallet directory

Note:

You can also install the Oracle Client Runtime package to provide the necessary commands and libraries to create and manage Oracle Wallet.

How to Create an External Password Store

Create a wallet on the client 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 specified. Autologin enables the client to access the Wallet contents without supplying a password and prevents exposing a clear text password on the client.

The mkstore command prompts 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. For example:

mkstore -wrl /tmp/wallet –create 
Enter password: mysecret 
PKI-01002: Invalid password. 
Enter password: mysecret1  (not echoed) 
Enter password again: mysecret1 (not echoed)

Note:

Using Oracle Wallet moves the security vulnerability from a clear text password in the datasource configuration file to an encrypted password in the Wallet file. Make sure the Wallet file is stored in a secure location.

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>

where:

  • 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:

    myhost:1521/myservice or

    (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=myhost-scan)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=myservice)))

    Note:

    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 Using a TNS Alias instead of a DB Connect String.

  • The username and password are the database login credentials.

  • Repeat for each database you want to use in a WebLogic datasource.

See the Oracle Database Advanced Security Administrator's Guide for more information about using autologin and maintaining Wallet passwords.

Defining a WebLogic Server Datasource using the Wallet

Use the following procedures to configure a WebLogic Server datasource to use Oracle Wallet:

Copy the Wallet Files

Copy the Wallet files, cwallet.sso and ewallet.p12, from the database machine to the client machine and locate it in a secure directory.

Update the Datasource Configuration

Use the following steps to configure a WebLogic datasource to use Oracle Wallet:

  1. Do not enter a user or password in the Administration Console when creating a datasource or delete them from an existing datasource. If a user, password, or encrypted password appear in the configuration, they override the Oracle wallet values.

  2. Modify the URL so that there is a ”/” before the ”@”. For example: the short form of the URL should look like jdbc:oracle:thin:/@mydburl:1234/mydb).

  3. The following value must be added to Connection Properties:

    oracle.net.wallet_location=wallet_directory

    where wallet_directory is the secure directory location in Step 1 of Copy the Wallet Files. An alternative method is use the -Doracle.net.wallet_location system property and add it to JAVA_OPTIONS. Oracle recommends using the connection property.

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, you can create an alias to map the URL information. The connection string information is stored in tnsnames.ora file with an associated alias name. The alias name is then used both in the URL and the Wallet.

  1. Specify the system property -Doracle.net.tns_admin=tns_directory where tns_directory is the directory location of the tnsnames.ora file.

    Note:

    Do not use the tns_directory location as a connection property.

  2. Create or modify a tnsnames.ora file in the directory location specified by tns_directory. The entry has the form:

    alias=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=host)(PORT=port))(CONNECT_DATA=(SERVICE_NAME=service)))

    Where host is URL of a database listener, port is the port a database listener, and service is the service name of the database you would like to connect to.

    There are additional attributes that can be configured, see "Local Naming Parameters (tnsnames.ora)" in the Database Net Services Reference. Oracle recommends that the string be entered on a single line.

  3. Use the alias in the datasource definition URL by replacing the connection string with the alias. For example, change the URL attribute in the Connection Pool tab of the Administrative Console to jdbc:oracle:thin:/@alias.

Once created, it should not be necessary to modify the alias or the datasource definition again. To change the user credential, update the Wallet. To change the connection information, update the tnsnames.ora file. In either case, the datasource must be re-deployed. The simplest way to redeploy a datasource is to untarget and target the datasource in the Administration Console. This configuration is supported for Oracle release 10.2 and higher drivers.