9 Configuring 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:

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

9.2 Configuring a Domain to Use an LDAP-Based Credential Store

An LDAP-based credential store is typically used and recommended in production environments. The LDAP servers supported in this release are the Oracle Internet Directory and the Oracle Virtual Directory (LSA).

To use a domain LDAP-based credential store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or WLST commands.

The prerequisites for using an LDAP-based credential store are identical to those for using an LDAP-based policy store. For details, see Section 8.1.2, "Prerequisites to Using an LDAP-Based Policy Store."

An LDAP-based credential store is recommended in distributed environments. For details, see Section 8.1.1, "Multiple-Node Server Environments."

9.3 Reassociating the Domain Credential Store

The reassociation of both the Credential and the Policy stores is accomplished as a unit using Fusion Middleware Control or the WLST command reassociateSecurityStore, as explained in Section 8.2, "Reassociating the Domain Policy Store."

9.4 Migrating Credentials to the Domain Credential Store

A domain includes one credential store. Application-specific credentials are supported and migrated to credentials in the domain credential store when the application is deployed. Thus, all servers and all applications deployed in a domain use a common credential store, the domain credential store. Access to the credential store requires permission.

The following sections explain how to migrate credentials to the domain credential store when an application is deployed with either Fusion Middleware Control or a WLST command:

9.4.1 Migrating Application Credentials with Fusion Middleware Control

Application credentials are specified in the application file cwallet.sso and can be migrated to the domain credential store when the application is deployed or redeployed to a managed server in the WebLogic environment.

The migration of credentials differs with the migration of policies in several aspects: (a) credentials cannot be removed automatically when the application is undeployed; (b) the migration of credentials at deployment or redeployment with overwriting is allowed only when the WebLogic domain is operating in development mode.

For details, see procedure in Section 7.5.2, "Migrating Policies and Credentials at Deployment."

9.4.2 Migrating Credentials with the Command migrateSecurityStore

A specific credential map or all credentials in all maps can be migrated manually from a source repository to a target repository using the WLST command migrateSecurityStore.

This command is offline, that is, it does not require a connection to a running server to operate; therefore, the configuration file passed to the argument configFile need not be an actual domain configuration file, but it can be assembled just to specify the source and destination repositories of the migration.

The kinds of the repositories where the source and target data is stored is transparent to the command, and any combination of file-based and LDAP-based repositories is allowed (LDAP-repositories must use an Oracle Virtual Directory or an Oracle Internet Directory LDAP server only).

This command is typically used when transitioning from a test to a production environment, or when reproducing policy or credential data from one domain to another domain.

Note that the target LDAP server requires setting up before the command is used, as described in Section 8.1.2, "Prerequisites to Using an LDAP-Based Policy Store."

Note:

Since the command migrateSecurityStore recreates GUIDs and takes a long time to migrate large volume of data, you may want to consider migrating stores with an alternate procedure that uses Oracle Internet Directory bulk operations. For details, see Section 7.5.2.3, "Migrating Large Volume Policy and Credential Stores.".

The commands listed below can be run in interactive mode or in script mode. In interactive mode, you enter the command at a command-line prompt and view the response immediately after. In script mode, you write commands 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 further details about WLST commands and their syntax, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Important:

Before invoking a security-related WLST command in a shell, you must run the script wlst.sh, as illustrated in the following sample: 
> sh $ORACLE_HOME/common/bin/wlst.sh

This ensures that the required JARs are added to the classpath. Failure to run the above script in a new shell renders the WLST commands unusable.

Before running an online command, connect to the server as follows:

>java weblogic.WLST
>connect('servername', 'password', 'localhost:portnum')

Script and Interactive Modes Syntaxes

The command syntax varies depending on the scope of the credentials being migrated (credentials in a particular map or all credentials). Optional arguments are enclosed by square brackets.

To migrate all credentials use either of the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type credStore
                     -configFile jpsConfigFileLocation
                     -src srcJpsContext
                     -dst dstJpsContext

