To start PingAuthorize Policy Editor, use the bin/start-server command.

$ bin/start-server
Note:

You can run bin/start-server manually from the command line or within a script.

Overriding the configuration at startup

You can override a number of Policy Editor settings by defining specific environment variables before starting the server. By overriding some of the configuration, you can redefine certain aspects of the configuration without re-running the setup tool.

To override the configuration, stop the Policy Editor, define one or more of the environment variables, and restart the Policy Editor.

Environment variables you can use to override configuration variables

The following table lists the environment variables that you can define, sorted based on expected frequency of use with related variables grouped together.

Environment variable Example value Description

PING_EXTERNAL_BASE_URL

pap.example.com:9443

The Policy Editor hostname and port.

PingAuthorize uses this value to construct AJAX requests.

The port value must match the value of PING_PORT for web browsers to pass cross-origin resource sharing (CORS) checks.

PING_PORT

443

The Policy Editor HTTPS port.

The server binds to this listen port.

PING_KEYSTORE_TYPE

JKS

The Policy Editor’s key store type. Valid values include JKS and PKCS12.

PING_KEYSTORE_PATH

/path/to/keystore.jks

The path to the Policy Editor’s key store.

KEYSTORE_PIN_FILE

/path/to/keystore.pin

The path to the Policy Editor's key store PIN file. When present, this environment variable takes precedence over PING_KEYSTORE_PASSWORD when validating and presenting the server certificate. The key store PIN value itself does not persist to the configuration.yml file and is not visible on the command-line. For a more complete example, see the Demo mode (custom SSL certificate) tab of Installing the PingAuthorize Policy Editor non-interactively.

PING_KEYSTORE_PASSWORD

password1234

The Policy Editor’s key store password.

PING_CERT_ALIAS

server-cert

The alias for the Policy Editor’s server certificate.

PING_SHARED_SECRET

pingauthorize

The Policy Editor’s shared secret, which PingAuthorize Server needs to make policy requests to the Policy Editor.

PING_OIDC_​CONFIGURATION_ENDPOINT

https://oidc.example.com:9031/.well-known/openid-configuration

The OpenID Connect (OIDC) provider’s discovery URL. Used when the Policy Editor is set up in OIDC mode.

PING_SCOPE

openid email profile additional_scope

Space-separated OIDC scopes that the Policy Editor requests during authorization and validates during token verification. Used to override the requested OIDC scopes configured during server setup.

PING_OIDC_TLS_VALIDATION

NONE

The OIDC Transport Layer Security (TLS) validation setting. Set to NONE to configure the Policy Editor to accept self-signed SSL certificates from the OIDC provider and skip hostname verification.

Used when the Policy Editor is set up in OIDC mode. For non-production use only.

PING_CLIENT_ID

8cb9f2c9-c366-47e0-9560-db2132b2d813

The Policy Editor’s client ID with the OIDC provider. Used when the Policy Editor is set up in OIDC mode.

PING_USERNAMES

admin, user1, user2

Used in demo mode. A comma-separated list of usernames accepted by the Policy Editor for sign on.

PING_H2_FILE

./Symphonic

The path to the policy database H2 file.

Leave off the .mv.db extension.

PING_DB_APP_USERNAME

db_user

The username the application uses to access the server database.

PING_DB_APP_PASSWORD

Pa$$w0rd!23

The password the application uses to access the server database.

PING_DB_ADMIN_USERNAME

db_admin

The username the setup tool uses when upgrading the policy database (H2 only).

PING_DB_ADMIN_PASSWORD

$3cr3T

The password the setup tool uses when upgrading the policy database (H2 only).

PING_OPTIONS_FILE

/path/to/options.yml

The path to an options.yml file to use with the Policy Editor's setup tool.

PING_ADMIN_PORT

9444

The admin port where the H2 database backup endpoint is available.

The policy administration point (PAP) uses this endpoint to back up the H2 database, which stores your Trust Framework, policies, commit history, and other data.

Related environment variables: PING_BACKUP_SCHEDULE, PING_H2_BACKUP_DIR

PING_BACKUP_SCHEDULE

0 0 0 * * ?

The periodic database backup schedule for the Policy Editor (also known as the PAP) in the form of a cron expression.

Note:

The PAP evaluates the expression against the system timezone. For the PingAuthorize Docker images, the default timezone is UTC.

The default is 0 0 0 * * ?, which is midnight every day.

For more information, see Quartz 2.3.0 cron format.

Related environment variables: PING_ADMIN_PORT, PING_H2_BACKUP_DIR

PING_H2_BACKUP_DIR

/opt/out/backup

The directory in which to place the H2 database backup files.

The default is SERVER_ROOT/policy-backup.

Related environment variables: PING_ADMIN_PORT, PING_BACKUP_SCHEDULE

PING_ENABLE_API_HTTP_CACHE

false

Controls the API HTTP caching feature for the run-time instance of the server. APIs are cached by default.

Provide this environment variable at run time and set it to false to disable API HTTP caching for that server instance.

PING_DISABLE_SNI_HOSTNAME_CHECKS

false

 Determines whether PingAuthorize performs SNI hostname checks. By default, these checks are disabled.

Example: Use an existing SSL certificate for HTTPS connections

This example shows how to provide the environment variables necessary for the Policy Editor to present a different SSL certificate than the one configured during setup:

env PING_CERT_ALIAS=<certificate-nickname> \
PING_KEYSTORE_PATH=<path-to-keystore-file> \
PING_KEYSTORE_TYPE=<PKCS12-or-JKS> \
KEYSTORE_PIN_FILE=<path-to-keystore-pin-file> \
bin/start-server

Example: Override the configured HTTPS port

In this example, the Policy Editor is started using an HTTPS port that differs from the value configured during installation. The override requires two environment variables: PING_PORT and PING_EXTERNAL_BASE_URL.

$ bin/stop-server
$ export PING_PORT=9443 PING_EXTERNAL_BASE_URL=pap.example.com:9443; bin/start-server

Example: Override the configured policy database location

This example changes the policy database location. The new value must be a policy server Java database connectivity (JDBC) connection string for an H2 embedded database. To use a file located at /opt/shared/Symphonic.mv.db, use the following commands:

$ bin/stop-server
$ export PING_H2_FILE=/opt/shared/Symphonic
$ bin/setup demo {ADDITIONAL_ARGUMENTS} && bin/start-server
Note:

Even though the actual filename of the policy database includes the extension .mv.db, the JDBC connection string excludes the extension.

If /opt/shared/Symphonic.mv.db does not exist, setup creates a new one. If the file does exist and is from an older PingAuthorize server, setup updates the file to the latest version.

Troubleshooting startup errors

The bin/start-server command prints an error message if it detects that an error has occurred during startup. For more information about the error, see the logs/authorize-pe.log and logs/start-server.log files.