LDAPS Configuration Guide

 

Overview

This article explains how to configure Predict! Risk Controller to authenticate users against an Active Directory server using LDAPS (LDAP over SSL, port 636).

It covers:

• Prerequisites
• Standalone.xml (required)
• Certificate trust-store setup (using InstallCert)
• Best Practices
• Troubleshooting

 

Prerequisites

Obtain the following information from the Active Directory administrator:

• Username with search permission and corresponding password
• Short domain name and Fully Qualified Domain Name (FQDN)
• Full DNS address of the AD server
• LDAP URL
  • LDAPS uses port 636 (e.g. ldaps://adserver.domain.company.com:636)
• Base Context
  • Distinguished Name of the user container
• LDAP RDN
  • the login attribute, typically sAMAccountName

 

Step 1 — Configure LDAP Authentication During Installation (if applicable)

When setting up LDAPS during a fresh installation or upgrade, select the LDAP Authentication component on the Choose Components screen. Enter the following when prompted:

• LDAP URL using the LDAPS format: ldaps://adserver.domain.company.com:636
• Bind DN
  • the account used to search the directory
  • (e.g. Company\BindAccount)
• Bind Credentials
  • password for the bind account
• Base Context
  • distinguished name of the container holding user accounts
• LDAP RDN
  • attribute used as the Predict! login name
  • typically sAMAccountName
• Search subtree
  • set to True to search sub-OUs
• Role Context, Role Filter, Role Name Attribute
  • for group-based access control

 

Step 2 — Configure standalone.xml for LDAPS

To switch an existing LDAP connection to LDAPS

1. open the following file in a text editor:
   • C:\prc6\wf26\standalone\configuration\standalone.xml
2. Locate the <dir-context> element and make the following change:
   • replace ldap:// with ldaps:// and change port 389 to 636:

<dir-contexts>

  <dir-context name="ldap-connection"

    url="ldaps://adserver.domain.company.com:636"

    principal="domain\pinocchio">

    <credential-reference clear-text="geppetto"/>

  </dir-context>

</dir-contexts>

 

Note:

1. Account details are case-sensitive. 
2. Short-form account names (DOMAIN\name) require the domain name in capitals.
3. Long-form names (name@domain.company.com) should use the case they were defined in.
4. The AD login module must always be last in the authentication chain in standalone.xml to prevent AD account lockouts.

 

Step 3 — Import the LDAPS Domain Controller Certificate

Important: Predict! must trust the SSL certificate presented by the Domain Controller. 

Use the InstallCert tool, located on the Predict! installation media at:

Predict! Risk Controller\Scripts\InstallCert

 

1. Unzip the InstallCert folder into the prc/jdk/bin directory:
   1. C:\prc6\JDKXX\bin\
2. Open a Command Prompt in the unzipped InstallCert folder and run the command below (replacing the example values with the correct DC address and port):
   1. D:\prc6\JDK21\bin\java.exe InstallCert adserver.domain.company.com 636
3. Press 1 to add the certificate. This creates or updates the jssecacerts file.
4. Repeat steps 1–3 for each Domain Controller certificate that must be trusted.
5. Copy the jssecacerts file to the following location, replacing any existing file:
   1. C:\prc6\JDKXX\lib\security\
6. Restart the Predict! service to apply the changes.

Note: Do not modify the cacerts file. 

• The jssecacerts file takes precedence over cacerts when both are present and will not be overwritten by JDK updates.
• This process must be repeated each time AD certificates are renewed.

 

Step 4 — Restart the Predict! Service

After saving standalone.xml and importing the certificate, restart the Predict! Risk Controller service for all changes to take effect.

• This can be done from Windows Services Manager, Task Manager, or via Command Prompt:

sc stop PRC62

sc start PRC62

 

Best Practices

Encrypt the LDAP Bind Password

Encrypting the Active Directory bind credentials stored in standalone.xml is strongly recommended rather than leaving them as clear text. Refer to the article on encrypting passwords in standalone.xml. 

Note: Encrypting the LDAP password does not affect what is sent over the wire to the AD server. AD servers typically only receive an MD5 hash of the password regardless of how it is stored on the Predict! server.

 

Configure LDAP Connection and Read Timeouts

To prevent slow logins caused by unresponsive LDAP servers, configure connection and read timeouts. Add the following to standalone.conf.bat:

-Dcom.sun.jndi.ldap.read.timeout=60000

Alternatively, add timeout attributes directly on the dir-context element in standalone.xml:

<dir-context name="ldap-connection" url="ldaps://..."

  connection-timeout="10000" read-timeout="10000" ...>

 

Restrict Authentication to Active Directory Only

Rely entirely on Active Directory for authentication by disabling local Predict! passwords.

Add the following line to:  C:\prc6\layouts\settingsFile.properties

Using_Active_Directory=TRUE

Restart the Predict! service after making this change.

Alternatively, this can be set from the Admin Portal under System Settings without requiring a service restart.

Note: Users authenticated against Active Directory must also be present in the Predict! database. Create the required user accounts first by logging in as ADMIN.

 

Configure LDAP Redirects

If the LDAP server is configured to redirect requests, add referral-mode="follow" to the dir-context element in standalone.xml:

<dir-context name="ldap-connection" url="ldaps://..."

  principal="..." referral-mode="follow">

  <credential-reference clear-text="..."/>

</dir-context>

 

Troubleshooting

Problem	Suggested Resolution
Users cannot authenticate via Active Directory	Open a Command Prompt and run: telnet AD_Server 636 to verify the AD server accepts connections on port 636 from the Predict! application server.
SSL/certificate error when connecting via LDAPS	The DC certificate has not been imported. Follow Step 3 above using InstallCert. Verify the jssecacerts file exists in \prc6\JDKXX\lib\security after import.
AD accounts are becoming locked out	Ensure the AD login module is placed last in the authentication chain in standalone.xml. If it runs before the Predict! database module, failed login attempts using Predict! database passwords will register as AD failures and may trigger lockout.
LDAP settings lost after upgrade	The installer only migrates a maximum of one LDAP section. After upgrading, manually replicate any additional LDAP sections from the previous standalone.xml into the new configuration file.
Old AD password still works after the user changes it	This is caused by the LRU credential cache in WildFly. Add a maximum-age parameter to the caching-realm element, or remove caching realms entirely to force live LDAP queries. Note: Removing caching may increase login time.
Certificate renewal causes LDAPS authentication failure	The InstallCert process must be repeated each time the AD Domain Controller certificate is renewed. Schedule this as a recurring task ahead of certificate expiry dates.