10 Managing the Credential Store

A credential store is a repository of security data (credentials). A credential can hold user name and password combinations, tickets, or public key certificates. 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 credentials (user name and password) to access some external system, such as a database or an LDAP-base repository.

This chapter is divided into the following sections:

• Credential Types

• Managing Credentials with Fusion Middleware Control

• Managing Credentials with OPSS Scripts

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 combination of map name and key name must be unique for all entries in the credential store.

Oracle Wallet is the default credential store; in a production environment, it is recommended the use of an LDAP-based Oracle Internet Directory as the credential store. It is also recommended that the Oracle Wallet be used to store X.509 certificates. The credential store does not allow the storage of end-user digital certificates.

10.2 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.3 Managing Credentials with Fusion Middleware Control

The following procedure explains how to manage credentials with Fusion Middleware Control, including creating, viewing, deleting, or updating a credential.

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

   
   

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

   The table below this read-only area allows creating, editing, and searching credentials.

2. At any point, use the button Delete to remove a selected item (key or map) in the table. Note that deleting a credential map, deletes all keys in it. Similarly, use the button Edit to view or modify the data in a selected item.

3. To display credentials matching a given key name, enter the string to match in the box Credential Key Name, and then click the blue button to the right of it. The result of the query is displayed in the table.

4. To redisplay the list of credentials after examining the results of a query, select Domain > Security > Credentials.

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 box Key, and select a type (Password or Generic) from the pull-down menu Type. The dialog display changes according the type selected.

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

   If Generic is 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 Create Key dialog used to create a generic 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 Generic Key Dialog

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 Edit Key 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 Edit Key Dialog

To remove a key or a map:

1. Select the item from the table.

2. Click Delete and confirm the item's removal.

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

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

For platform-specific requirements to run an OPSS script, see Important Note.

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

• listCred

• updateCred

• createCred

• deleteCred

• modifyBootStrapCredential

• addBootStrapCredential

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

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

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

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

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