Installing the PingAuthorize Policy Editor non-interactively - PingAuthorize - 10.1

PingAuthorize 10.1
bundle
pingauthorize-101
ft:publication_title
PingAuthorize 10.1
Product_Version_ce
PingAuthorize 10.1 (Latest)
category
ContentType
Product
Productdocumentation
paz-101
pingauthorize
ContentType_ce
Product documentation

For an automated software installation, run PingAuthorize Policy Editor setup in the non-interactive command-line interface (CLI) install mode.

Note:

You must run setup in non-interactive 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.
  • Enable self-governance.
  • Enable Camel services.

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:

  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 key store 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 Java Runtime Environment (JRE), do one of the following:

    Tip:

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

  3. Run the setup command with the appropriate authentication mode, as illustrated in the following authentication mode example tabs.
    1. Optional: If you're using a PostgreSQL policy database, provide the server runtime user value you used to create the database to --dbAppUsername as part of the setup command.
    2. Optional: Explore the CLI help documentation for the setup command.
    OptionCommand

    View the general options for running setup.

    		 $ bin/setup --help

    View the options for running setup in demo mode.

    		 $ bin/setup demo --help

    View the options for running setup in OIDC mode.

    		 $ bin/setup oidc --help
    Note:

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

  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.

    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 server start.

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 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 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/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.

For more information about configuring OIDC authentication, see the OIDC mode (generic) tab on this page.

Note:

Self-governance is not supported in clustered Policy Editor configurations.

To enable self-governance with OIDC authentication, use the following arguments:

--enableSelfGovernance (required)
Turns on the self-governance functionality.
--selfGovernanceSystemUser (required)
Sets the self-governance administrator username for OIDC authentication.
--apiHttpCacheTtl (optional)

Sets the time-to-live 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.

Note:

If you don't specify a value, the Policy Editor uses the default time-to-live 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/<my-environment-id>/as \
--clientId <my-client-id> \
--generateSelfSignedCertificate \
--enableSelfGovernance \
--selfGovernanceSystemUsername <oidc-authenticated-user>

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>
CAUTION:

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>
Note:

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.
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.

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>