For an automated software installation, run PingAuthorize Policy Editor setup in the noninteractive command-line interface (CLI) install mode.
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.
Click the following tabs for examples of the setup command in different authentication modes.
- After you complete setup, see Post-setup steps (manual installation).
- 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 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.