--- title: Getting started description: The following provides guidance on preparing a PingDirectory deployment for Terraform access. component: terraform page_id: terraform::products/pingdirectory/getting_started canonical_url: https://developer.pingidentity.com/terraform/products/pingdirectory/getting_started.html revdate: March 19, 2025 section_ids: requirements: Requirements start-pingfederate-docker-container: (Optional) Start a PingDirectory Docker container enable-configuration-http-servlet: Ensure the Configuration HTTP Servlet extension is enabled determine-server-port: Determine what port the server is using for HTTPS connections determine-credentials: Determine credentials that are able to configure the server determine-version: Determine what version of PingDirectory you are running trusting-pingdirectory-certificates: Trusting PingDirectory certificates use-the-provider-to-configure-pingdirectory: Use the provider to configure PingDirectory --- # 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.](https://devops.pingidentity.com/how-to/devopsRegistration/) ## (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. | 1. 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. ```console 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 ``` 2. After starting the container, follow the logs until the server becomes available. ```console 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: ```console 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: ```console 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](https://devops.pingidentity.com/get-started/getStartedExample/). | ## 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: ```console 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: ```console 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](https://registry.terraform.io/providers/pingidentity/pingdirectory/latest/docs).