Configuration Automation - Ping CLI

Connect PingFederate to Ping CLI

The following guide provides guidance on how to connect a PingFederate deployment to Ping CLI.

Requirements

  • A running PingFederate server accessible over HTTPS or Docker CLI to start one

  • If using Docker to start a PingFederate server, a DevOps license is required. Register for the DevOps program here

(Optional) Start a PingFederate Docker container

If you already have a running PingFederate server that you can reach over HTTPS, you can skip this step. You can use Ping CLI with any supported PingFederate server.

First, start a PingFederate server. The following example shows how to start a single PingFederate server using Docker.

Your DevOps credentials will be read from the .pingidentity/config file in the user’s home directory. The HTTPS port (default 9999) must be exposed. This example starts the product with the getting-started/pingfederate server profile, running the latest version of PingFederate from the Docker Hub.

docker run --name pingfederate_pingcli_provider_container \
  -d -p 9031:9031 \
  -d -p 9999:9999 \
  --env-file "${HOME}/.pingidentity/config" \
  -e SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git \
  -e SERVER_PROFILE_PATH=getting-started/pingfederate
  pingidentity/pingfederate:latest

After starting the container, follow the logs until the server becomes available.

docker logs -f pingfederate_pingcli_provider_container

After the following message displays in the container logs, the server is ready to receive requests from Ping CLI:

PingFederate is up

Accessing the PingFederate API

Gaining access to the API depends on where your PingFederate instance is running. To work with the API, you need to authenticate as you would for performing administrative tasks. To interact directly with the API in the browser and view the documentation, you would browse to the following URL:

https://<pf_host>:9999/pf-admin-api/api-docs/

where <pf_host> is the network address of your PingFederate server. This target can be an IP address, a host name, or a fully qualified domain name. It must be reachable from your computer. When using a local container as previously shown, the port mappings result in PingFederate being available on port 9999 by default. Ping CLI manages configuration at the API endpoints using the specified port (9999) over HTTPS when accessing the product locally under Docker.

The administration API base URL is configurable in Ping CLI using the service.pingfederate.httpsHost configuration key:

pingcli config set "service.pingfederate.httpsHost=https://localhost:9999"

Ping CLI supports the ability to set the default admin API path with the service.pingfederate.adminAPIPath configuration key, which defaults to /pf-admin-api/v1. If your environment has a load balancer or other network configuration that requires a different path to the API, you can configure Ping CLI to use it as shown in the example.

pingcli config set "service.pingfederate.adminAPIPath=/my/custom/admin/api/path"

Configure Ping CLI with PingFederate authentication details

Ping CLI supports basic authentication, OAuth2 client credentials flow authentication, and access token authentication for connection to the PingFederate configuration API.

Follow the appropriate section for your deployment.

OAuth 2.0 client credentials

When using OAuth2 client credentials, the client_id, client_secret, and token_url attributes are required in Ping CLI configuration, with scopes being optional.

If using OIDC, refer to the OIDC Authentication page for more information.

Run the following Ping CLI commands, replacing the following configuration key values:

  • service.pingfederate.authentication.clientCredentialsAuth.clientID with the Client ID value of the OAuth 2.0 client used to connect to the PingFederate administration API

  • service.pingfederate.authentication.clientCredentialsAuth.clientSecret with the Client Secret value of the OAuth 2.0 client used to connect to the PingFederate administration API

  • service.pingfederate.authentication.clientCredentialsAuth.scopes with a comma separated list of any scope values required for the OAuth 2.0 client to use the PingFederate administration API

  • service.pingfederate.authentication.clientCredentialsAuth.tokenURL with the Token URL value that PingFederate must use to gain an access token using the provided client credentials

pingcli config set "service.pingfederate.authentication.clientCredentialsAuth.clientID=***"
pingcli config set "service.pingfederate.authentication.clientCredentialsAuth.clientSecret=***"
pingcli config set "service.pingfederate.authentication.clientCredentialsAuth.scopes=openid,profile"
pingcli config set "service.pingfederate.authentication.clientCredentialsAuth.tokenURL=https://my-token-endpoint.bxretail.org/as/token"
pingcli config set "service.pingfederate.authentication.type=clientCredentialsAuth"

Optionally, the PingFederate service can be configured against a custom configuration profile using the --profile option flag (or the short code flag -P). Learn more in Managing Configuration Profiles.

Ping CLI is now configured with the PingFederate service using OAuth 2.0 client credentials.

HTTP basic authentication

When using basic authentication, Ping CLI needs the username and password of a user with permission to manage server configuration.

When using the Ping Identity Docker images, you can use the default username and password. Learn more in Deploy an Example Stack.

Run the following Ping CLI commands, replacing the following configuration key values:

  • service.pingfederate.authentication.basicAuth.username with the Administrator Username value for an active PingFederate administrator

  • service.pingfederate.authentication.basicAuth.password with the Administrator Password value for an active PingFederate administrator

pingcli config set "service.pingfederate.authentication.basicAuth.username=***"
pingcli config set "service.pingfederate.authentication.basicAuth.password=***"
pingcli config set "service.pingfederate.authentication.type=basicAuth"

Optionally, the PingFederate service can be configured against a custom configuration profile using the --profile option flag (or the short code flag -P). Learn more in Managing Configuration Profiles.

Ping CLI is now configured with the PingFederate service using OAuth 2.0 client credentials.

Trusting PingFederate certificates

PingFederate generates a self-signed certificate by default, which is presented by the server when connecting. The default self-signed certificate can also be replaced with a custom certificate. Ping CLI has a couple of ways of configuring trust for the HTTPS connection with the server.

By default, Ping CLI trusts the host’s default root CA set when connecting to the server.

If you need to provide CA certificates for Ping CLI to trust, you can use the service.pingfederate.caCertificatePemFiles configuration key. This attribute supports providing a set of paths to files containing PEM-encoded CA certificates to be trusted.

pingcli config set "service.pingfederate.caCertificatePemFiles=/path/to/ca1.pem,/path/to/ca2.pem"

Finally, if using self signed certificates (for example, when using a local Docker container), configure the service.pingfederate.insecureTrustAllTLS configuration key to enable Ping CLI to trust any certificate (regardless of whether the issuer is trusted or untrusted) when connecting to the server.

The service.pingfederate.insecureTrustAllTLS configuration key, when set to true, is insecure and is intended for development and testing only. You shouldn’t enable this option for production use. 
pingcli config set "service.pingfederate.insecureTrustAllTLS=true"