Installing the Policy Editor non-interactively

For an automated software installation, run bin/setup in non-interactive command-line interface (CLI) mode.

You must run bin/setup in non-interactive CLI mode instead of interactive mode to do any of the following:

Configure the Policy Editor with a policy configuration key.
Configure a key store for a policy information provider.
Configure a trust store for a policy information provider.
Customize the Policy Editor’s logging behavior.
Configure the Policy Editor for a PostgreSQL database.
Configure the Policy Editor to present an existing SSL certificate instead of generating a self-signed certificate.
Enable self-governance.
Enable Camel services.

Learn more in Specifying custom configuration with an options file.

Before you begin

To use a PostgreSQL policy database, you must set up the database before you install the Policy Editor.

After you set up your PostgreSQL policy database, save the following information for installing the Policy Editor:

The PostgreSQL JDBC connection string, with the host, port, and database name
The server runtime credential provided through the policy-db tool

Steps

Choose one of the following authentication modes for the Policy Editor:

Demo mode: Configures the Policy Editor to use form-based authentication with a fixed set of credentials. Unlike OIDC mode, this mode doesn’t require an external authentication server.

This mode is inherently insecure. You should only use it for demonstration purposes.

OIDC mode: Configures the Policy Editor to delegate authentication and sign-on services to an OIDC provider, such as PingFederate.

If you choose OIDC mode, you must provide the host name and port of an OIDC provider or its base URL.

If you don’t use the setup tool to generate a self-signed certificate, you must also provide information related to the Policy Editor’s connection security, including the location of a keystore that contains the server certificate and the certificate’s nickname.

If the OIDC provider presents a certificate that isn’t trusted by the Policy Editor’s Java Runtime Environment (JRE), do one of the following:

Add the certificate to the JRE trust store. Learn more in Configuring an OIDC provider for single sign-on requests from PingAuthorize.
Disable certificate validation by starting the Policy Editor with the PING_OIDC_TLS_VALIDATION environment variable set to NONE.

The setup tool’s --help option displays the options available for a non-interactive installation.

The following table describes the available CLI help options for the setup tool:

CLI help options

Command Description

$ bin/setup --help

General options for running setup

$ bin/setup demo --help

Options for running setup in demo mode

$ bin/setup oidc --help

Options for running setup in OIDC mode

Run the bin/setup command with the appropriate authentication mode, as shown in Authentication mode examples.
1. (Optional) If you’re using a PostgreSQL policy database, pass the server runtime username to --dbAppUsername.
  
  If you don’t want to use the default database credentials for your H2 policy database, refer to Setting database credentials at initial setup.
Copy and record any generated values needed to configure external servers.

The shared secret is used in the PingAuthorize admin console, under External Servers > Policy External Server > Shared Secret.
Run bin/start-server to start the Policy Editor.

The Policy Editor runs in the background, so you can close the terminal window in which it was started without interrupting it.
1. (Optional) If you’re using a PostgreSQL policy database, provide the server runtime password value you used to create the database to the PING_DB_APP_PASSWORD environment variable before starting the server.

Next steps

Complete the post-setup steps.
Consider additional configuration options for the Policy Editor.

Authentication mode examples

Click the following tabs for examples of the setup command in different authentication modes.

Example: Set up the PingAuthorize Policy Editor in OIDC mode (PingFederate)

Use this example as a reference to set up the PingAuthorize Policy Editor for sign-ons using a PingFederate OIDC provider:

$ bin/setup oidc \
  --oidcHostname  <ping-federate-hostname>  \
  --oidcPort  <ping-federate-port>  \
  --clientId pingauthorizepolicyeditor \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

The Policy Editor uses the provided OIDC host name and OIDC to query the PingFederate server’s autodiscovery endpoint for the information it needs to make OIDC requests. The provided client ID represents the Policy Editor and must be configured in PingFederate.

The Policy Editor can skip host name verification and accept self-signed SSL certificates from the OIDC provider.

The following example uses the PING_OIDC_TLS_VALIDATION environment variable to set up the Policy Editor to handle sign-ons for a provider using a self-signed certificate:

$ env PING_OIDC_TLS_VALIDATION=NONE bin/setup oidc \
  --oidcHostname  <ping-federate-hostname>  \
  --oidcPort  <ping-federate-port>  \
  --clientId pingauthorizepolicyeditor \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

For more information about configuring PingFederate, see Configuring an OIDC provider for single sign-on requests from PingAuthorize.

