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
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
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. Batch files are a powerful feature that make scripted deployments possible. By convention, these scripts use a file extension of
.dsconfig. Batch files support comments using the
# character and line continuation using the
# 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
$ 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
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
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-126.96.36.199) 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 ...
Finally, a graphical configuration and administration interface is provided by the Administrative Console, a web application that is available by default from the