11 Managing the Credential Store

A credential can hold user names, passwords, and tickets; credentials can be encrypted. Credentials are used during authentication, when principals are populated in subjects, and, further, during authorization, when determining what actions the subject can perform.

Oracle Platform Security Services includes the Credential Store Framework (CSF), a set of APIs that applications can use to create, read, update, and manage credentials securely. A typical use of the credential store is to store user names and passwords to access some external system, such as a database or an LDAP-based repository.

This chapter is divided into the following sections:

11.1 Credential Types

OPSS supports the following types of credentials according to the data they contain:

  • A password credential encapsulates a user name and a password.

  • A generic credential encapsulates any customized data or arbitrary token, such as a symmetric key.

A credential is uniquely identified by a map name and a key name. A map can hold several keys and, typically, the map name corresponds with the name of an application; all credentials with the same map name define a logical group of credentials, such as the credentials used by the application. The pair of map and key names must be unique for all entries in a credential store.

There is no limit to the number or kind of characters you can set in a password, except that it must be non-empty and non-null.

Oracle Wallet is the default file-based credential store, and it can store X.509 certificates; production environments typically use either an Oracle Internet Directory LDAP-based or a DB-based credential store.

11.2 Encrypting Credentials

OPSS supports storing encrypted data in file- and LDAP-based credential stores. OPSS uses an encryption key to encrypt and decrypt data when it is read from or written to the credential store. This key has domain scope, that is, there is exactly on (current) key per domain. To enable the encryption of credentials in a file- or LDAP-based store, set the following property in the credential store service instance of the file jps-config.xml:

<property name="encrypt" value="true" />

In case of DB-based credential stores, data is always encrypted using a client-side key.

The Domain Encryption Key

When the property encrypt is set to true, OPSS uses an encryption key to encrypt new credentials entered in the credential store. This encryption key is a 128-bit AES key randomly generated when the domain is started for the very first time and is valid for the entire domain; eventually, the domain encryption key may require being rolled over periodically; rolling over a key generates a new key and archives the previous one; archived keys are used to decrypt old data, and the new key is used to encrypt and decrypt new data.

When a new domain encryption key is produced, data in the credential store is not immediately re-encrypted with the new key. Instead, data is encrypted (with the new key) only when it is written. This implies that to get all data to use the same encryption key, all credentials must be read and written.

Domains Sharing a Credential Store

If two or more domains share a credential store and encryption is enabled in that store, then each of those domains must use the same encryption key. To ensure this, OPSS provides offline scripts to export, import, and restore keys in the domain bootstrap wallet, so that an encryption key generated in one domain can be carried over to all other domains sharing the credential store. For details about these commands, see Managing Credentials with WLST commands.

The following scenarios illustrate how to set credential encryption in a cluster of two domains, Domain1 and Domain2. (In case of more than two domains, treat each additional domain as Domain2 in the illustration below.)

Note:

The following scenarios assume that the credential store is LDAP-based, but the use of importEncryptionKey and exportEncryptionKey to import and export keys across domains applies also to DB-based credential stores (in which data is always encrypted).

First Scenario

Assume that Domain1 has reassociated to an LDAP-based credential store, and Domain2 has not yet joined to that store. Then, to enable credential encryption on that store, proceed as follows:

  1. Set the property encrypt to true in Domain1's jps-config.xml file and restart the domain.

  2. Use the WLST command exportEncryptionKey to extract the key from Domain1 into the file ewallet.p12; note that the value of the argument keyFilePassword passed to the script must be used later when importing that key into another domain.

  3. Set the property encrypt to true in Domain2's jps-config.xml file.

At this point you can complete the procedure in one of two ways; both of them use the WLST command reassociateSecurityStore, but with different syntaxes. For details about this script, see Section 10.4.1, "reassociateSecurityStore."

The first approach is as follows:

  1. Use the WLST command reassociateSecurityStore to reassociate Domain2's credential store to that used by Domain1; use the argument join and do not use the arguments keyFilePassword and keyFilePath.

  2. Use the WLST command importEncryptionKey to import the extracted ewallet.p12 into Domain2; note that the value of the argument keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.

  3. Restart Domain2's server.

The second approach is as follows:

  1. Use the WLST command reassociateSecurityStore to reassociate Domain2's credential store to that used by Domain1; use the arguments join, keyFilePassword, and keyFilePath.

  2. Restart Domain2's server.

Second Scenario