Example: Set up the PingAuthorize Policy Editor in OIDC mode (generic OIDC provider)

This example sets up the PingAuthorize Policy Editor for sign-ons using an arbitrary OIDC provider.

This example departs from the PingFederate example by specifying the OIDC provider’s base URL, rather than a host name and port. This can be useful if the OIDC provider’s autodiscovery and authorization endpoints include an arbitrary prefix, such as a customer-specific environment identifier.

$ bin/setup oidc \
  --oidcBaseUrl https://auth.example.com/9595f417-a117-3f24-a255-5736ab01f543/auth/ \
  --clientId 7cb9f2c9-c366-57e0-9560-db2132b2d813 \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

The Policy Editor uses the provided OIDC base URL to query the OIDC provider’s autodiscovery endpoint for the information it needs to make OIDC requests. The provided client ID represents the Policy Editor and must be configured in the OIDC provider as well.

The Policy Editor can skip host name verification and accept self-signed SSL certificates from the OIDC provider.

The following example uses the PING_OIDC_TLS_VALIDATION environment variable to set up the Policy Editor to handle sign-ons for a provider using a self-signed certificate:

$ env PING_OIDC_TLS_VALIDATION=NONE bin/setup oidc \
  --oidcBaseUrl https://auth.example.com/9595f417-a117-3f24-a255-5736ab01f543/auth/ \
  --clientId 7cb9f2c9-c366-57e0-9560-db2132b2d813 \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

For more information about configuring an OIDC provider, see Configuring an OIDC provider for single sign-on requests from PingAuthorize.

Example: Set up the PingAuthorize Policy Editor in OIDC mode (custom scope)

This example sets up the PingAuthorize Policy Editor for sign-ons using OIDC with one or more custom scopes.

In OIDC mode, the Policy Editor UI requests an access token with the following default scopes: openid email profile. You can change the default requested scopes persistently, during server setup, or on a one-time basis, at server startup.

Add OIDC scopes during setup

To add requested OIDC scopes persistently, use the --scope option to provide a space-separated list of scopes to the setup command.

$ bin/setup oidc \
  --oidcBaseUrl https://auth.example.com/02fa3993-a851-4eb5-96c7-f0c561be23c6/auth/ \
  –-clientId 21a74125-85db-4fca-8a56-e5d45d4d8163 \
  --scope "openid email profile  <additional_scope>" \
  --generateSelfSignedCertificate \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

The Policy Editor can skip host name verification and accept self-signed SSL certificates from the OIDC provider. The following example uses the PING_OIDC_TLS_VALIDATION environment variable to set up the Policy Editor to handle sign-ons for a provider using a self-signed certificate:

$ env PING_OIDC_TLS_VALIDATION=NONE bin/setup oidc \
  --oidcBaseUrl https://auth.example.com/02fa3993-a851-4eb5-96c7-f0c561be23c6/auth/ \
  –-clientId 21a74125-85db-4fca-8a56-e5d45d4d8163 \
  --scope "openid email profile  <additional_scope>" \
  --generateSelfSignedCertificate \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

Add OIDC scopes at startup

To override persistently requested OIDC scopes for a single runtime instance of the Policy Editor, use the PING_SCOPE environment variable to provide a space-separated list of scopes to the start-server command:

$ env PING_SCOPE="openid email profile  <different_scope>" bin/start-server

For more information about configuring an OIDC provider, see Configuring an OIDC provider for single sign-on requests from PingAuthorize.

Example: Set up the PingAuthorize Policy Editor in OIDC mode (self-governance)

This example sets up the PingAuthorize Policy Editor with self-governance and OIDC authentication.

You can find information about configuring OIDC authentication on the OIDC mode (generic) tab on this page.

Self-governance isn’t supported in clustered Policy Editor configurations.

To enable self-governance with OIDC authentication, use the following arguments when running the bin/setup command:

--enableSelfGovernance (required): Enables self-governance functionality.
--selfGovernanceSystemUsername (required): Sets the username of the self-governance administrator for OIDC authentication. To specify multiple self-governance administrators, provide a comma-separated list of usernames.
--apiHttpCacheTtl (optional): Sets the time-to-live (TTL) value (in seconds) for the HTTP cache, after which the cache is refreshed and a new self-governance check is performed. This value must be 1 or greater.

If you don’t specify a value, the Policy Editor uses the default TTL of 60 seconds.

The following example sets up the Policy Editor to use PingOne for OIDC authentication, enables self-governance, and specifies an OIDC username for the self-governance administrator:

