Using SSL to Access the LDAP Server
This procedure describes how to set up Windchill and Apache to use SSL to connect to the Windchill Directory Server. Data encryption and Server identification is supported. Client identification is not documented. Windchill Directory Server provides all the software to accept and communicate over an SSL connection. Tools are also provided to manage certificates.
Windchill does not provide SSL configuration options during installation. Windchill installation is performed using non-SSL connections to the LDAP Server. After Windchill installation is complete, Windchill and Windchill Directory Server can be reconfigured to use SSL to access the directory server.
Configure Windchill Directory Server to Accept SSL-based Connections
To use SSL, you must obtain or generate a certificate used to provide proof of server identity. For production use, PTC recommends that a certificate be obtained from a trusted Certificate Authority. For testing purposes, you can generate a self-signed certificate using the keytool utility of Java.
The Windchill Directory Server provides a number of options for configuring and using SSL. The following section describes one of the options which provides instructions for configuring SSL using a self-signed certificate. The instructions also include information about configuring Windchill and Apache to use SSL to communicate with the Windchill Directory Server.
Configure Windchill Directory Server to Accept SSL-based Connections Using a Self-signed Certificate
This procedure assumes the following:
• The Windchill Directory Server is installed on the system on which you are working.
• The Java keytool utility is in your path. You can either add it to your path, or provide its full path when invoking the utility.
Perform the following steps to configure Windchill Directory Server to accept SSL-based connections:
1. Choose a directory for the keystore and navigate to the directory you choose. For example, navigate to D:\WindchillDS\WindchillDS\server\config.
2. Create a private key for the certificate.
keytool -genkey -alias windchillds-server -keyalg rsa -dname "CN=<MyHost>.<MyDomain>.com,O=PTC,C=US" -keystore ldaps-keystore -storetype JKS
In this case, the value of the -dname argument should be changed so that it is suitable for your environment. The value of the CN attribute should be the fully-qualified name of the system on which the certificate is being installed, the value of the O attribute should be the name of the company or organization, and the C attribute should be the two-character country abbreviation. You will be interactively prompted for both a password to protect the contents of the keystore and a password to protect the private key. Both passwords should be the same.
3. Generate a self-signed certificate for the key with the command:
keytool -selfcert -alias windchillds-server -validity 1825 -keystore ldaps-keystore -storetype JKS
When you are prompted for the keystore password, enter the same password that you provided in Step 2.
4. Create a text file named D:\WindchillDS\WindchillDS\server\config\ldaps-keystore.pin.
The file should contain the password that you chose to protect the contents of the keystore.
5. Export the public key for the certificate that you just created.
keytool -export -alias windchillds-server -file windchillds-server.cer -rfc -keystore ldaps-keystore -storetype JKS
6. Create a new trust store and import the server certificate into it.
keytool -import -alias windchillds-server -file windchillds-server.cer -keystore ldaps-truststore -storetype JKS
Type "yes" when you are prompted about whether you want to trust the certificate.
7. Use the Windchill Directory Server Control-Panel to change the default keystore location, the default truststore location, and the default certificate nickname. Or, place content similar to the following in the local file change_keystore:
dn: cn=JKS,cn=Key Manager Providers,cn=config
changetype: modify
replace: ds-cfg-key-store-file
ds-cfg-key-store-file: config/ldaps-keystore
-
replace: ds-cfg-key-store-pin-file
ds-cfg-key-store-pin-file: config/ldaps-keystore.pin
-
<blank line>
dn: cn=JKS,cn=Trust Manager Providers,cn=config
changetype: modify
replace: ds-cfg-trust-store-file
ds-cfg-trust-store-file: config/ldaps-truststore
-
<blank line>
dn: cn=LDAPS Connection Handler,cn=Connection Handlers,cn=config
changetype: modify
replace: ds-cfg-ssl-cert-nickname
ds-cfg-ssl-cert-nickname: windchillds-server
-
<blank line>
|
|
When copying the entries above, replace <blank line> with a blank line.
|
Then, enter an ldapmodify command similar to:
..\bat\ldapmodify.bat --hostname localhost --port 4444
--filename change_keystore --bindDN
cn=Manager --bindPassword "admin" --trustAll --useSSL --noPropertiesFile
8. Use the dsconfig command to enable the key manager provider, trust manager provider, and SSL connection handler.
The following examples show typical use of the dsconfig command to enable the default providers.
..\bat\dsconfig -h localhost -p 4444 -D "cn=manager" -w admin -X -n set-key-manager-provider-prop --provider-name JKS --set enabled:true
..\bat\dsconfig -h localhost -p 4444 -D "cn=manager" -w admin -X -n set-trust-manager-provider-prop --provider-name "Blind Trust" --set enabled:true
..\bat\dsconfig -h localhost -p 4444 -D "cn=manager" -w admin -X -n set-connection-handler-prop --handler-name "LDAPS Connection Handler" --set "trust-manager-provider:Blind Trust" --set key-manager-provider:JKS --set listen-port:636 --set enabled:true
Port 636 is the standard SSL port for SSL connections to LDAP. If you wish to use another port, then change the listen-port property in the last command to the port number being used.
9. The LDAP server now has a second listener that accepts SSL-based client connections.
The correct configuration can be verified with the ldapsearch command, for example:
..\bat\ldapsearch --port 636 --useSSL --bindDN "cn=Manager" --bindPassword "admin" --baseDN "" --searchScope base "(objectClass=*)"
You should be prompted about whether you want to trust the server's certificate, and upon typing “yes,” the root DSE entry will be returned to you.
|
|
This step should only be performed after the Windchill configuration is completed.
|
If all communication to the LDAP server is to use SSL the normal LDAP listener can be disabled.
..\bat\dsconfig -h localhost -p 4444 -D "cn=manager" -w admin -X -n set-connection-handler-prop --handler-name "LDAP Connection Handler" --set enabled:false
Configure Windchill to use LDAPS
1. Import your self-signed certificate into the JVM.
Windchill uses Info*Engine for all access to an LDAP directory. Info*Engine uses standard Java JNDI code for communication to the LDAP/LDAPS Directory. Info*Engine has been tested using LDAPS with the Windchill Directory Server and with Active Directory. Any JNDI compliant LDAPS directory should be supported.
If using a Certificate Authority signed certificate, the JVM should have support built in and Info*Engine just needs to be configured.
If a self-signed certificate is being used, the certificate must be added to the JVM keystore. This is done by doing the following:
a. Locate the self-signed certificate. Import the certificate into the default JVM keystore with the following commands:
cd <jdk_home>/jre/lib/security <java_home>\jre\bin\keytool -import -alias windchillds-server -file <self-signed-certificate-file> -keystore jssecacerts
b. Create a password when prompted.
Type "yes" when you are prompted about whether you want to trust the certificate.
For example:
cd d:\java\jdk1.6.0_17\jre\lib\security d:\java\jdk1.6.0_17\bin\keytool -import -alias windchillds-server -file "d:\WindchillDS\WindchillDS\server\config\windchillds-server.cer" -keystore jssecacerts
2. Configure the JNDI adapters to use LDAPS
Use the Info*Engine Property Administrator to change/add the following properties of the JNDI adapter definitions that should access the LDAP Server using LDAPS. Normally two adapters are defined: ...EnterpriseLdap, ... and ...Ldap. Change the following property.
Provider Url:
Old value: ldap://<fully qualified hostname>/ New value: ldaps://<fully qualified hostname>:<SSL port>/
The <SSL port> must be specified if it is not the standard port: 636.
3. Configure the servlet Base Uri
Open the Info*Engine Property Administrator. From the Services column of the main page, open the “servlet” entry. Expand the Property Administrator Properties and click edit to change the Base URI. Change the ldap:// prefix to ldaps:// and modify the port number as necessary. The <SSL port> must be specified if it is not the standard port for LDAPS: 636. For example:
Old value: ldap://<fully qualified hostname>/<DN>
New value: ldaps://<fully qualified hostname>:<SSL port>/<DN>
4. Configure Windchill Info*Engine to access the LDAP Server using LDAPS.
The Info*Engine configuration needs to be changed to use LDAPS. This involves three changes:
◦ Change to use LDAPS rather than LDAP
◦ Change the port number to specify the SSL port.
◦ Propagate the changes.
From a Windchill shell, use commands similar to these:
- xconfmanager -s ie.ldap.scheme=ldaps -t codebase/WEB-INF/ieStructProperties.txt
- xconfmanager -s ie.ldap.serverPort=636 -t codebase/WEB-INF/ieStructProperties.txt
- xconfmanager -p
5. Configure the Web Server to access the LDAP Server using LDAPS.
The following documents how to configure Apache 2.2 to access the LDAP server using SSL. If you are not using Apache, refer to your Web Server documentation for SSL configuration instructions.
The LDAP URL used to access the LDAP server must be updated in the Apache configuration. The LDAP URL protocol must be changed from “ldap” to “ldaps” and the port must be set to the SSL port of the LDAP server. From Windchill’s Apache installation directory, issue the following command to reconfigure Apache. If the LDAP server is providing the administrative LDAP service and the enterprise LDAP service, this command must be issued for each:
ant -f webAppConfig.xml addAuthProvider -DappName=<Web application name> -DldapUrl=<ldap Url> -DproviderName=<LDAP provider name> -DbindDn=<bindDN> -DbindPwd=<bindPassword>
The following example shows both commands for the administrative LDAP and enterprise LDAP:
ant -f webAppConfig.xml addAuthProvider -DappName=Windchill -DldapUrl=”ldaps://<host>:636/ou=people,cn=AdministrativeLdap,cn=Windchill_10.0,o=ptc” -DproviderName=AdministrativeLdap -DbindDn=”cn=manager” -DbindPwd=admin
ant -f webAppConfig.xml addAuthProvider -DappName=Windchill -DldapUrl=”ldaps://<host>:636/ou=people,cn=EnterpriseLdap,cn=Windchill_10.0,o=ptc” -DproviderName=EnterpriseLdap -DbindDn=”cn=manager” -DbindPwd=admin
Configure Trusted Certificates
Windows Systems
You must import the public certificate into the Internet Explorer Certificate Store. If you are using the steps in the previous section to generate a self-signed certificate, the public certificate is windchillds-server.cer.
1. From Internet Explorer, select > .
2. Select >
3. Select Trusted Root Certification Authorities
4. Select Import and browse to the CER file that you generated or was generated from a trusted Certificate Authority.
5. Verify that the certificate will be placed in the "Trusted Root Cerification Authorities" store.
6. Click Next and Finish.
UNIX Systems
You must modify the Apache configuration to configure trusted certificates.
For example, assume that you are using a self-signed certificate generated with the above Windchill Directory Server steps. Then add the following to the file <Apache>/conf/extra/additions.conf file:
LDAPTrustedGlobalCert CA_BASE64 /path/to/windchillds-server.cer
If you are using a certificate from a trusted Certificate Authority instead of using a self-signed certificate, you must do one of the following:
• Determine the appropriate LDAPTrustedGlobalCert directive to specify the location of the trusted CA certificates.
• Add an LDAPVerifyServerCert directive to disable verification of server certificates.
For details on the using your own signed certificate, see the
Apache documentation.
