Getting started

The following provides guidance on preparing a PingFederate deployment for Terraform access.

Requirements

Terraform CLI 1.4+
A running PingFederate server accessible over HTTPS, or Docker CLI to start one.
If using Docker to start a PingFederate server, you must have a DevOps license. 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. The provider can be used with any PingFederate server.

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 Docker Hub.
```
docker run --name pingfederate_terraform_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_terraform_provider_container
```

After you see the following message in the container logs, the server is ready to receive requests from the provider:

PingFederate is up

Accessing the PingFederate API

Gaining access to the API depends on where your PingFederate instance is running. In order to work with the API, you need to authenticate just as you would for performing administrative tasks. To interact directly with the API in the browser and view the documentation, you would typically go 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.

If you’re using OIDC, you can find information on how to connect in OIDC authentication in the PingFederate documentation.

When using a local container as shown above, the port mappings result in PingFederate being available at https://localhost:9999/pingfederate/app#/ by default. The provider supports an attribute admin_api_path 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 the provider to use it.

The PingFederate Terraform provider applies configuration at the API endpoints using the specified port (9999) over HTTPS when accessing the product locally under Docker.

Determine credentials that are able to configure the server

The provider supports basic authentication, OAuth2 client credentials flow authentication, and access token authentication for connection to the configuration API. In this example, basic authentication will be used.

When using basic authentication, the provider will need the username and password of a user with permission to manage server configuration.

When using the Ping Identity Docker images, the default username and password can be used. Learn more in Deploy an Example Stack in the Ping Identity DevOps documenation.

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

When using an access token, only access_token is required in the provider configuration.

You can find examples of configuring other authentication methods in the Terraform registry documentation.

Determine what version of PingFederate you’re running

The provider requires that the version of PingFederate is specified.

You can do this one of two ways:

Using the product_version attribute when configuring the provider:
```
provider "pingfederate" {
  ...
  product_version = "12.1"
}
```
Setting the PINGFEDERATE_PROVIDER_PRODUCT_VERSION environment variable to the version of PingFederate you’re running:
```
export PINGFEDERATE_PROVIDER_PRODUCT_VERSION=12.1
```

If using the container, you can view the product version using by running a shell in the container and searching for the appropriate environment variable:

docker container exec -it pingfederate_terraform_provider_container /bin/sh

Next, in the container shell, get the version:

env | grep PING_PRODUCT_VERSION

The product_version provider configuration attribute takes precedence over the PINGFEDERATE_PROVIDER_PRODUCT_VERSION environment variable.

If neither is set, the provider will throw an error.

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 be replaced with a custom certificate. The provider has a few ways of configuring trust for the HTTPS connection with the server.

By default, the provider will trust the host’s default root certificate authority (CA) set when connecting to the server.

If you need to provide CA certificates for the provider to trust, you can use the ca_certificate_pem_files attribute. This attribute supports providing a set of paths to files containing PEM-encoded CA certificates to be trusted.

You can also use the PINGFEDERATE_PROVIDER_CA_CERTIFICATE_PEM_FILES environment variable, with commas to delimit multiple PEM file paths if necessary.

Finally, the provider supports an insecure_trust_all_tls boolean attribute that enables it to trust all certificates when connecting to the server.

The insecure_trust_all_tls provider flag, when set to true, is insecure and is intended for development and testing only. You should not enable this option for production use.

Use the provider to configure PingFederate

You are now ready to configure the PingFederate server using the provider.

You can find examples on configuring the Terraform provider to manage PingFederate configuration in the PingFederate Provider Registry documentation.

Configuration Automation - Terraform