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 Broker 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 Broker Administration Guide.

Installation

To install the Ping Identity Data Governance Broker 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 Broker 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 Broker 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 Broker 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.0.0.1-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 \
  --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 Broker 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
...

Another thing you will have noticed is that you were prompted for some connection parameters. Both the Directory Server and the Data Governance Broker 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 Broker

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

$ unzip broker-6.0.0.1-GA-image.zip

Next, we run the Data Governance Broker’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 \
  --maxHeapSize 1g

Ping Identity Data Governance Broker 6.0.0.1

Initializing ..... Done
Configuring Data Governance Broker ..... Done
Configuring Certificates ..... Done
Creating Encryption Settings ..... Done
Starting Data Governance Broker ..... 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 Broker 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 Broker

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

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

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

Writing Data Governance Broker configuration to resource/broker-cfg.dsconfig ..... Done

Creating External Servers ..... Done
Configuring OpenID Connect Services ..... Done
Configuring Store Adapters ..... Done
Configuring Schema and Example Authentication Features ..... Done

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

The Data Governance Broker was configured with elements that are expected to be customized
before the affected services can be used. Search resource/broker-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 Broker 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 \
    --bindPassword password \
    --hostname example.com --port 1636 --useSSL --trustAll \
    --brokerTrustStorePath PingDataGovernance/config/truststore \
    --brokerTrustStorePassword `cat PingDataGovernance/config/truststore.pin` \
    --brokerBindDN "cn=Broker User" --brokerBindPassword 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 calamity:1636

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

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


Indexes for the following attributes should be rebuilt: ds-broker-external-identity.
Use the Directory Server's rebuild-index tool to rebuild indexes for each of
these attributes.  For example:

  rebuild-index [connection options] --task \
    --baseDN "dc=example,dc=com" \
    --index ds-broker-external-identity

where connection options specify LDAP connection options necessary for
connecting with the Directory Server.

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

Load users

The Data Governance Broker 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 Broker 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 Broker’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. Note that this tool requires that you provide the absolute path to the LDIF file that you just created.

$ 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 Broker is now ready to go! Read on to see a first example of how applications interact with the Data Governance Broker. You may also want to explore any of the following options.

Install the sample applications

A number of sample applications are provided for the Data Governance Broker. You are encouraged to install them, to read their source code, and to make modifications.

  1. A sample Groovy web application is provided on GitHub. This is a simple server-side application that demonstrates a few ways that clients can use the Data Governance Broker for authentication. It is specifically intended as a demonstration app that developers can use to familiarize themselves with the way clients may interact with the Data Governance Broker.
  2. A sample JavaScript application is provided on GitHub. This is a simple client-side application that demonstrates how an application written using a modern view library (in this case, React) can be structured to interact with the Data Governance Broker.
  3. The Data Governance Broker includes a sample application called My Account in the samples directory. This is a sophisticated, high-quality single-page application written in TypeScript. It demonstrates how the Data Governance Broker’s SCIM APIs can be used to manage a user’s profile, marketing preferences, and authentication settings. See its README for details.

API references

Read the API references if you’d like to explore the Data Governance Broker’s APIs in detail.

Other sources of documentation

Both the Directory Server and the Data Governance Broker 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:

  • Ping Identity Directory Server Administration Guide
  • Ping Identity Data Governance Broker Administration Guide
  • Ping Identity Security Guide

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