Environment variables simplify the process of container management because you can make all of your configuration changes in one place.

Important:

If you're running PingAccess in a clustered deployment, you must apply environment variable changes to each cluster node individually. PingAccess can't replicate property files, and by extension, environment variables, from the administrative node.

When PingAccess starts, it overrides property values in the configuration files with the values of the environment variables. During startup, PingAccess also logs environment variables that start with PA_ in the pingaccess.log file. Some initialization items might go to system.out.

Important:

If a utility uses a configuration file that's been modified by an environment variable, the utility also inherits any changes made by that environment variable.

For example, the obfuscate.sh script uses properties from the pa.jwk.properties file. If you create an environment variable that overrides a property in that file, obfuscate.sh also uses that modified property value.

Naming convention

To set your environment variables, use a deployment tool of your choice, such as Kubernetes or Docker Compose. Use the format PA_<FILE_NAME_WITHOUT_EXTENSION>_<PROPERTY_NAME>, where:

  • PA is short for PingAccess. You must begin all environment variables with this phrase.
  • <FILE_NAME_WITHOUT_EXTENSION> is the name of the file containing the property that you want to modify. Leave out the file extension.
  • <PROPERTY_NAME> is the name of the property that you want to modify.

When naming an environment variable:

  • Replace any periods in the file or property name with a single underscore.
    • Replace any dashes with two underscores.
  • Only use letters and underscores. Leave out any separators, such as parenthesis, braces, brackets, commas, or semicolons.
  • Write the whole environment variable in upper case.
    Note:

    Make sure that you use consistent case and spelling when setting environment variables to avoid unexpected behavior. If you have multiple references to the same property but case varies between those references, PingAccess can only use one version.

Examples
  • The environment variable for the pa.hostkey.keyId property in the pa.jwk.properties file is PA_PA_JWK_PA_HOSTKEY_KEYID.
  • The environment variable for the maxIdle property in the log4j2.db.properties file is PA_LOG4J2_DB_MAXIDLE.
  • The environment variable for the admin.header.X-Content-Type-Options property in the run.properties file is PA_RUN_ADMIN_HEADER_X__CONTENT__TYPE__OPTIONS.
  • The environment variable for the engine.httptransport.socketTimeout property in the run.properties file is PA_RUN_ENGINE_HTTPTRANSPORT_SOCKETTIMEOUT.
Modifiable properties

You can override the value of any property defined in one of the property files from the <pa>/conf directory. These property files include:

  • engine-registration.properties
  • fips-mode.properties
  • log4j2.db.properties
  • pa.jwk.properties
  • run.properties
Note:

It was already possible to override settings in the engine-registration.properties file with the ENGINE_NAME environment variable. You can continue to use the ENGINE_NAME environment variable, or you can update all instances to the new format for consistency.

Don't create environment variables for properties defined in:

  • Files outside of the /conf directory
  • .properties files from the /conf/localization directory.