Getting started

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

Requirements

Terraform CLI 1.1+
A running PingDirectory server accessible over HTTPS, or Docker CLI to start one.
When using Docker to start a PingDirectory server, you must have a DevOps license. Register for the DevOps program here.

(Optional) Start a PingDirectory Docker container

If you already have a running PingDirectory server that you can reach over HTTPS, you can skip this step. The provider can be used with any PingDirectory server.

Start a PingDirectory server. The following example shows how to start a single PingDirectory server using Docker.

Your DevOps credentials will be read from the .pingidentity/config file in the user’s home directory. The HTTPS port (default 1443) must be exposed.
```
docker run --name pingdirectory_terraform_provider_container \
		-d -p 1443:1443 \
		-d -p 1389:1389 \
		-e TAIL_LOG_FILES= \
		--env-file "${HOME}/.pingidentity/config" \
		pingidentity/pingdirectory:latest
```
After starting the container, follow the logs until the server becomes available.
```
docker logs -f pingdirectory_terraform_provider_container
```

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

Setting Server to Available

Ensure the Configuration HTTP Servlet extension is enabled

The PingDirectory Terraform provider applies configuration using the Configuration HTTP servlet extension, which must be enabled for the server’s HTTPS connection handler.

This setting is already configured by default in PingDirectory, including when running in Docker.

If you’ve disabled the Configuration HTTP servlet extension on your server, you can re-enable it with dsconfig:

dsconfig set-connection-handler-prop --handler-name "HTTPS Connection Handler" --add http-servlet-extension:Configuration

Determine what port the server is using for HTTPS connections

The PingDirectory Docker image uses port 1443 for HTTPS by default.

To determine what port you’re using, use the status command and examine the output for a block containing the HTTPS port:

dsconfig status

          --- Connection Handlers ---
Address:Port : Protocol : State    : Name
-------------:----------:----------:-------------------------
0.0.0.0:1389 : LDAP     : Enabled  : LDAP Connection Handler
0.0.0.0:1443 : HTTPS    : Enabled  : HTTPS Connection Handler
0.0.0.0:1636 : LDAPS    : Enabled  : LDAPS Connection Handler

Determine credentials that are able to configure the server

The Configuration API used by the provider uses basic authentication. The provider will need the username and password of a user that has permissions 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.

Determine what version of PingDirectory you are running

The provider requires that the version of PingDirectory is specified through the product_version attribute or the PINGDIRECTORY_PROVIDER_PRODUCT_VERSION environment variable.

You can view the product version using the status command. Look for the Server Details section:

dsconfig status

          --- Server Details ---
Host Name:            ...
Instance Name:        ...
Administrative Users: cn=administrator
Installation Path:    /opt/out/instance
Server Version:       Ping Identity Directory Server 9.2.0.0

Trusting PingDirectory certificates

PingDirectory generates a self-signed certificate by default, which is presented by the server’s HTTPS connection handler. You can replace the default self-signed certificate 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.

The provider also supports an insecure_trust_all_tls boolean attribute (configurable with environment variable PINGDIRECTORY_PROVIDER_INSECURE_TRUST_ALL_TLS) that allows simply trusting all certificates when connecting to the server. This option is insecure and should not be used in production.

If you need to provide CA certificates for the provider to trust, you can use the ca_certificate_pem_files attribute. This attribute allows you to provide a set of paths to files containing PEM-encoded CA certificates to be trusted. The PINGDIRECTORY_PROVIDER_CA_CERTIFICATE_PEM_FILES environment variable can also be used, with commas to delimit multiple PEM file paths if necessary.

If you want to trust the default self-signed certificate of the PingDirectory server, you can export the certificate from the server’s keystore using the manage-certificates command-line tool.

Write the output of that command to a file. Then you can include the path to that file in the ca_certificate_pem_files attribute when using the provider. The following example uses cert.pem as the filename:

manage-certificates export-certificate --keystore config/keystore --alias server-cert > cert.pem

Use the provider to configure PingDirectory

You are now ready to configure the PingDirectory server with the provider.

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

Configuration Automation - Terraform