Configuration files

This topic describes the Configuration files plugin for CPM.

Overview

The CPM enables organizations to manage application accounts that are stored externally from the Vault in the following types of files:

File type

Password location in file
Plain text Passwords in plain text files can be specified anywhere in any format. The CPM identifies passwords using a regular expression.
INI Passwords in INI files are specified in a particular section and parameter. The CPM uses these details to identify passwords and change them.
XML Passwords in XML files are specified in XmlElements. The CPM uses XPath for these XmlElements and XmlAttributes to identify passwords and change them.
Web configuration Passwords are stored in the same way as in XML files. However, any changes made in web configuration files cause the application to restart. Account management for accounts that are managed with the web configuration service account must be initiated manually in the PVWA so that users can control the application restart.

In all of the above file formats, the password value can be stored in either of the following ways:

Password type

Password storage
Direct account password The password stored in the configuration file is exactly the same as the password stored in the Vault.
Encrypted account password The password stored in the configuration file is an encrypted version of the password stored in the Vault.

Support

Target devices

This plugin is supported on the following target devices:

  • RHEL 7.1, 8.x*, 9.x*

  • Ubuntu 18.04, 22.04*

  • Debian 11.6*
  • Fedora 38*
  • IBM AIX 7.1, 7.3
  • Solaris Intel 11.2, 11.3
  • Solaris SPARC 11.2, 11.3
  • SUSE Linux 12
  • OpenSUSE 15.4
  • CentOS 7
  • Oracle Enterprise Linux 6, 7

* The target device version is only supported when the SSH library is configured to work with the Rebex library. For more information, see Configure FIPS-compliant mode.

Windows Server 2012, 2016, 2019, 2022

Connection protocols

This plug-in supports the following protocols to connect to the remote machine:

■ Windows – Windows file and printer sharing protocol
■ Unix – SSH protocol

Prerequisites

This plugin requires .NET Framework 4.8. If you are using an older version of the CPM, .NET Framework 4.8 must be installed on the CPM machine as well.

Required authorizations

The account used to access the file requires the following permissions to access the configuration file on the remote machine:

■ Windows:
■ Permissions

The CPM can connect to a remote machine using a logon account that has the following permissions:

■ View the configuration file
■ Edit the configuration file
■ Create files (if the CPM is configured to create a backup password file)

If the password will be encrypted, the local system account used to run the CPM service requires the following file system permissions for the encryption program executable:

■ Administrative permissions
■ Communication
■ On the remote machine, make sure that the following options are enabled:
■ Client for Microsoft Networks
■ File and Printer Sharing for Microsoft Networks
■ On the CPM machine, if DEP is supported, disable it.
■ Unix
■ Permissions

The CPM can connect to a remote machine using a Unix/Linux connection with a logon account that has the following permissions:

■ SSH login permissions
■ View the password file
■ Edit the password file
■ Create files (if the CPM is configured to create a backup password file)
■ Communication
■ Open port 22 to enable SSH and SFTP activities.

Platform

In the Platform Management page, make sure that one of the following service account platforms is displayed, depending on the service account to implement:

■ Text Config File – To manage passwords stored in plain text files.
■ INI Config File – To manage passwords stored in INI files.
■ XML Config File – To manage passwords stored in XML files.
■ Web Config File – To manage passwords stored in web configuration files.

Encrypt passwords

Passwords stored in configuration files can be encrypted using an external command.

  1. In the Platform Management page, select Service Account Platforms.

  2. Select the platform that will manage the service account, and click Edit.

    The Service account settings page appears.

  3. Select Additional Policy Settings, and specify the following parameters:

    Parameter

    Description
    Encryption Command

    The encryption command that encrypts the password. This command sends the current password as its parameter.

    You can store the encryption file on the CPM machine in the bin folder or in another location. When storing the file in the bin folder, use the filename. When storing in another location, use the full path of the location and filename.

    For example:

    • Set the parameter to: 'C:\Encryption files\EncExe'

    • The command would be: 'C:\Encryption files\EncExe' <currpass>

    • Output: The new encrypted password

    You can also specify additional arguments. For example:

    • Set the parameter to: 'C:\Encryption files\EncExe' sha512

    • The command would be: 'C:\Encryption files\EncExe' <currpass> sha512

    If the encryption file or argument contain spaces, enclose it in single quotes as in the examples above.

    If the current password parameter is empty, the new password will be inserted in the file.
    Encryption Regex

    The regex parameter that handles the output of the Encryption Command parameter. If this parameter is not defined, it will behave as if "(.*)" has been specified.

    This parameter is only relevant when the Encryption Command parameter is defined.

  4. Click OK to save them and return to the System Configuration page.

