Bookshelf v7.8.2: Configuring BI Presentation Services to Identify Credential Stores

BI Presentation Services must be able to identify the credential stores that store the credentials and secrets. The credential store details are specified in the BI Presentation Services configuration file instanceconfig.xml. This file is located in one of the following locations:

Credential stores are identified by the CredentialStore node in the instanceconfig.xml file. This top-level node contains one or more CredentialStorage sub-elements, each of which describes the type and location of a credential store. In addition, optional attributes for passphrase, as shown in Table 3, may be specified for the CredentialStore node.

When BI Presentation Services encounters an encrypted credential, it needs to know the passphrase to use to decrypt the credential. A passphrase-related attribute may be specified either at the CredentialStore node level, as an attribute of the CredentialStorage sub-node, or may be stored along with the credential in the credential store. When a passphrase attribute is specified at the CredentialStore level, then BI Presentation Services will use it as a default to decrypt any encrypted credential that it encounters if no other passphrase attributes have been specified at lower levels.

For security reasons, it is recommended that the passphrase not be stored within the credential store, since unauthorized access to the credential store will reveal passwords and secrets. Providing the passphrase needed to decrypt a credential in the instanceconfig.xml file allows for enhanced security, because neither the instanceconfig.xml file nor the credential store on its own has enough information to expose the password.

NOTE: You should secure any file where a passphrase has been provided using OS or file system capabilities.

Table 3. CredentialStorage Node Elements and Sub-elements
Attribute Name	Required?	Description
passphrase	No	For encrypted files, this determines the passphrase used to decrypt the file.
passphraseFile	No	Path to a plain text file that contains the passphrase. This file should be suitably protected using OS and file system facilities.
passphraseEnvVar	No	Name of an environment variable that contains the passphrase.
passphraseLoader	No	This value specifies a command line that should be executed to extract the passphrase for the key. The command must result in the passphrase being written out, in plain text format, to the standard output of the executable.

The CredentialStorage Element

The CredentialStorage sub-element describes the type and location of the credential store and various options for the credential store. The attributes of the CredentialStorage node are shown in Table 4.

In addition, all the passphrase-related attributes that are shown in Table 3 also supported for the CredentialStorage node.

Table 4. CredentialStorage Node Passphrase-Related Attributes
Attribute Name	Required?	Description
type	Yes	This describes the type of credential store. Possible values are JKS, file and custom. JKS refers to a Java Keystore, file to a credential store in proprietary XML file format, and custom to a custom store.
propertyFile	Yes, if type=JKS	This value points to a standard Java property file which contains all additional options necessary for loading the Java credential store. This attribute must be specified if type=JKS.
path	Yes, if type=file	This value points to an XML file in proprietary format that describes the credential store. This attribute must be specified if type=file.
commandLine	Yes, if type=custom	This value specifies the command line that should be executed to run the custom credential store loader. This attribute must be specified if type=custom.

The following example of the instanceconfig.xml file identifies two credential stores via two CredentialStorage elements. The first store identified is a Java Keystore of type JKS. The second is the XML file store, credentialstore.xml. For the XML file store, the passphrase "secret" has been provided as an attribute of the CredentialStorage element.