Storing passwords in a vault

You can use a vault to store the OpenPages® database user password, the OPSystem user password, or both.

This topic applies to IBM OpenPages traditional on-premises and IBM OpenPages on Cloud.

Before you begin

You need a CyberArk vault.
Request an SSL certificate from your CyberArk administrator. The certificate is required to authenticate the connection between OpenPages and CyberArk.
In CyberArk, create an Application for OpenPages. For more information, see the CyberArk documentation.
In CyberArk, add one or both of the following user accounts to the vault. Put the accounts into the same safe within the vault.
- The OpenPages database user, for example openpage
- The OPSystem user

About this task

When OpenPages needs a password, it retrieves it from the vault. When you need to change the password, you update it in the vault.

Procedure

Set up the SSL certificate keystore with the client certificate and server certificates:
1. Add the client certificate to the keystore. If the client certificate is in .crt or .pem format, convert it:
  In this example, the client certificate is cyberark-client.p12 and the keystore is cyberark-ssl8.p12.
```
keytool -importkeystore -srckeystore cyberark-client.p12 -srcstoretype pkcs12 -destkeystore cyberark-ssl8.p12 -deststoretype pkcs12
```
2. Add any server certificates to the same keystore by running the following command:
  In this example, the server certificate is cpd-cyberark1-chain.pem.
```
keytool -importcert -file cpd-cyberark1-chain.pem -alias cpd-cyberark -keystore cyberark-ssl8.p12 -storetype pkcs12
```
3. Copy the keystore file to the following directory on each application server: <OP_HOME>/aurora/conf/.
  For example: <OP_HOME>/aurora/conf/cyberark-ssl8.p12

Configure the vault properties.

Log in to the application server and go to the <OP_HOME>/aurora/conf/ directory.
Create a file called vault.properties.

Copy the following text into the file:

implementation=CyberArk
cyberark.safe=
cyberark.account=
cyberark.db.user=
cyberark.db.object=
cyberark.opsystem.object=
cyberark.keystore.file=
cyberark.keystore.pass=
cyberark.url=
cyberark.ssl.disable.hostname.verification=true|false
cyberark.keystore.type=pkcs12
cyberark.keystore.alias=
cyberark.db.folder=
cyberark.opsystem.folder=

Configure the following properties in the file:

Table 1. Vault properties
Property	Description
`cyberark.safe`	Type the name of the vault. For example: `OpenPagesSafe`
`cyberark.account`	Type the unique ID of the application (App ID) that you created in CyberArk for OpenPages.
`cyberark.db.user` `cyberark.db.object`	If you are storing the OpenPages database user password in the vault, complete these fields. `cyberark.db.user`: Type the username of the OpenPages database user. The name must match the name in the vault. `cyberark.db.object`: Type the account name (unique ID) of the object in your vault that stores the database password. For example: `cyberark.db.user=openpage cyberark.db.object=Database-Oracle-openpage`
`cyberark.opsystem.object`	If you are storing the OPSystem password in the vault, type the account name (unique ID) of the object in your vault that stores the OPSystem password.
`cyberark.keystore.file`	Type the absolute path to the keystore that contains the CyberArk server certificates. For example: `/home/opuser/OP/OpenPages/aurora/conf/cyberark-ssl8.p12` An absolute file path is required because the same properties file will be used by multiple components that will have different relative path locations.
`cyberark.keystore.pass`	Type the password of your client certificate keystore.
`cyberark.keystore.alias`	Type the alias of the keystore.
`cyberark.url`	Type the HTTPS URL for CyberArk. For example: `https://myserver-cyberark.com`
`cyberark.ssl.disable.hostname.verification`	Set to `false` (default) unless the SSL server certificate and the hostname of the CyberArk environment are not the same. You might encounter this situation in non-production environments that use self-signed certificates.
`cyberark.keystore.type`	This property must be set to `pkcs12`.
`cyberark.db.folder`	Optional Specifies the CyberArk folder in the safe under which `cyberark.db.object` is located.
`cyberark.opsystem.folder`	Optional Specifies the CyberArk folder in the safe under which `cyberark.opsystem.object` is located. Leave blank if you don't need this property.