Additional logon passwords

If the CPM manages a password in a configuration file on a remote machine, and the remote machine requires an additional password for log on, create an additional password object to contain the extra user’s logon details. You must link the additional password object to the original password object.

For more information, see Create linked accounts.

Usage

In the relevant platform, in the UI & Workflows parameters, add the ID of the service account in the list of Usages. For more information, see Edit a platform.

Add service accounts

When you add service account for an account stored in a configuration file, specify the following parameters:

1. In the Account Details page, display the TextConfigFile service account pane.
2. Specify the following required properties:
Property Description
Address The address of the remote machine where the Text configuration file is located.
File Path The full file path including name and extension of the configuration file that contains the password. For example, in Unix, "/home/passwords/filename". For example in Windows, "C:\NewShare\passwords\FileName.txt".
Password Regex The password regular expression that matches the line of the password in the configuration file. Specify a prefix and a postfix to allow the CPM to identify the entire line, and specify the password in parenthesis "(" and ")". This single-groups the password and defines the location of the password to change.
Example 1: Specify Password=(.*); to replace the new password with all the characters between Password= and ; (semi-colon). 
Example 2: Specify Password=(........); to replace the new password with eight characters after Password=. If the ; (semi-colon) is not found after eight characters, this regex will not match the line in the password file and will not replace the password successfully.
The CPM will replace all occurrences of the specified regex in the password file.
If the password regex is empty, the CPM will return an error message.
ConnectionType The connection type that will be used to access the target machine where the configuration file resides. Valid values are:
■Windows File Sharing
■SSH
1. In the Account Details page, display the INIConfigFile pane.
2. Specify the following required properties:
Property Description
Address The address of the remote machine where the INI configuration file is saved.
File Path The full file path including name and extension of the configuration file that contains the password. For example, in Unix, "/home/passwords/filename". For example in Windows, "C:\NewShare\passwords\FileName.ini".
INI Section The ini section that contains the password string. If more than one ini sections contain a password to manage, create multiple service accounts for this account or use the TextConfigFile usage.
INI Parameter Name The name of the parameter in the configuration file that contains the password. If more than one parameter in the same ini section contains a password to manage, create multiple service accounts for this account or use the TextConfigFile usage.
ConnectionType The connection type that will be used to access the target machine where the configuration file resides. Valid values are:
■Windows File Sharing
■SSH

XML files with a DTD are not supported.

1. In the Account Details page, display the XMLConfigFile pane.
2. Specify the following required properties:
Property Description
Address The address of the remote machine where the XML configuration file is located.
File Path The full file path including name and extension of the configuration file that contains the password. For example, in Unix, "/home/passwords/filename". For example in Windows, "C:\NewShare\passwords\FileName.xml".
XML Element The XPath that represents the xml element which contains the text/attribute to change.

For more information about XPath, refer to http://www.w3schools.com/xml/xpath_syntax.asp.
ConnectionType The connection type that will be used to access the target machine where the configuration file resides. Valid values are:
■Windows File Sharing
■SSH
3. Specify the following optional properties:
Property Description
Port The port that is used for non-standard SSH ports. Default is 22 if not set.

This parameter is only relevant for SSH protocol.
Backup Password File Whether or not a backup configuration file will be created. Specify Yes or No.

When this parameter is set to Yes, the password file will be saved in a subfolder of the location where the password file is stored, before the password content is changed.

