Credential Provider (CP) configuration files

The CP is configured in two parameter files. One file is installed locally with the CP, and the other is stored in a Safe in a Digital Vault.

 

This topic describes the parameters in the CP configuration files and their default values. For optimal performance guidelines, see Recommendations for best performance.

For more information on logs configuration, see Configure audit and monitor log files.

basic_appprovider.conf

basic_appprovider.conf is the CP's local or basic configuration file.

It specifies the location of the central configuration file in the Vault, and the parameters that are required to log onto the Vault and retrieve the central configuration file.

During installation this file is copied to:

  • Windows - the installation folder of the Credential Provider
  • Linux/AIX – the /etc/opt/CARKaim/conf folder
basic_appprovider.conf parameters

Parameter

Description

AppProviderParmsSafe

The name of the Safe where the main configuration file is stored.

Default value: AppProviderConf

AppProviderVaultParmsFolder

The name of the folder in the configuration Safe where the main configuration file is stored.

Default value: Root

AppProviderVaultParmsFile

The name of the main configuration file.

Default value: main_appprovider.conf. <platform>.<version>

AppProviderVaultFile

The full pathname of the Vault.ini file. For more information about this file’s location, see:

Default value: Default location of the installation

AppProviderCredFile

The full pathname of the CP’s credential file used to access the Vault.

Default value: Default location of the installation

AdvancedFIPSCryptography

Enables FIPS-complaint cryptography in the CP.

 

Applies only to CP, not to the SDKs used with CP.

Default value: No

PIMConfigurationSafe

The name of the Safe where the PAM configuration files are stored.

This value is set by the user during installation.

dsf

Default value: PVWAConfig

PIMConfigurationFolder

The folder in the PAM configuration Safe where the PAM configuration files are stored.

This value is set by the user during installation.

Default value: Root

PIMPVConfigurationFileName

The name of the PAM configuration file.

This value is set by the user during installation.

Default value: PVConfiguration.xml

PIMPoliciesConfigurationFileName

The name of the platform configuration file.

This value is set by the user during installation.

Default value: Policies.xml

LogsFolder

The folder where the CP log files will be stored.

Default value: Default location of the installation

TempFolder

The path of the temporary files folder.

Default value: Default location of the installation

LocalParmsFileFolder

The folder where the configuration file backed up.

Default value: Default location of the installation

InitialTraceLevels

The trace level for activities that occur the first time the CP connects to the Vault after the aimprv service starts. You can set several values, separated by commas. For example, 0,1,2,3,4,5.

Default value: 0

main_appprovider.conf. <platform>.<version>

This is the Credential Provider's main configuration file. It contains all the parameters that determine how the Credential Provider works.

During installation, this file is copied to the CP Safe (by default, called AppProviderConf) in the Vault.

Because this configuration file is stored in the Vault, several CPs running on the same type of operating system can use this same main configuration file. In this case, it is known as the central configuration file. See Shared configuration.

Alternatively, a Credential Provider can have its own customized main configuration file.

General parameters

main_appprovider.conf file - General parameters

Parameter

Description

ProviderCacheFolder

The folder where the general caches’ persistent files will reside.

Acceptable value: A folder path

Default value: --

OfflineUpdateInterval

The number of seconds that the CP will wait until its next attempt to update offline operations in the Vault.

Type: Numeric

Default value: 1800

OfflineUpdateRetries

The maximum number of retries that will be performed to update an offline operation in the Vault.

Type: Numeric

Default value: 600

MaxConcurrentRequests

The number of threads in the CP that will handle Credential Provider password requests.

Acceptable value: Numeric

Default value: 40

OldLogsRetention

The number of days that trace and console log files will be saved in the CP’s Logs folder. A value of ‘-1’ indicates that log files will not be deleted.

If this parameter is changed from zero to a positive number or vice versa, the change is only applied after the Credential Provider is restarted.

Type: Numeric

Default: 30

OldAuditLogsRetention

The number of days that audit log files will be saved in the \Old subfolder of the CP’s Logs folder. A value of ‘-1’ indicates that log files will not be deleted.

If this parameter is changed from zero to a positive number or vice versa, the change is only applied after the Credential Provider is restarted.

Type: Numeric

Default value: 90

AuthenticationLogs

Whether or not authentication warning and info logs show in AppConsole.log and the Windows Event Viewer.

Acceptable value: Yes/No

Default value: Yes

AuthenticationLogsInterval

The number of minutes after which the authentication security standard is checked. The default is every 24 hours.

Acceptable value: 0-10080. A value of 0 indicates continuous checks. A value of 10080 indicates a once per week check.

Default value: 1440 (24 hours)

AutomaticParmsRefreshInterval

The frequency (in seconds) that the CP will refresh the main configuration file stored on the CP machine from the file in the Vault.

Type: Numeric

Default value: 3600

AutomaticProviderPasswordRefreshInterval

The frequency (in seconds) that the CP takes to refresh the connection to the Vault and log in again. After logging in, the user's password is changed in the Vault and updated in its credential file."appprovideruser.cred".

This process runs as part of the AutomaticParmsRefresh background job and therefore the frequency of this process depends on the AutomaticParmsRefreshInterval's value as well.

The default is every 24 hours

Type: Numeric

Default value: 86400 (24 hours)

LogRetentionOnSizeMB

The size in MB of log files when it will be moved to the ‘Old’ folder. A new log file will be started in its place.

Type: Numeric

Default value: 25

LogRetentionOnTimeIntervalMinutes

The number of minutes after which a log file will be moved to the ‘Old’ folder.

Type: Numeric

Default value: 0

ShutdownTimeoutSec

The number of seconds that the CP will wait to terminate pending requests when shutting down.

