Installing the PingAuthorize Policy Editor noninteractively - PingAuthorize - 9.1

PingAuthorize
bundle
pingauthorize-91
ft:publication_title
PingAuthorize
Product_Version_ce
PingAuthorize 9.1
category
ContentType
Product
Productdocumentation
paz-91
pingauthorize
ContentType_ce
Product documentation

For an automated software installation, run PingAuthorize Policy Editor setup in the noninteractive CLI install mode.

Note:

You must run setup in noninteractive command-line mode instead of interactive mode if you need 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.

For more information, see Specifying custom configuration with an options file.

  1. Optional: If you choose 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, be prepared to provide the following information when installing the Policy Editor:

    • PostgreSQL Java Database Connectivity (JDBC) connection string, with the host, port, and database name
    • The PostgreSQL user and password for the application to use when accessing the database
  2. Choose the authentication mode for the PingAuthorize Policy Editor:

    • Demo mode: Configures the PingAuthorize Policy Editor to use form-based authentication with a fixed set of credentials. Unlike OpenID Connect (OIDC) mode, this mode doesn't require an external authentication server. However, it's inherently insecure and should only be used for demonstration purposes.

    • OIDC mode: Configures the PingAuthorize 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.

      Note:

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

      If the OIDC provider presents a certificate that is not trusted by the Policy Editor's JRE, do one of the following:

    Tip:

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

  3. Run the correct command based on your needs (see the tabs below for examples of the setup command in different authentication modes):
    Note:

    If you don't want to use the default database credentials for your H2 policy database, see Setting database credentials at initial setup.

    • To see the general options for running setup:

      $ bin/setup --help

    • To see the options for running setup in demo mode:

      $ bin/setup demo --help

    • To see the options for running setup in OIDC mode:

      $ bin/setup oidc --help
  4. Copy and record any generated values needed to configure external servers.

    The Shared Secret is used in PingAuthorize, under External Servers > Policy External Server > Shared Secret.

  5. To start the Policy Editor, or policy administration point (PAP), run bin/start-server.

    The Policy Editor runs in the background, so you can close the terminal window in which it was started without interrupting it.

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

  1. After you complete setup, see Post-setup steps (manual installation).
  2. Consider additional configuration options in Specifying custom configuration with an options file.

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 OpenID Connect (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 hostname verification and accept self-signed SSL certificates from the OIDC provider.

This 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 OpenID Connect (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 hostname verification and accept self-signed SSL certificates from the OIDC provider.

This 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 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 an automatically generated self-signed server certificate and a PostgreSQL policy database.

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

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

Instead, run the following command to populate the PING_DB_APP_PASSWORD environment variable at server start.

$ env PING_DB_APP_PASSWORD=<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>
Note:

If you don't use the KEYSTORE_PIN_FILE during setup, you can supply the --keystorePassword argument.

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.
Warning:
  • 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.