The backup file will be named "Backup__ %fileName%" where %fileName% will be the suffix after the last trailing '/' or '\' and will reside in the same directory as the original password file.
Password Regex The password regex that matches the line of the password in the configuration file. Specify a prefix and a postfix to allow the CPM to identify the entire line, and specify the password in parenthesis "(" and ")". This single-groups the password and defines the location of the password to change.
Example 1: Specify Password=(.*); to replace the new password with all the characters between Password= and ; (semi-colon). 
Example 2: Specify Password=(........); to replace the new password with eight characters after Password=. If the ; (semi-colon) is not found after eight characters, this regex will not match the line in the password file and will not replace the password successfully.
The CPM will replace all occurrences of the specified regex in the password file.
If the password regex is empty, the CPM will return an error message.
XML Attribute The xml attribute of the xml element (defined in the XML Element parameter) to change. If this parameter is empty, the new password value will be written in the text of the xml element.
1. In the Account Details page, display the XMLConfigFile pane.
2. Specify the following required properties:
Property Description
Address The address of the remote machine where the WebConfig configuration file is located.
File Path The full file path including name and extension of the file that contains the password. For example, in Unix, "/home/passwords/filename". For example in Windows, "C:\NewShare\passwords\FileName.xml".
XML Element The XPath that represents the xml element which contains the text/attribute to change.
ConnectionType The connection type that will be used to access the target machine where the configuration file resides. Valid values are:
■Windows File Sharing
■SSH
3. Specify the following optional properties:
Property Description
Port The port that is used for non-standard SSH ports. Default is 22 if not set.

This parameter is only relevant for SSH protocol.
Backup Password  File Whether or not a backup configuration file will be created. Specify Yes or No.

When this parameter is set to Yes, the password file will be saved in a subfolder of the location where the password file is stored, before the password content is changed.

The backup file will be named "Backup__ %fileName%" where %fileName% will be the suffix after the last trailing '/' or '\' and will reside in the same directory as the original password file.
Password Regex The password regex that matches the line of the password in the configuration file. Specify a prefix and a postfix to allow the CPM to identify the entire line, and specify the password in parenthesis "(" and ")". This single-groups the password and defines the location of the password to change.
Example 1: Specify Password=(.*); to replace the new password with all the characters between Password= and ; (semi-colon). 
Example 2: Specify Password=(........); to replace the new password with eight characters after Password=. If the ; (semi-colon) is not found after eight characters, this regex will not match the line in the password file and will not replace the password successfully.
The CPM will replace all occurrences of the specified regex in the password file.
If the password regex is empty, the CPM will return an error message.
XML Attribute The xml attribute of the xml element (defined in the XML Element parameter) to change. If this parameter is empty, the new password value will be written in the text of the xml element.

Run multiple service accounts concurrently

At any time, only one configuration file service account process can manage a specific configuration file. If multiple processes specify the same Address and FilePath properties, the processes will run consecutively. However, if two service accounts specify the same configuration file, but one specifies an IP address and the other specifies the FQDN address, the CPM might run these service accounts simultaneously, which may cause an error.

Manage comments in INI configuration files

Comments that appear in the same line as passwords will be managed according to the following guidelines:

■ Lines that start with ‘#’ (hash) or ‘;’ (semi-colon) are line comments.
■ The INIConfigFile service account recognizes inline comments that are marked with a space followed by ‘ ;’ (space followed by a semi-colon), and will treat them as comments, as shown in the following example:
■ Previous password:  Password=Abc123 ; comment
■ New password: Password=Def456 ; comment
■ The INIConfigFile service account does not recognize inline comments that are marked with a hash (#), and will treat them as part of the password value.
■ Semi-colons that are not preceded by a space can be included in password values managed by the INIConfigFile service accounts, as shown in the following example:
■ Previous password:  Password=Abc;123
■ New password: Password=Def456
 

In lines that use a semi-colon as part of a password, you cannot specify inline comments with ‘ ;’ (space followed by a semi-colon).