This chapter includes the following sections:
A credential can hold user names, passwords, and tickets, and 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.
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 the map name corresponds with the name of an application. All credentials with the same map name define a group of credentials, such as the credentials used by an application. The pair of map and key names must be unique for all entries in the credential store.
A password can have any number of characters, but they cannot be empty nor null.
By default, the credential store is an Oracle wallet and it can store X.509 certificates.
OPSS supports storing encrypted data in file and LDAP 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 is unique and has domain scope. To enable the encryption of credentials in a file or LDAP store, set the following property in the credential store instance of the jps-config.xml file:
<property name="encrypt" value="true" />
In case of DB credential stores, data is always encrypted using a client-side key.
The Domain Encryption Key
When you set the encrypt property to true, OPSS uses an encryption key to encrypt new credentials entered in the credential store. This encryption key is a 128-bit Advanced Encryption Standard (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 generated, the credential store data is not encrypted immediately with the new key. Instead, data is encrypted (with the new key) only when it is written. This means 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 facilitate this, OPSS provides offline scripts to export, import, and restore keys in the cwallet.sso bootstrap file so that an encryption key generated in one domain can be carried over to all other domains sharing the credential store.
The following scenarios illustrate how to set encryption key in a cluster of two domains, Domain1 and Domain2. (In case of more than two domains, treat each additional domain as Domain2).
Note:
The following scenarios assume an LDAP credential store but the use of the importEncryptionKey and exportEncryptionKey commands to import and export keys across domains applies also to DB credential stores (in which data is always encrypted).
Scenario One
Assume that Domain1 has reassociated to an LDAP credential store, and Domain2 has not yet joined to that store. Then, to enable credential encryption on that store:
Set the encrypt property to true in Domain1's jps-config.xml file and restart the domain.
Use the exportEncryptionKey WebLogic Scripting Tool (WLST) command to extract the key from Domain1 into the ewallet.p12 file. Note that the value of keyFilePassword passed to the command must be used later when you import that key into another domain.
Set the encrypt property to true in Domain2's jps-config.xml file.
At this point, complete the procedure in one of two ways. Both of them use the reassociateSecurityStore WLST command but with different syntaxes.
The first approach:
Use the reassociateSecurityStore WLST command to reassociate Domain2's credential store to that used by Domain1. Use the join argument and do not use the keyFilePassword and keyFilePath arguments.
Use the importEncryptionKey WLST command to import the extracted ewallet.p12 file into Domain2. Note that the value of keyFilePassword must be identical to the one used when the ewallet.p12 file was generated.
Restart Domain2's server.
The second approach:
Use the reassociateSecurityStore WLST command to reassociate Domain2's credential store to that used by Domain1. Use the join, keyFilePassword, and keyFilePath arguments.
Restart Domain2's server.
Scenario Two
Assume that Domain1 has reassociated to an LDAP credential store and Domain2 has already joined to that store. Then, to enable credential encryption on that store:
true in Domain1's jps-config.xml file and restart the domain.exportEncryptionKey WLST command to extract the key from Domain1 into the ewallet.p12 file. Note that the value of keyFilePassword passed to the command must be used later when you import that key into another domain.true in Domain2's jps-config.xml file.importEncryptionKey WLST command to write the extracted ewallet.p12 file into Domain2. Note that the value of keyFilePassword must be identical to the one used when the file ewallet.p12 was generated.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, you must import that key to each of the other domains in the cluster with the exportEncryptionKey and importEncryptionKey commands.
See also:
Managing Credentials with WLST
exportEncrytionKey and importEncryptionKey in WLST Command Reference for Infrastructure Security
Follow the instructions in this section to manage credentials with Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control).
Task 1, Opening the Credentials Page
Log in to Fusion Middleware Control and go to Domain, then to Security, and then to Credentials. The Credentials page is displayed. The Policy Store Provider area is read-only and displays the provider currently used in the domain.
Task 2, Searching Credentials
To display credentials matching a given key name, enter the string to match in the Credential Key Name text field, and then click the search button. The result of the search is displayed in the table at the bottom of the page.
Task 3, Creating a Credential Map
Click Create Map. The Create Map dialog is displayed.
Enter the name of the map for the new credential.
Click OK to return to the Credentials page. The new credential map name is displayed in the table.
Task 4, Adding a Key to a Credential Map
Click Create Key. The Create Key dialog is displayed.
In the Select Map menu, choose a map, enter a key in the text Key text field, and choose a type (Password or Generic) from the pull-down menu Type.
For a Password key, enter the fields Key, User Name, Password, Confirm Passwords.
For a Generic key, enter the required field Key and the credential information either as text (choose the Enter as Text radio button), or as a list of key-value pairs (choose the 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.
Click OK to return to the Credentials page. The new key is displayed under the map you chose.
Task 5, Editing a Key
Executing an online command requires a connection to a running server. Unless otherwise stated, the commands listed in this section are online and operate on a security store.
Read-only scripts can be performed only by users in the following WebLogic Server groups: Monitor, Operator, Configurator, or Admin. Read/write scripts can be performed only by users in the following WebLogic Server groups: Admin or Configurator. All WLST commands are available with the installation of Oracle WebLogic Server.
You can run WSLT commands in interactive or in script mode. In interactive mode, you enter the command at a command-line prompt. In script mode, you write the commands in a text file and run the script, much like the directives in a shell script.
OPSS provides the following commands to administer application credentials: