Rate this page

Quick start

The instructions in this quick start guide will help you to get up and running quickly with a copy of the Ping Identity Data Governance Server using a sample configuration. Note that this is not a deployment guide! If you require detailed instructions and information about advanced options, please consult the Ping Identity Directory Server Administration Guide and the Ping Identity Data Governance Server Administration Guide.

Installation

To install the Ping Identity Data Governance Server in a development environment, you’ll need these:

  • An Oracle JDK or OpenJDK installation, version 7 or higher.
  • The Ping Identity Directory Server zip distribution.
  • The Ping Identity Data Governance Server zip distribution.
  • A minimum of 1.5 GB free RAM.

We’ll use the command line to perform the installation, but no particular expertise is required. You’ll simply need to copy and paste a few commands.

Install the JDK

Both the Ping Identity Directory Server and the Ping Identity Data Governance Server require JDK 7 or higher. For the most current list of supported Java versions, check the Ping Identity Customer Support Center portal or contact an authorized support provider.

The installation procedure varies depending on your platform and JDK vendor. See these instructions for installing the Oracle JDK 8 and these instructions for installing OpenJDK 8. Note that you can install multiple JDKs on a single system. If your system comes with a JDK installation by default, it can still be helpful to use a dedicated installation of the JDK for the Directory Server and Data Governance Server so that you can update it without affecting other Java applications.

After you’ve installed a JDK, you should set the JAVA_HOME environment variable to your JDK’s root installation directory. For example, if your JDK was installed to the directory /usr/local/java/jdk8, you might use the following command:

$ export JAVA_HOME=/usr/local/java/jdk8

On MacOS, JDKs are usually installed to the system’s /Library/Java/JavaVirtualMachines directory. The /usr/libexec/java_home tool can be used to echo the path to a particular JDK. Note the backticks in the following command.

$ export JAVA_HOME=`/usr/libexec/java_home -v 1.8`

About connection security and passwords

Let’s pause for a moment to emphasize the fact that we will be configuring servers for development and testing, so we’ll be taking some shortcuts with security.

Install the Ping Identity Directory Server

The Ping Identity Directory Server will be used to store user data, and at times, we’ll refer to it as the user store. It can be set up and configured with a myriad of options, but for tutorial purposes, we’ll keep the setup as simple as possible.

First, unzip the package containing the Directory Server files. The files will be unzipped to the PingDirectory subdirectory of the current directory.

$ unzip directory-6.1.0.0-GA-image.zip

Next, run the Directory Server’s setup command. This sets some important configuration values that the Directory Server needs to run its LDAP and HTTPS listeners, and it also starts the server itself.

$ PingDirectory/setup --cli --no-prompt --acceptLicense \
  --rootUserDN "cn=directory manager" --rootUserPassword password \
  --allowWeakRootUserPassword \
  --ldapPort 1389 --ldapsPort 1636 \
  --httpsPort 1443 --generateSelfSignedCertificate \
  --baseDN "dc=example,dc=com" \
  --maxHeapSize 512m --instanceName user-store

Some of the setup values that we’ve chosen here will be used later, when we configure the Data Governance Server to communicate with the Directory Server. Let’s note them right now.

DS setting Value Description
Root user DN cn=directory manager This is the name of the root administrative account.
Root user password password This is the root administrative account’s password. Because this is a test server, we used a weak password.
LDAPS port 1636 The port of the LDAPS (LDAP+SSL) listener.
Base DN dc=example,dc=com An identifier for the root of the directory information tree (DIT) under which user entries are stored.

To confirm that the Directory Server is running, you can run its status command. This will generate a voluminous amount of output, but you just need to look for a Server Run Status value of Started and an Operational Status value of Available.

$ PingDirectory/bin/status


>>>> Specify LDAP connection parameters

How do you want to connect to the Directory Server on localhost?

    1)  LDAP
    2)  LDAP with SSL

Enter option [1]:

Administrator user bind DN [cn=Directory Manager]:

Password for user 'cn=Directory Manager':

          --- Server Status ---
Server Run Status:    Started 03/Aug/2016:18:23:05.000 -0500
Uptime:               0 days 0 hours 1 minutes 15 seconds
Operational Status:   Available
Open Connections:     2
Max Connections:      2
Total Connections:    4
...

You will notice that you were prompted for some connection parameters. Both the Directory Server and the Data Governance Server provide administrative interfaces for status and configuration using the LDAP protocol. You log in to these interfaces using the root DN account that you created during setup, cn=Directory Manager.

Install the Ping Identity Data Governance Server

The first two steps of installing the Data Governance Server are very similar to the steps we took when installing the Data Governance Server. First, we unzip the package containing the Data Governance Server files, and this creates a subdirectory of the current directory called PingDataGovernance.

$ unzip broker-6.1.0.0-GA-image.zip

Next, we run the Data Governance Server’s setup command. This performs some minimal configuration needed to start the server, and then it starts the server.

$ PingDataGovernance/setup --no-prompt --acceptLicense --location Austin \
  --instanceName broker --ldapPort 8389 --ldapsPort 8636 \
  --httpsPort 8443 --generateSelfSignedCertificate \
  --rootUserDN "cn=directory manager" --rootUserPassword password \
  --allowWeakRootUserPassword \
  --maxHeapSize 1g

Ping Identity Data Governance Server 6.1.0.0

Initializing ..... Done
Configuring Data Governance Server ..... Done
Configuring Certificates ..... Done
Creating Encryption Settings ..... Done
Starting Data Governance Server ..... Done

Access product documentation from https://example.com:8443/docs/index.html

As we did before, let’s note some of the settings that we chose to use.

Data Governance Server setting Value Description
Root user DN cn=directory manager This is the name of the root administrative account.
Root user password password This is the root administrative account’s password. Because this is a test server, we used a weak password.
LDAPS port 8636 The port of the LDAPS (LDAP+SSL) listener.
HTTPS port 8443 The port of the HTTPS listener.

Configure the Data Governance Server

At this point, the Data Governance Server is running, but it can’t do much. The Data Governance Server needs to be configured to connect to the Directory Server acting as its user store, a SCIM schema needs to be configured, and SCIM attributes need to be mapped to LDAP attributes on the user store.

That is all fairly advanced configuration for a beginner to contend with. Fortunately, the create-initial-config tool can be used to configure a reasonable set of defaults for us, including a sample user schema.

$  PingDataGovernance/bin/create-initial-config --no-prompt \
    --port 8636 --useSSL --trustAll \
    --bindPassword password --governanceBindPassword password \
    --governanceTrustStorePath PingDataGovernance/config/truststore \
    --governanceTrustStorePasswordFile PingDataGovernance/config/truststore.pin \
    --externalServerConnectionSecurity useSSL --userStore example.com:1636 \
    --userStoreBaseDN "dc=example,dc=com" \
    --initialSchema user-and-ref-app

Writing Data Governance Server configuration to resource/governance-cfg.dsconfig ..... Done

Creating External Servers ..... Done
Configuring Store Adapters ..... Done
Configuring Schema ..... Done

See the generated script file resource/governance-cfg.dsconfig and the Data Governance Server
configuration audit log logs/config-audit.log for details about how the server
was configured by this tool.

The Data Governance Server was configured with elements that are expected to be customized
before the affected services can be used. Search resource/governance-cfg.dsconfig
for instances of 'CHANGEME' and update the referenced components using dsconfig
or the Administrative Console, substituting valid values for services you intend to
enable.

Any user store servers introduced in the future must be prepared for access
using the prepare-external-store tool.

At this point, the Data Governance Server is fully configured, but we need to use a special tool called prepare-external-store to make some changes to the Directory Server.

$ PingDataGovernance/bin/prepare-external-store --no-prompt \
    --bindDN "cn=directory manager" \
    --bindPassword password \
    --hostname example.com --port 1636 --useSSL --trustAll \
    --governanceTrustStorePath PingDataGovernance/config/truststore \
    --governanceTrustStorePassword `cat PingDataGovernance/config/truststore.pin` \
    --governanceBindDN "cn=Governance User" --governanceBindPassword password \
    --userStoreBaseDN "ou=people,dc=example,dc=com"

The public certificate for the external server was added to the local
truststore 'config/truststore'

Verifying base DN 'ou=people,dc=example,dc=com' ..... Missing or inaccessible

Base entry ou=people,dc=example,dc=com does not exist in example.com:1636

Testing 'cn=Broker User' access .....
Created 'cn=Broker User,cn=Root DNs,cn=config'

Testing 'cn=Governance User' access ..... Done
Testing 'cn=Governance User' privileges ..... Done
Checking Data Governance Server Schema ..... Done
Updating Data Governance Server Schema ..... Done
Configuring Access ..... Done
Configuring Metadata ..... Done

Among other things, the tool created a service account on the DS called cn=Governance User, which the Data Governance Server will use when searching, reading, creating, updating, and deleting LDAP entries.

Load users

The Data Governance Server is almost ready to go, but we’ll need to seed the user store with some user accounts if we want to do anything interesting. Later on, we’ll learn how a Data Governance Server client can create users using SCIM, but we’ll start by bulk loading users directly into the Directory Server over LDAP.

To do this, we need to create a users file in the LDIF format using a tool included with the Directory Server, called make-ldif, and an LDIF template file included in the Data Governance Server’s resource/starter-schema directory. This file is specifically intended for use with the sample user schema that we loaded when running create-initial-broker-config previously.

$ PingDirectory/bin/make-ldif \
  --templateFile PingDataGovernance/resource/starter-schemas/reference-apps-make-ldif.template \
  --ldifFile user-entries.ldif
  
Processed 1000 entries
LDIF processing complete.  1003 entries written

This creates a file in the current directory called user-entries.ldif, with over a thousand user entries. That’s actually a small number of users; the Directory Server easily handles millions of user entries, given a sufficient amount of memory.

You now need to load these users. You do this with the import-ldif tool.

$ PingDirectory/bin/import-ldif --task --hostname localhost --port 1389 \
  --backendID userRoot --bindDN "cn=directory manager" --bindPassword password \
  --overwriteExistingEntries --ldifFile /path/to/user-entries.ldif
  
Import task 2016080322361508 scheduled to start immediately
...
Import task 2016080322361508 has been successfully completed

The import process will produce a staggering amount of output. Look for a success message at the very end.

Next steps

Your Data Governance Server is now ready to go! Browse the Data Governance Server’s API documentation to learn how to interact with the user data.

API references

Other sources of documentation

Both the Directory Server and the Data Governance Server contain PDF documentation intended for administrators. Even if you do not need to deploy or administer these servers, looking over these manuals to familiarize yourself with basic administration concepts can be helpful. These manuals include:

In addition, the UnboundID Community provides forums and a knowledge base, where you may find answers to your questions.