PingDirectory

Configuring LDAP external servers

The LDAP external server configuration element defines the connection, location, and health check information necessary for the PingDirectoryProxy server to communicate with the server properly.

PingDirectoryProxy includes a tool, prepare-external-server, for configuring communication between the PingDirectoryProxy server and the LDAP backend server. After you add a new LDAP external server to an existing installation, we strongly recommend that you run this tool to automatically create the user account necessary for communications. The prepare-external-server tool does not make configuration changes to the local PingDirectoryProxy server, only the external server is modified. When you run this tool, you must supply the user account and password that you specified for the PingDirectoryProxy server during configuration, cn=Proxy User by default.

You should not use cn=Directory Manager as the account to use for communication between the PingDirectoryProxy server and the PingDirectory server. For security reasons, the account used to communicate between the PingDirectoryProxy server and the PingDirectory server should not be directly accessible by clients accessing the PingDirectoryProxy server. The account that you choose should meet the following criteria:

  • For all server types, it should not exist in the PingDirectoryProxy server but only in the backend directory server instances.

  • For the PingDirectory server, this user should be a root user.

  • For the PingDirectory server, this user should not automatically inherit the default set of root privileges, but instead should have exactly the following set of privileges: bypass-read-acl, config-read, lockdown-mode, proxied-auth, and stream-values.

  • For Sun Directory Servers, the account should be created below the cn=Root DNs,cn=config entry and the nsSizeLimit, nsTimeLimit, nsLookThroughLimit, and nsIdleTimeout values for the account should be set to -1. You also need to create access control rules to grant the user account appropriate permissions within the server. The prepare-external-server tool handles all of this work automatically.

About the prepare-external-server tool

Use the prepare-external-server tool if you have added LDAP external servers using dsconfig.

The create-initial-proxy-config tool automatically runs the prepare-external-server tool to configure server communications so that you do not need to invoke it separately. The create-initial-proxy-config tool verifies that the proxy user account exists and has the correct password and required privileges. If it detects any problems, it prompts for manager credentials to rectify them.

If you want the prepare-external-server tool to add the LDAP external server’s certificates to the PingDirectoryProxy server’s trust store, you must include the --proxyTrustStorePath option and either the --proxyTrustStorePassword or the --proxyTrustStorePasswordFile option.

The default location of the PingDirectoryProxy server’s trust store is config/truststore. The pin is encoded in the config/truststore.pin file.

The following example prepares a PingDirectory server on the remote host ds-east-01.example.com, listening on port 1389 for access by the PingDirectoryProxy server using the default user account cn=Proxy User, as shown in the following example.

prepare-external-server --hostname ds-east-01.example.com \
--port 1389 --baseDN dc=example,dc=com --proxyBindPassword secret

When the prepare-external-server command is executed, it creates the cn=Proxy User Root distinguished name (DN) entry as well as an access control rule in the PingDirectory server to grant the proxy user the proxy access right.

For non-Ping Identity servers, the --baseDN argument is required for the prepare-external-server tool. The base DN is used to create the global access control instruction (ACI) entries for these servers.

Configuring server communication using the prepare-external-server tool

The following example illustrates how to run the prepare-external-server tool to prepare a PingDirectory server.

About this task

In this example, the server is configured on the remote host ds-east-01.example.com, listening on port 1636.

The PingDirectory server is being accessed by a PingDirectory server that uses the default user account cn=Proxy User,cn=Root DNs,cn=config. Because a password to the trust store is not provided, the trust store defined in the --proxyTrustStorePath is referenced in a read-only manner.

Steps

  • To prepare the PingDirectory server, use the prepare-external-server tool.

    Example:

    $ ./PingDirectoryProxy/bin/prepare-external-server \
  --baseDN dc=example,dc=com
  --proxyBindPassword password \
  --hostname ds-east-01.example.com \
  --useSSL \
  --port 1636
  --proxyTrustStorePath /full/path/to/trust/store \
  --proxyTrustStorePassword secret

  • Follow the prompts to set up the external server.

    Testing connection to ds-east-01.example.com:1636 .....

Do you wish to trust the following certificate?

Certificate Subject: CN=ds-east-01.example.com, O=Example Self-Signed Certificate
Issuer Subject:      CN=ds-east-01.example.com, O=Example Self-Signed Certificate
Validity:            Thu May 21 08:02:30 CDT 2009 to Wed May 16 08:02:30 CDT 2029

Enter 'y' to trust the certificate or 'n' to reject it.

y

The certificate was added to the local trust store

Done
Testing 'cn=Proxy User' access to ds-east-01.example.com:1636 ..... Failed to bind as
'cn=Proxy User'

Would you like to create or modify root user 'cn=Proxy User' so that it is available
for this Directory Proxy Server? (yes / no) [yes]:

Enter the DN of an account on ds-east-01.example.com:1636 with which to create or
manage the 'cn=Proxy User' account [cn=Directory Manager]:

Enter the password for 'cn=Directory Manager':

Created 'cn=Proxy User,cn=Root DNs,cn=config'

Testing 'cn=Proxy User' privileges ..... Done

Configuring an external server using dsconfig

Use the dsconfig tool to create and configure external servers. Then, specify the host name, connection method, port number, and bind distinguished name (DN), as described in previous procedures.

