10 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.

10.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.

In CSF, a credential is uniquely identified by a map name and a key name. Typically, the map name corresponds with the name of an application and 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.

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 an RDBMS DB-based credential store.

10.2 Encrypting Credentials

OPSS supports storing encrypted data in file- and LDAP-based credential stores. (In case of DB-based credential stores, data is always encrypted.) OPSS uses an encryption key to encrypt and decrypt data when it is read from or written to the credential store. 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" />

By default, credentials are kept in clear-text.

The Encryption Key

Assuming the above property set, OPSS automatically generates a random 256-bit AES key when the domain is restarted. Since the keys generated are practically distinct, a domain uses a unique encryption key. In addition to the first generated encryption key, there may be other keys (roll-over keys) automatically generated over time and used to encrypt and decrypt data. The only way to get a roll-over key is by restarting the domain.

When a new roll-over key is produced, data in the credential store is not immediately re-encrypted with the new key. Instead, data is re-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; this applies regardless of the type, LDAP or DB, of the credential store. 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 OPSS Scripts.

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

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

Use the OPSS script exportEncryptionKey to extract the key from Domain1's bootstrap wallet 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.

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 OPSS script reassociateSecurityStore, but with different syntaxes. For details about this script, see Section 9.3.29, "reassociateSecurityStore."

The first approach is as follows:

Use the OPSS script 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.

Use the OPSS script importEncryptionKey to write the extracted ewallet.p12 into Domain2's bootstrap wallet; note that the value of the argument keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.

Restart Domain2's server.

The second approach is as follows:

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

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:

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

Use the OPSS script exportEncryptionKey to extract the key from Domain1's bootstrap wallet 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.

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

Use the OPSS script importEncryptionKey to write the extracted ewallet.p12 into Domain2's bootstrap wallet; note that the value of the argument keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.

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 OPSS scripts exportEncryptionKey and importEncryptionKey.

10.3 Managing the Credential Store

Credentials can be provisioned, retrieved, modified, or deleted, but only by a user in the appropriate administration role. The following sections explain how an administrator can manage credentials using Fusion Middleware Control pages or OPSS scripts, and how code can access data in the CSF.

10.4 Managing Credentials with Fusion Middleware Control

The following procedure explains how to use Fusion Middleware Control to manage credentials.

Log in to Fusion Middleware Control and navigate to Domain > Security > Credentials (if the application is deployed on Oracle WebLogic Server), or to Cell > Security > Application Policies (if it is deployed on WebSphere Application Server), to display the Credentials page partially illustrated in the following graphic:

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

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.

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:

Click Create Map to display the Create Map dialog.

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

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:

Click Create Key to display the Create Key dialog.

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 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.

10.5 Managing Credentials with OPSS Scripts

An OPSS script is either a WLST script, in the context of the Oracle WebLogic Server, or a WASAdmin script, in the context of the WebSphere Application Server. The scripts listed in this section apply to both platforms: WebLogic Application Server and WebSphere Application Server.

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 scripts are available out-of-the-box with the installation of the Oracle WebLogic Server.

WLST scripts can be run in interactive mode or in script mode. In interactive mode, you enter the script at a command-line prompt and view the response immediately after. 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.

10.5.1 listCred

The script listCred returns the list of attribute values of a credential in the credential store with given map name and key name. This script lists the data encapsulated in credentials of type password only.

Script Mode Syntax

listCred.py -map mapName -key keyName

Interactive Mode Syntax

listCred(map="mapName", key="keyName")

The meanings of the arguments (all required) are as follows:

map specifies a map name (folder).

key specifies a key name.

Example of Use

The following invocation returns all the information (such as user name, password, and description) in the credential with map name myMap and key name myKey:

listCred.py -map myMap -key myKey

10.5.2 updateCred

The script updateCred modifies the type, user name, and password of a credential in the credential store with given map name and key name. This script updates the data encapsulated in credentials of type password only. Only the interactive mode is supported.

10.5.3 createCred

The script createCred creates a credential in the credential store with a given map name, key name, user name and password. This script can create a credential of type password only. Only the interactive mode is supported.

10.5.4 deleteCred

The script deleteCred removes a credential with given map name and key name from the credential store.

Script Mode Syntax

deleteCred.py -map mapName -key keyName

Interactive Mode Syntax

deleteCred(map="mapName",key="keyName")

The meanings of the arguments (all required) are as follows:

map specifies a map name (folder).

key specifies a key name.

Example of Use

The following invocation removes the credential with map name myMap and key name myKey:

deleteCred.py -map myMap -key myKey

10.5.5 modifyBootStrapCredential

The offline script modifyBootStrapCredential modifies the bootstrap credentials configured in the default jps context, and it is typically used in the following scenario: suppose that the policy and credential stores are LDAP-based, and the credentials to access the LDAP store (stored in the LDAP server) are changed. Then this script can be used to seed those changes into the bootstrap credential store.

jpsConfigFile specifies the location of the file jps-config.xml relative to the location where the script is run.

username specifies the distinguished name of the user in the LDAP store.

password specifies the password of the user.

Example of Use

Suppose that in the LDAP store, the password of the user with distinguished name cn=orcladmin has been changed to welcome1, and that the configuration file jps-config.xml is located in the current directory.Then the following invocation changes the password in the bootstrap credential store to welcome1:

10.5.6 addBootStrapCredential

The offline script addBootStrapCredential adds a password credential with given map, key, user name, and user password to the bootstrap credentials configured in the default jps context of a jps configuration file.