migrateSecurityStore(type="credStore", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext")

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

  • configFile specifies the location of a configuration file jps-config.xml relative to the directory where the command is run. Typically, this configuration file is created just to be used with the command and serves no other purpose. This files contains two jps-contexts that specify the source and destination stores.

    In addition, if the migration involves one or two LDAP-based stores, then this file must contain a bootstrap jps-context that refers to the location of a cwallet.sso file where the credentials to access the LDAP based involved in the migration are kept. See second example below. For complete details, see Section 15.4.7, "Specifying Bootstrap Credentials Manually."

  • src specifies the name of a jps-context in the configuration file passed to the argument configFile. This context identifies the source credential repository.

  • dst specifies the name of another jps-context in the configuration file passed to the argument configFile. This context identifies the target credential repository.

The contexts passed to src and dst must be defined in the passed configuration file and must have distinct names. From these two contexts, the command determines the locations of the source and the target repositories involved in the migration.

To migrate just one credential map, use either of the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

migrateSecurityStore.py -type folderCred
                     -configFile jpsConfigFileLocation
                     -src srcJpsContext
                     -dst dstJpsContext
                     [-srcFolder map1]
                     [-dstFolder map2]
                                     [-srcConfigFile alternConfigFileLocation]
                     [-overWrite trueOrFalse]

migrateSecurityStore(type="folderCred", configFile="jpsConfigFileLocation", src="srcJpsContext", dst="dstJpsContext", [srcFolder="map1"], 
[dstFolder="map2"], [srcConfigFile="alternConfigFileLocation"], [overWrite="trueOrFalse"])

The meanings of the arguments configFile, src, and dst are identical to the previous case. The meanings of the last four arguments (all optional) are as follows:

  • srcFolder specifies the name of the map containing the credentials to be migrated. This argument is optional. If unspecified, the credential store is assumed to have only one map and the value of this argument defaults to the name of that map.

  • dstFolder specifies the map to where the source credentials are migrated. This argument is optional and, if unspecified, defaults to the map passed to srcFolder.

  • srcConfigFile specifies the location of an alternate configuration file, and it is used in the special case in which credentials are not configured in the file passed to configFile. This argument is optional. If unspecified, it defaults to the value passed to configFile; if specified, the value passed to configFile is ignored.

  • overWrite specifies whether a target credential matching a source credential should be overwritten by or merged with the source credential. Set to true to overwrite the target credential; set to false to merge matching credentials. Optional. If not specified, defaults to false. When set to false, if a matching is detected, the source credential is disregarded and a warning is logged.

If the input does not follow the syntax above, the command execution fails and returns an error. In particular, the input must satisfy the following requisites: (a) the file jps-config.xml is found in the passed location; (b) the file jps-config.xml includes the passed jps-contexts; and (c) the source and the destination context names are distinct.

For examples of use, see Section 7.5.2.2, "Migrating Credentials Manually."

9.5 Managing the Domain 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 FMC pages or WLST commands, and how code can access data in the CSF.

9.5.1 Managing Credentials with Fusion Middleware Control

Fusion Middleware Control allows the management of credentials in a WebLogic domain, regardless of the type of credential store provider used in the domain, as explained in Managing Credentials.

This task is performed, for example, when a credential packaged with the application is to be replaced with another credential valid in the target environment.

9.5.1.1 Managing Credentials

This section explains the steps you follow to manage credentials in a domain credential store with Fusion Middleware Control, such as creating, viewing, deleting, or updating a credential stored in the credential store.

  1. Log in to Oracle Enterprise Manager and navigate to Domain > Security > Credentials, to display the Credentials page. This page is partially shown in the following graphic:

    Surrounding text describes emsyscreds.gif.

    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 where the key is inserted, enter a key in the text box Key, select a type from the menu Type (the appearance of the dialog changes according to the type selected), enter the required data.

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

9.5.2 Managing Credentials with WLST Commands

If a domain administrator does not want to use Fusion Middleware Control to manage credentials or wants to execute a frequent task automatically, the administrator can create a WLST script that invokes WLST security-related commands.

An online command is a command that to operate requires the Oracle WebLogic Server to be running. All commands below operate on a domain credential store, regardless of whether it is file-based or LDAP-base, to which you connect just before the commands are available.

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

Unless otherwise explicitly stated, the commands listed below can be run in interactive mode or in script mode. In interactive mode, you enter the command at a command-line prompt and view the response immediately after. In script mode, you write commands in a text file (with a py file name extension) and run it without requiring input, much like the directives in a shell script.

Important:

Before invoking a security-related WLST command in a shell, you must run the script wlst.sh, as illustrated in the following sample: 
> sh $ORACLE_HOME/common/bin/wlst.sh

This ensures that the required JARs are added to the classpath. Failure to run the above script in a new shell renders the WLST commands unusable.

Before running an online command, connect to the server as follows:

>java weblogic.WLST
>connect('servername', 'password', 'localhost:portnum')

WLST supports the following commands to administer credentials, all online commands, except for offline modifyBootStrapCredential:

9.5.2.1 listCred

The command listCred returns the list of attribute values of a credential in the domain credential store with given map name and key name. This command 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

9.5.2.2 updateCred

The command updateCred modifies the type, user name, and password of a credential in the domain credential store with given map name and key name. This command 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")

9.5.2.3 createCred

The command createCred creates a credential in the domain credential store with a given map name, key name, user name and password. This command 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")

9.5.2.4 deleteCred

The command deleteCred removes a credential with given map name and key name from the domain 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

9.5.2.5 modifyBootStrapCredential

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

This command must be run by a domain administrator and 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 command 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.