Steps

  1. Run the dsconfig command.

    $ bin/dsconfig

  2. In the PingDirectoryProxy main menu, enter the number corresponding to external servers.

  3. Enter the number to create a new external server.

  4. Select the type of server you want to create.

    Example:

    This example creates a new Ping Identity PingDirectory server.

    >>>> Select the type of external server that you want to create:

  1) Ping Identity DS external server
  2) JDBC external server
  3) LDAP external server
  4) Sun DS external server

  ?) help
  c) cancel
  q) quit

Enter choice [c]: 1

  5. Specify a name for the new external server.

    Example:

    In this example, the external server is named east1.

    >>>> Enter a name for the Ping Identity DS external server that you want
to create: east1

  6. Configure the host name or IP address of the target LDAP external server.

    Example:

    Enter a value for the 'server-host-name' property:east1.example.com

  7. Configure the location property of the new external server.

    Example:

    Do you want to modify the 'location' property?

   1) Leave undefined
   2) Change it to the location: East
   3) Change it to the location: West
   4) Create a new location

   ?) help
   q) quit

Enter choice [1]: 2

  8. Define the bind DN and bind password.

    Example:

    Do you want to modify the 'bind-dn' property?

   1) Leave undefined
   2) Change the value

   ?) help
   q) quit

Enter choice [1]: 2

Enter a value for the 'bind-dn' property [continue]: cn=Proxy User,cn=Root DNs,cn=config

Enter choice [b]: 6

...

Do you want to modify the 'password' property?

   1) Leave undefined
   2) Change the value
   ?) help
   q) quit

Enter choice [1]: 2

Enter a value for the 'password' property [continue]:
Confirm the value for the 'password' property:

  9. To finish the operation, enter f.

    Enter choice [b]: f

Result

The Ping Identity DS external server was created successfully.

Next steps

After adding the server, run the prepare-external-server tool to configure communications between the PingDirectoryProxy server and the Ping Identity PingDirectory server.

For more information, see Preparing two new external servers using the prepare-external-server tool.

Configuring authentication with a SASL external certificate

By default, the PingDirectoryProxy server authenticates to the PingDirectory server using LDAP simple authentication with a bind DN and a password. You can configure the PingDirectoryProxy server to use Simple Authentication and Security Layer (SASL) EXTERNAL to authenticate to the PingDirectory server with a client certificate.

Before you begin

Install and configure the PingDirectoryProxy server instances to communicate with the backend PingDirectory server instances using either SSL or StartTLS.

Steps

  1. Create a Java KeyStore (JKS) that includes a public and private key pair for a certificate that the PingDirectoryProxy server instances will use to authenticate to the PingDirectory instances.

    1. Run the following command in the instance root of one of the PingDirectoryProxy server instances.

      $ keytool -genkeypair \
  -keystore config/proxy-user-keystore \
  -storetype JKS \
  -keyalg RSA \
  -keysize 2048 \
  -alias proxy-user-cert \
  -dname "cn=Proxy User,cn=Root DNs,cn=config" \
  -validity 7300

    2. When prompted for a key store password, enter a strong password to protect the certificate.

    3. When prompted for the key password, press Enter to use the key store password to protect the private key.

  2. Use a text editor to create a config/proxy-user-keystore.pin file containing a single line that is the key store password provided in the previous step.

  3. If there are other PingDirectoryProxy server instances in the topology, copy the proxy-user-keystore and proxy-user-keystore.pinfiles into the config directory for all instances.

  4. To export the public component of the proxy user certificate to a text file, run the following command.

    $ keytool -export \
  -keystore config/proxy-user-keystore \
  -alias proxy-user-cert \
  -file config/proxy-user-cert.txt

  5. Copy the proxy-user-cert.txt file into the config directory of all directory server instances.

    1. Import that certificate into each server’s primary trust store by running the following command from the server root.

      $ keytool -import \
  -keystore config/truststore \
  -alias proxy-user-cert \
  -file config/proxy-user-cert.txt

    2. When prompted for the keystore password, enter the password contained in the config/truststore.pin file.

    3. When prompted to trust the certificate, enter yes.

  6. To update the configuration for each PingDirectoryProxy server instance to create a new key manager provider that will obtain its certificate from the config/proxy-user-keystore file, run the following dsconfig command.

    $ dsconfig create-key-manager-provider \
  --provider-name "Proxy User Certificate" \
  --type file-based \
  --set enabled:true \
  --set key-store-file:config/proxy-user-keystore \
  --set key-store-type:JKS \
  --set key-store-pin-file:config/proxy-user-keystore.pin

  7. To update the configuration for each LDAP external server in each PingDirectoryProxy server instance to use the newly-created key manager provider, and also to use SASL EXTERNAL authentication instead of LDAP simple authentication, run the following dsconfig command.

    $ dsconfig set-external-server-prop \
  --server-name ds1.example.com:636 \
  --set authentication-method:external \
  --set "key-manager-provider:Proxy User Certificate"

    Result:

    After these changes, the PingDirectoryProxy server re-establishes connections to the LDAP external server and authenticate with SASL EXTERNAL.

  8. Verify that the PingDirectoryProxy server can communicate with all backend servers by running the bin/status command.

    Result:

    All of the servers listed in the "--- LDAP External Servers ---" section are available.

  9. Review the PingDirectory server access log.

    The BIND RESULT log messages used to authenticate the connections from the PingDirectoryProxy server include the following:

    • authType="SASL"

    • saslMechanism="EXTERNAL"

    • resultCode=0

    • authDN="cn=Proxy User,cn=Root DNs,cn=config"