Type: Numeric

Default value: 180

DisableExceptionHandling

Whether exceptions will be handled by the operating system during a system crash or an error will be written to the CP log but the error will not be handled.

Acceptable value: Yes/No

Default value: Yes

ProviderHostNames

Enables CPs to use a user provided hostname/IP, instead of relying on the NIC. This is useful when there is a large number of NICs on the server, and will significantly shorten the time it takes the CP to start.

Specify a list of one or more hostnames or IP addresses separated by a comma.

If a host name includes a comma, specify it within “”.

Recommended: Add this parameter to a Provider specific configuration file.

Acceptable value: One or more IP addresses, separated by a comma

Default value: --

VerboseErrors

Whether or not verbose error logs will be shown in responses and the Windows Event Viewer.

Acceptable value: Yes/No

Default value: No

For zOS 12.6, this value must be set to Yes.

TrustedCLIShells

Defines a list of shells that are authorized to run scripts. If an untrusted shell runs a script, an error will be returned. For more information about this parameter, refer to Restrict trusted shells to run the CLI password SDK. For more information about this error, refer to Untrusted shell errors

To customize the trusted shells list, add this parameter to the “[Main]” section of the main configuration file.

Acceptable value: String, separated by commas

Default value: --

TrustedCLIWrappers parameters

main_appprovider.conf file - TrustedCLIWrapper parameters

Parameter

Description

HASH1

The hash value of a wrapper script used by applications running from CPs that use this configuration file. You can add up to 200 hash values, specifying each hash value on a new line. For example:
HASH1=…
HASH2=…
HASH3=…

Type: String

Default value: --

Debug parameters

main_appprovider.conf file - Debug parameters

Parameter

Description

AppProviderDebugLevels

The level of Provider debug. You can set several values, separated by commas.

Acceptable values: 0,1,2,3,4,5

Default value: 0

CacheDebugLevels

The level of cache debug. You can set several values, separated by commas.

Acceptable values: 0,1,2

Default value: 0

ProtocolDebugLevels

The level of protocol debug. You can set several values, separated by commas.

Acceptable values: 0,1,2

Default value: 0

Cache parameters

To reduce the load on the Vault, always configure a caching mechanism.

main_appprovider.conf file - Cache parameters

Parameter

Description

CacheRefreshInterval

The frequency (in seconds) that the CP cache is refreshed by the background process.

Best practice:

This value has an impact on the ChangeNotificationPeriod parameter value defined in the Central Policy Manager, and on the LocalCacheLifespan parameter value defined in Application Server Credential Provider.

We recommend using the following values for these parameters:

  • CacheRefreshInterval= 1500 seconds
  • ChangeNotificationPeriod = 3001 seconds (calculated from (CacheRefreshInterval* 2) + 1). That is, there will be at least 2 refresh cycles before the password is released.

  • LocalCacheLifeSpan = ((CacheRefreshInterval/ 2) - 1) = 749 seconds, that is, the Application Server Credential Provider 2nd-level cache will refresh twice as frequently as the Credential Provider cache.

That being said, you should configure these values based on your organization's needs.

For example:

  • If your organization requires a shorter time for the immediate password change to occur, then lower the CacheRefreshInterval value.

    • CacheRefreshInterval= 180 seconds
    • ChangeNotificationPeriod = (CacheRefreshInterval*2) + 1 = 361 seconds.
    • LocalCacheLifeSpan = ((CacheRefreshInterval/ 2) - 1) = 89 seconds
  • If your organization wants more certainty that the cache refresh succeeded and that at least 3 cycles of refresh cache occur before the password changes, you could define following configuration:

    • CacheRefreshInterval= 1500 seconds
    • ChangeNotificationPeriod = (CacheRefreshInterval*3) + 1 = 4501 seconds.
    • LocalCacheLifeSpan = ((CacheRefreshInterval/ 2) - 1) = 749 seconds

Type: Numeric

Default value: 1500

VaultAccessInterval

The time (in seconds) after the most recent retrieval of a password in cache from the Vault until it expires. After a password expires, it is no longer retrieved from the cache and the next password request goes to the Vault.

A password that expires is updated by the Credential Provider.

Specify -1 to ensure that passwords in the cache never expire.

Type: Numeric

Default value: 31536000 (1 year)

CacheLevel

The type of cache level that will be implemented on the CP.

Acceptable values: None, Memory, Persistent

Default value: Persistent

KeyStorage

(For CacheLevel=Persistent)

Where the cache file encryption key is stored.

If set to Vault, the key is stored in the Vault in a dedicated Safe. This mode requires a more stable connection to the Vault. For more information, see Persistent cache level.

Acceptable values: Local, Vault

Default value: Local

CacheFile

The name of the file that will be used for the Secrets Manager persistent cache, if the persistent cache level is implemented.

Acceptable values: Full file path

Default value: --

CachedSecretExpiry

The time (in hours) that an unrequested secret object will be stored in the cache, after which it will be physically removed from the cache the next time the cache is manually or automatically refreshed.

Acceptable values: 1 - 8760 hours (1 year)

Default value: 168 hours (7 days)

ValidateQueriesAgainstVault

Determines whether regex queries will be validated against the Vault or against the local cache.

  • Yes - queries are validated against the Vault once per cache refresh interval, and the cache is updated

  • No - queries are validated against the cache

Acceptable values: Yes/No

Default value: No

TCP parameters

main_appprovider.conf file - TCP parameters

Parameter

Description

Port

The port number that the CP uses to listen for application requests from Password SDKs.

Acceptable values: 1-65536

Default value: 18923

TcpTimeout

The number of seconds that the CP will wait to receive a request or send a response to the application.

Type: Numeric

Default value: 30