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
|
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 |
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
-
Run the
dsconfig
command.$ bin/dsconfig
-
In the
PingDirectoryProxy main menu
, enter the number corresponding to external servers. -
Enter the number to create a new external server.
-
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
-
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
-
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
-
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
-
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:
-
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
-
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.
-
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
-
When prompted for a key store password, enter a strong password to protect the certificate.
-
When prompted for the key password, press Enter to use the key store password to protect the private key.
-
-
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. -
If there are other PingDirectoryProxy server instances in the topology, copy the
proxy-user-keystore
andproxy-user-keystore.pin
files into theconfig
directory for all instances. -
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
-
Copy the
proxy-user-cert.txt
file into theconfig
directory of all directory server instances.-
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
-
When prompted for the keystore password, enter the password contained in the
config/truststore.pin
file. -
When prompted to trust the certificate, enter
yes
.
-
-
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 followingdsconfig
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
-
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.
-
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.
-
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"
-