Skip Headers
Oracle® Fusion Middleware Application Security Guide
11g Release 1 (11.1.1)

Part Number E10043-11
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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.

This chapter is divided into the following sections:

10.1 Credential Types

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

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

By default, credentials are kept in clear-text.

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

The first approach is as follows:

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

  2. Use the OPSS script 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 OPSS script 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 OPSS script 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 OPSS script 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 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. For procedures to manage other service providers, see Section 8.7, "Configuring Services Providers with Fusion Middleware Control."

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

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

  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 10-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 10-1 The Create Key Dialog

    Surrounding text describes Figure 10-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 10-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 Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

Figure 10-2 The Create Key Dialog

Surrounding text describes Figure 10-2 .

10.5 Managing Credentials with OPSS Scripts

An OPSS script is either a OPSS 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. The script syntaxes on the WebSphere platform are practically identical to those on the WebLogic platform, the only difference being that, on WebSphere, script names are prefixed with the string Opss.

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

OPSS scripts 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 an OPSS script, see note in section Section 9.3, "Managing Application Policies with OPSS Scripts."

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

WASAdmin scripts can be run in interactive mode only. For details, see Oracle Fusion Middleware Third-Party Application Server Guide.

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

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

Interactive Mode Syntax

updateCred(map="mapName", key="keyName", user="userName", password="passW", [desc="description"])   

The meanings of the arguments (optional arguments are enclosed by square brackets) are as follows:

  • map specifies a map name (folder) in the credential store.

  • key specifies a key name.

  • user specifies the credential user name.

  • password specifies the credential password.

  • desc specifies a string describing the credential.

Example of Use

The following invocation updates the user name, password, and description of the password credential with map name myMap and key name myKey:

updateCred(map="myMap", key="myKey", user="myUsr", password="myPassw")

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

Interactive Mode Syntax

createCred(map="mapName", key="keyName", user="userName", password="passW", [desc="description"])  

The meanings of the arguments (optional arguments are enclosed by square brackets) are as follows:

  • map specifies the map name (folder) of the credential.

  • key specifies the key name of the credential.

  • user specifies the credential user name.

  • password specifies the credential password.

  • desc specifies a string describing the credential.

Example of Use

The following invocation creates a password credential with the specified data:

createCred(map="myMap", key="myKey", user="myUsr", password="myPassw") 

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

This script is available in interactive mode only.

Interactive Mode Syntax

modifyBootStrapCredential(jpsConfigFile="pathName", username="usrName", password="usrPass")

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

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

modifyBootStrapCredential(jpsConfigFile='./jps-config.xml', username='cn=orcladmin', password='welcome1')

Any output regarding the audit service can be disregarded.

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

This script is available in interactive mode only.

Interactive Mode Syntax

addBootStrapCredential(jpsConfigFile="pathName", map="mapName", key="keyName", username="usrName", password="usrPass")

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

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

  • map specifies the map of the credential to add.

  • key specifies the key of the credential to add.

  • username specifies the name of the user in the credential to add.

  • password specifies the password of the user in the credential to add.

Example of Use

The following invocation adds a credential to the bootstrap credential store:

addBootStrapCredential(jpsConfigFile='./jps-config.xml', map='myMapName', key='myKeyName', username='myUser', password='myPassword')

10.5.6 exportEncryptionKey

The offline script exportEncryptionKey extracts the OPSS domain encryption key to a pkcs#12 format file called ewallet.p12.

Interactive Mode Syntax

exportEncryptionKey(jpsConfigFile="pathName", keyFilePath="dirloc" ,keyFilePassword="password")

All arguments are required:

  • jpsConfigFile specifies the location of the file jps-config.xml; either relative to the location where the script is run, or the full path.

  • keyFilePath specifies the directory where the file ewallet.p12 is created; note that the content of this file is encrypted and secured by the value passed to keyFilePassword.

  • keyFilePassword specifies the password to secure the file ewallet.p12; note that this same password must be used when importing that file.

10.5.7 importEncryptionKey

The offline script importEncryptionKey replaces the OPSS domain encryption key with the one in the specified ewallet.p12 file.

Interactive Mode Syntax

importEncryptionKey(jpsConfigFile="pathName", keyFilePath="dirloc" ,keyFilePassword="password")

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

  • jpsConfigFile specifies the location of the file jps-config.xml; either relative to the location where the script is run, or the full path.

  • keyFilePath specifies the directory where the ewallet.p12 is located.

  • keyFilePassword specifies the password used when the file ewallet.p12 was generated.

10.5.8 restoreEncryptionKey

The offline script restoreEncryptionKey replaces the current OPSS domain encryption key with the key that was used prior to the execution of importEncryptionKey. The current key is lost forever; this command is typically used when there is a need to restore to a previously working version of the domain.

Interactive Mode Syntax

restoreEncryptionKey(jpsConfigFile="pathName")

Its only argument is required:

  • jpsConfigFile specifies the location of the file jps-config.xml; either relative to the location where the script is run, or the full path.

10.5.9 rollOverEncryptionKey

The offline script rollOverEncryptionKey replaces the current domain OPSS encryption key with a new one; the current key is not deleted but archived, since it is used to decrypt data that was encrypted using that key.

Interactive Mode Syntax

rollOVerEncryptionKey(jpsConfigFile="pathName")

Its only argument is required:

  • jpsConfigFile specifies the location of the file jps-config.xml; either relative to the location where the script is run, or the full path.

Note the following important points:

  • This command should be executed from the administration server in the domain. No server restart is needed after its execution.

  • If the domain is the only domain accessing the security store, nothing else is required.

  • However, if two or more domains share the security store, the newly generated key should be exported from the domain where the script was run and imported into each of the other domains sharing the security store, using the scripts exportEncryptionKey and importEncryptionKey.

  • On the WebSphere platform, the script name is Opss.rollOverEncryptionKey.