Assume that Domain1 has reassociated to an LDAP-based credential store and Domain2 has already joined to that store. Then, to enable credential encryption on that store, proceed as follows:

  1. Set the property encrypt to true in Domain1's jps-config.xml file and restart the domain.

  2. Use the WLST command exportEncryptionKey to extract the key from Domain1 into the file ewallet.p12; note that the value of the argument keyFilePassword passed to the script must be used later when importing that key into another domain.

  3. Set the property encrypt to true in Domain2's jps-config.xml file.

  4. Use the WLST command importEncryptionKey to write the extracted ewallet.p12 into Domain2; note that the value of the argument keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.

  5. Restart Domain2's server.

Important Note:

In case of multiple domains sharing a credential store in which encryption has been enabled, every time a roll-over key is generated in one of those domains, the administrator must import that key to each of the other domains in the cluster using the WLST commands exportEncryptionKey and importEncryptionKey.

11.3 Managing Credentials with Fusion Middleware Control

The following procedure explains how to use Fusion Middleware Control to manage credentials. For procedures to manage other service providers, see Section 9.7, "Configuring Services Providers with Fusion Middleware Control."

  1. Log in to Fusion Middleware Control and navigate to Domain > Security > Credentials to display the Credentials page partially illustrated in the following graphic:

    credential store page

    The area Credential Store Provider is read-only; when expanded, it displays the credential store provider currently in use in the domain.

  2. To display credentials matching a given key name, enter the string to match in the Credential Key Name box, and then click the blue button. The result of the search is displayed in the table at the bottom of the page.

  3. At any point, you can remove an item by selecting it and clicking the Delete button; similarly, you can modify an item from the table by selecting it and clicking Edit button. Note that deleting a credential map, deletes all keys in it.

To create a credential map:

  1. Click Create Map to display the Create Map dialog.

  2. In this dialog, enter the name of the map for the credential being created.

  3. Click OK to return to the Credentials page. The new credential map name is displayed with a map icon in the table.

To add a key to a credential map:

  1. Click Create Key to display the Create Key dialog.

  2. In this dialog, select a map from the menu Select Map for the key being created, enter a key in the text Key box, and select a type (Password or Generic) from the pull-down menu Type. The dialog display changes according the type selected.

    If Password was selected, enter the required fields (Key, User Name, Password, Confirm Passwords).

    If Generic was selected, enter the required field Key and the credential information either as text (select Enter as Text radio button), or as a list of key-value pairs (select Enter Map of Property Name and Value Pairs radio button); to add a key-value pair, click Add Row, and then enter the Property Name, Value, and Confirm Value in the added arrow.

    Figure 11-1 illustrates the dialog used to create a password key.

  3. Click OK to return to the Credentials page. The new key is displayed under the map icon corresponding to the map you selected.

    Figure 11-1 The Create Key Dialog

    Surrounding text describes Figure 11-1 .

To edit a key:

  1. Select a key from the table.

  2. Click Edit to bring up the Edit Key dialog.

  3. In that dialog, modify the key data as appropriate. In case of editing a generic key, use the red X next to a row to delete the corresponding property-value pair.

    Figure 11-2 illustrates the dialog used to edit a generic key.

  4. Click OK to save your changes and return to the Credentials page.

For specific considerations that apply to ADF applications only, see section How to Edit Credentials Deployed with the Application in Administering Oracle ADF Applications.

Figure 11-2 The Create Key Dialog

Surrounding text describes Figure 11-2 .

11.4 Managing Credentials with WLST commands

An online script is a script that requires a connection to a running server. Unless otherwise stated, scripts listed in this section are online scripts and operate on a policy store, regardless of whether it is file-, LDAP-, or DB-based. There are a few scripts that are offline, that is, they do not require a server to be running to operate.

Read-only scripts can be performed only by users in the following WebLogic groups: Monitor, Operator, Configurator, or Admin. Read-write scripts can be performed only by users in the following WebLogic groups: Admin or Configurator. All WLST commands are available out-of-the-box with the installation of the Oracle WebLogic Server.

WLST commands can be run in interactive mode or in script mode. In interactive mode, you enter the script at a command-line prompt; in script mode, you write scripts in a text file (with a py file name extension) and run it without requiring input, much like the directives in a shell script.

For platform-specific requirements to run a WLST command, see note in section Section 10.4, "Managing Application Policies with WLST commands."

In regards to configuration files and JVMs, see note in Section 5.6, "Typical Security Practices with WLST Commands."

OPSS provides the following scripts on all supported platforms to administer credentials (all scripts are online, unless otherwise stated):

Note:

To retrieve a credential with a given map and key, use scripting to invoke the MBean operation JpsCredentialMXBean.getPortableCredential(map, key).