Rate this page

Server configuration

In this article, we’ll cover some of the basics of server configuration. For a detailed look at configuration, consult the Ping Identity Data Governance Broker Administration Guide and the Ping Identity Data Governance Broker Configuration Reference.

The Ping Identity Data Governance Broker is built upon the same foundation as the Ping Identity Directory Server, a robust and time-tested LDAP directory server. Both servers use a common configuration system, and their configurations are managed similarly, using the same tools and APIs.

The configuration system is fundamentally LDAP-based. Configuration entries are stored in a special LDAP backend called cn=config. This is a tree structure, and configuration entries are organized in a shallow hierarchy under cn=config.

Administrative accounts

Administrative accounts, called Root DNs, are stored in a branch of the configuration backend, cn=Root DNs,cn=config. When setup is run, a superuser account is created, typically called cn=Directory Manager. Though the Data Governance Broker is not an LDAP directory server, it follows this convention by default, and so its superuser account is also typically called cn=Directory Manager.

You should refer to the Ping Identity Data Governance Broker Administration Guide for more information about managing root DN accounts, including how to create them and how to restrict or expand their privileges.

The dsconfig tool

When administering the server from a shell, the dsconfig tool is used. When run without arguments, dsconfig enters an interactive mode, allowing the user to browse and update the configuration from a menu-based interface.

>>>> Ping Identity Data Governance Broker configuration console main menu

What do you want to configure?

  Cluster-Wide Configuration

    1)   Access Token Provider            17)  SAML Artifact
                                               Resolution Endpoint
    2)   Access Token Validator           18)  SCIM Attribute
    3)   Account Flow Handler             19)  SCIM Resource Type
    4)   Authentication Chain             20)  SCIM Schema
    5)   Authentication Context Class     21)  SCIM Sub Resource Type
                                               Handler
    6)   Authentication Service           22)  SCIM Subattribute
    7)   Chained Identity Authenticator   23)  Secondary Store Adapter
    8)   External Identity Provider       24)  Store Adapter
    9)   External Identity Provider       25)  Store Adapter Mapping
         Attribute Mapping
    10)  Identity Authenticator           26)  Telephony Messaging
                                               Provider
    11)  Key Pair                         27)  Trusted Certificate
    12)  OAuth2 Client                    28)  Verification Code
                                               Generator
    13)  OAuth2 Scope                     29)  XACML Policy
    14)  OpenID Connect Claim             30)  XACML Policy Service
    15)  OpenID Connect Service
    16)  Permitted Scope

  Server Configuration

    31)  Connection Handler               35)  Log Publisher
    32)  External Server                  36)  Web Application
                                               Extension
    33)  Global Configuration
    34)  Location

    /)   filter by name
    o)   'Basic' objects are shown - change this
    q)   quit

Enter option:

From this interface, configuration objects can be listed, updated, created, and deleted.

An especially valuable feature is the ability to display the command line needed to re-create a configuration object.

>>>> Configure the properties of the Authenticated Identity OAuth2
Scope

        Property                Value(s)
        ---------------------------------------------------------------
    1)  token-name              email
    2)  description             OpenID Connect email scope
    3)  tag                     -
    4)  consent-prompt-text     View your email address.
    5)  scim-sub-resource-type  The Authenticated Identity OAuth2 Scope
                                applies to the SCIM Resource Type of
                                the authenticated identity.
    6)  resource-operation      retrieve
    7)  resource-attribute      emails

    /)  filter by name
    ?)  help
    f)  finish - apply any changes to the Authenticated Identity OAuth2
        Scope
    s)  sort properties alphabetically
    d)  display the equivalent dsconfig command lines that would either
        re-create this object or only apply pending changes
    r)  display the equivalent Configuration API arguments that would
        either re-create this object or only apply pending changes
    b)  back
    q)  quit

Enter option [b]: d

Command line to re-create this Authenticated Identity OAuth2 Scope
based on its current settings:

dsconfig create-oauth2-scope --scope-name email --type authenticated-identity --set "description:OpenID Connect email scope" --set "consent-prompt-text:View your email address." --set resource-operation:retrieve --set resource-attribute:emails

The Authenticated Identity OAuth2 Scope has not been modified.  No
command line to display

A command line obtained in this form can be used directly from a shell, or it can be placed in a dsconfig batch file, along with other commands. By convention, these scripts use a file extension of .dsconfig. Batch files support comments using the # character and line continuation using the \ character.

# Create a read/write scope for the 'emails' attribute
dsconfig create-oauth2-scope --scope-name manage_email \
  --type authenticated-identity \
  --set "description:Read and write user email addresses." \
  --set "consent-prompt-text:View and update your email address." \
  --set resource-operation:modify \
  --set resource-operation:retrieve \
  --set resource-attribute:emails

A dsconfig batch file is loaded by running dsconfig with the --batch-file argument.

$ PingDataGovernance/bin/dsconfig --no-prompt --batch-file email-scope.dsconfig \
  --hostname localhost --port 1636 --useSSL --trustAll \
  --bindDN "cn=directory manager" --bindPassword password
Batch file 'email-scope.dsconfig' contains 1 commands.

Pre-validating with the local server ..... Done

Executing: create-oauth2-scope --no-prompt --hostname localhost --port
1636 --useSSL --trustAll --bindDN "cn=directory manager"
--bindPassword ******** --scope-name manage_email --type
authenticated-identity --set "description:Read and write user email addresses."
--set "consent-prompt-text:View and update your email address." --set
resource-operation:retrieve --set resource-operation modify --set
resource-attribute:emails

The mirrored operation was applied on the 'Broker' cluster

The Authenticated Identity OAuth2 Scope was created successfully

Batch files are a powerful feature that make scripted deployments possible.

The configuration audit log

All successful configuration changes are recorded to the file logs/config-audit.log. This log records both the configuration commands that represent these changes and the configuration commands needed to undo the changes.

$ tail -n 4 PingDataGovernance/logs/config-audit.log
# [10/Sep/2016:21:51:19.906 -0500] conn=0 op=49355 dn='cn=CN=example.com\,O=UnboundID Certificate,cn=Internal,cn=Root DNs,cn=config' authtype=[SASL] sasltype=[UNBOUNDID-INTER-SERVER] from=10.5.0.250 to=10.5.0.235
# This change was made to mirrored configuration data, which is automatically kept in sync across all servers.
# Undo command: dsconfig delete-oauth2-scope --scope-name email2
dsconfig create-oauth2-scope --scope-name email2 --type authenticated-identity --set "description:OpenID Connect email scope" --set "consent-prompt-text:View your email address." --set resource-operation:retrieve --set resource-attribute:emails

The config-diff tool

The config-diff compares server configurations, producing a dsconfig batch file of the differences.

When run without arguments, the config-diff tool produces a list of changes to the configuration as compared to the server’s baseline (e.g., out-of-the-box) configuration. Because this captures the customizations that you’ve made to your server configuration, this can be indispensable when making the transition from a development environment to a staging or production environment.

$ PingDataGovernance/bin/config-diff
# No comparison arguments provided, so using "--sourceLocal --sourceBaseline --targetLocal" to compare the local configuration with the baseline.
# Run "config-diff --help" to get a full list of options and example usages.

# Configuration changes to bring source (config.ldif.24116-aligned-to-6.0.0.0) to target (config.ldif)
# Comparison options:
#   Ignore differences on shared host
#   Ignore differences by instance

dsconfig set-key-manager-provider-prop --provider-name JKS --set enabled:true
dsconfig create-location --location-name Austin
dsconfig set-global-configuration-prop --set location:Austin
...

Administrative Console

Finally, a graphical configuration and administration interface is provided by the Administrative Console, a web application that is available by default from the /console path.

Administrative Console main menu