$ bin/setup oidc \
--hostname localhost \
--port 9443 \
--adminPort  <admin-port>  \
--oidcBaseUrl https://auth.pingone.com/<your-environment-id>/as \
--clientId  <your-client-id>  \
--generateSelfSignedCertificate \
--enableSelfGovernance \
--selfGovernanceSystemUsername  <oidc-authenticated-user>

To specify multiple self-governance administrators, provide a comma-separated list of usernames:

$ bin/setup oidc \
--hostname localhost \
--port 9443 \
--adminPort  <admin-port>  \
--oidcBaseUrl https://auth.pingone.com/<your-environment-id>/as \
--clientId  <your-client-id>  \
--generateSelfSignedCertificate \
--enableSelfGovernance \
--selfGovernanceSystemUsername <admin-user-1>,<admin-user-2>

Example: Set up the PingAuthorize Policy Editor in demo mode

This example sets up the PingAuthorize Policy Editor in demo mode with an automatically-generated self-signed server certificate.

After completing setup, the Policy Editor will accept sign-ons using the username admin and the password password123.

$ bin/setup demo \
  --adminUsername admin \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

The decision point shared secret is a credential that the PingAuthorize Server uses to authenticate to the Policy Editor when it uses the Policy Editor as an external policy decision point (PDP).

For information about how to configure PingAuthorize Server to use the decision point shared secret, see Post-setup steps (manual installation).

Example: Set up the PingAuthorize Policy Editor with a PostgreSQL policy database

This example sets up the PingAuthorize Policy Editor in demo mode with the following options:

Automatically generated self-signed server certificate
PostgreSQL policy database with server runtime credentials (see the following caution about --dbAppPassword)

$ bin/setup demo \
  --dbConnectionString "jdbc:postgresql://<host>:<port>/<database>" \
  --dbAppUsername "<db-user>" \
  --dbAppPassword "<db-password>" \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

Using the --dbAppPassword option to provide the PostgreSQL database password to the setup tool persists the password to a configuration file.

Instead, omit --dbAppPassword entirely to persist the default password, and set the PING_DB_APP_PASSWORD environment variable before server start. For example:

$ env PING_DB_APP_PASSWORD=<db-password>  bin/start-server

Example: Set up the PingAuthorize Policy Editor to use a custom SSL certificate

This example sets up the PingAuthorize Policy Editor in demo mode with a provided SSL server certificate in PKCS12 format:

$ env KEYSTORE_PIN_FILE=<path-to-keystore.pin>  bin/setup demo
  --adminUsername admin \
  --pkcs12KeyStorePath  <path-to-keystore.p12>  \
  --certNickname  <certificate-nickname>  \
  --decisionPointSharedSecret  <shared-secret>  \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>

If you don’t use the KEYSTORE_PIN_FILE during setup, you can supply the --keystorePassword option.

The following information describes the previous example code block:

The KEYSTORE_PIN_FILE environment variable, along with the --pkcs12KeyStorePath and --certNickname command-line options, affect the server’s SSL certificate configuration.
KEYSTORE_PIN_FILE contains the path to a file containing a valid key store PIN value.
The --pkcs12KeyStorePath value is a path to a valid PKCS12 key store file.
The --certNickname value is the certificate nickname or alias.

The PingAuthorize Policy Editor only supports lowercase certificate nicknames.
Because the KEYSTORE_PIN_FILE is not persisted, it must also be available in the environment of start-server.

Example: Set up the PingAuthorize Policy Editor in demo mode (self-governance)

This example sets up the PingAuthorize Policy Editor in demo mode with self-governance enabled.

For more information about setting up the Policy Editor in demo mode, click the Demo mode tab on this page.

To enable self-governance in demo mode, use the --enableSelfGovernance argument. The following values are set by default:

The time-to-live value for the HTTP cache is set to 60 seconds, after which the cache is refreshed and a new self-governance check is performed.
The self-governance administrator username is set to selfgovernanceadmin.
The self-governance administrator password is set to password123.

The following example sets up the Policy Editor in demo mode with self-governance enabled:

$ bin/setup demo \
--adminUsername admin \
--enableSelfGovernance \
--generateSelfSignedCertificate \
--licenseKeyFile /opt/PingAuthorize/PingAuthorize.lic \
--decisionPointSharedSecret pingauthorize \
--hostname localhost \
--port 9443 \
--adminPort  <admin-port>