If you do not have values for the following properties, remove them from the file. Do not leave these properties in the file with blank values.
- cyberark.opsystem.object
- cyberark.keystore.alias
- cyberark.db.folder

If you're storing the database password in the vault, update the Liberty database data source files (op-ora.xml or op-db2.xml) on each application server.

Go to the <OP_HOME>/wlp-usr/servers/<server_name>Server<#>/configDropins/overrides/ directory.
If the op-ora.xml or op-db2.xml file is not in the overrides directory, copy it from the <OP_HOME>/wlp-usr/servers/<server_name>Server<#>/op-db2.xml directory.
Do not modify or delete the files in <OP_HOME>/wlp-usr/servers/<server_name>Server<#> file.
Open the op-ora.xml or op-db2.xml file in the <OP_HOME>/wlp-usr/servers/<server_name>Server<#>/configDropins/overrides/ directory.

Add the following jaasContextEntry elements:

<jaasLoginContextEntry id="vaultJAASLoginEntry" name="vaultJAASLoginEntry" loginModuleRef="vaultLoginModule" />
    <jaasLoginModule id="vaultLoginModule" className="com.ibm.openpages.vault.jaas.VaultDBLoginModule" controlFlag="REQUIRED" libraryRef="vaultJaasLibrary">
         <options VaultPropertiesPath="${openpages.home}/aurora/conf/vault.properties"/>
    </jaasLoginModule>

    <library id="vaultJaasLibrary">
      <fileset dir="${openpages.home}/aurora/lib" includes="com.ibm.openpages.vault.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="com.ibm.openpages.vault.jaas.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="httpclient-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="httpcore-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="commons-logging-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="jackson-annotations-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="jackson-core-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="jackson-databind-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="bcprov-jdk15to18-*.jar"/>
      <fileset dir="${openpages.home}/aurora/lib" includes="aurora-tools.jar"/>
    </library>

Update both of the <dataSource...> elements in the file to add the following attribute:
```
jaasLoginContextEntryRef="vaultJAASLoginEntry"
```
Remove the op.jdbc.password attribute from the nested properties of each of the dataSource elements.
Open the <OP-HOME>/wlp-usr/servers/<server-name>-OPNode1Server1/bootstrap.properties file and remove the op.jdbc.password property.
Repeat these steps on each application server.

If you're storing the database password in the vault and you are using an Oracle database, do the following steps:
1. Edit the /home/opuser/OP/OpenPages/aurora/bin/op-backup-restore.env file.
2. Set the following property:
```
VAULT_IMPLEMENTATION=CyberArk
```
3. Comment out or remove the DB_OP_PWD property.
4. Repeat these steps on each application server.
If you're storing the database password in the vault and you use Global Search, do the following steps:
1. If the global search server is on a different host than the application server, copy the vault.properties file and the certificate .p12 file to the search server.
2. Edit the /home/opuser/OP/OPSearch/opsearchtools/openpages_search.properties file.
3. Change the line OPSearchTool.DatabaseVaultProperties= to the absolute path of the vault.properties file on the search server.
4. Comment out the OPSearchTool.DatabasePassword property.
5. Restart the search server.
If you're storing the OPSystem password in the vault, do the following steps:
1. Open the aurora.properties file.
2. Remove or comment out the following property:
```
security.system.password
```
3. Repeat these steps on each application server.
Restart all application servers.
If you use Global Search, restart the search server.

What to do next

When you need to change the database password, update it in the vault. Next, update IBM® Cognos® Analytics with the new password. See Modifying the OpenPages database password in Cognos.

Note: If you're using Global Search, do not use the opsearchtool.sh script to change the database password for the search server.

When you need to change the OPSystem password, update it in the vault, and then run the chng-sys-password utility. See Changing the OPSystem password.