SSL/TLS Client Authentication
There are many ways to handle SSL/TLS authentication. Handling it depends on the security requirements of a specific site. The following are the minimum requirements for achieving SSL/TLS client authentication:
• A client certificate must be generated. This is an X.509 public/private certificate pair and is usually stored in a PKCS #12 archive file, which is sometimes referred to as a pkcs12 keystore. It may also be contained in many other keystore formats.
• The web server must be configured for HTTPS. For more information, see Configuring HTTPS for PTC HTTP Server and Windchill.
• The web server must be configured to verify the client SSL/TLS certificate using the client authentication (CA) certificate that signed the client certificate.
• The web server must be configured to enforce SSL/TLS client certificate authentication.
• The client must be capable of presenting the SSL/TLS client certificate to the server when challenged.
The SSL/TLS client certificate generation and CA certificates will vary on each site. To generate these certificates and obtain the correct CA certificates, consult with your local SSL/TLS experts. The CA certificate must be used to sign the SSL/TLS client certificate.
 |
Windchill SSL/TLS client authentication is not supported for the Safari browser on Mac OS. For up-to-date information about client compatibility with SSL/TLS authentication, refer to the article: https://support.ptc.com/appserver/cs/view/solution.jsp?n=CS250038.
|
Web Server Configuration
For Apache-based web servers (including PTC HTTP Server), the CA certificate must be in PEM-encoded format. Documentation for configuring Apache 2.4 for SSL/TLS client certificate authentication can be found on Apache web site using the following URLs:
For a simple case, the SSLCACertificateFile directive in Apache can specify the CA certificate file that is used to validate the client SSL certificate. For example:
SSLCACertificateFile<httpserver_home>/<location_to>/ca.crt.
If the SSL CA certificate is a certificate chain, you may need to set the SSLVerifyDepth directive to specify the number of certificates in the chain to check. For more information about SSL CA certificates, consult with your SSL expert.
The previous two configuration directives can be placed in httpd.conf or in any file in the conf/conf.d directory. However, PTC highly recommends that you create a new site-specific CONF file and add this file to httpserver_home/conf/sslvhostsconf.d directory. This file will be automatically added to the default SSL virtualhost configuration. Creating a new file will assist in managing these configuration directives and will ensure that PTC updates do not overwrite any specific configuration values.
After these values are configured, the web server must know which URLs require authentication. This is normally configured in the <httpserver_home>/conf/conf.d/30-app-[webappname]-Auth.conf file. The file is automatically generated; therefore, any changes can be lost. To avoid overwriting these configured values, add them to the site-specific CONF file previously created in the httpserver_home/conf/sslvhostsconf.d directory. For details on how to configure changes to automatically generated files from PTC, see PTC HTTP Server Configuration Layout.
Within each LocationMatch block, the default file configures at least the LDAP authentication.
The directives in this block can be entirely replaced with the appropriate SSL directives. At a minimum, the following directives are necessary:
• SSLVerifyClient require
• SSLUserName [varname]
The value of the SSLUserName varname argument depends on site security requirements and certificate configuration. The SSLUserName directive is required to set the REMOTE_USER variable. As an alternative to SSLUserName, the FakeBasic SSL option can be used as documented in the Apache mod_ssl documentation. This alternative is recommended as it provides a fake HTTP Basic authentication header that the Windchill component can attempt to use.
Some Windchill clients do not natively support SSL authentication. This requires specific authentication mechanisms or anonymous access to be allowed on certain Windchill URLs. By default these URL resources are declared in the <ptc_httpserver_home>/conf/app-<webAppName>-AuthRes.xml> file. Any resource with the type anonymous or protocolAuth needs to be accessible without SSL client verification. The LocationMatch rules for those URLs must include the directive SSLVerifyClient none. If your authentication requirements mandate that all URLs must be configured for SSL authentication, then you can alternatively configure the Apache server so that those URLs are accessed with a certificate.
Client Compatibility
The following clients require configuration to enable SSL authentication with Windchill.
• Creo Parametric 2.0, 3.0 and 4.0
a. Import the user-specific certificate in the web browser
▪ Internet Explorer: > > .
▪ Chrome: > > .
b. Launch Creo Parametric and go to Configuration Editor
c. For Creo 3.0 and 4.0 M010 Chrome embedded browsers, add dm_pki_authentication_url with the value set to the URL of the Windchill server
|
|
SSL certificate authentication is for Chromium embedded browser in Creo 4.0 F000 is not supported, however this is supported in Creo 4.0 M010.
This step is not needed for Creo 2.0 as Chromium embedded browser is not supported for that release.
|
d. Save config.pro file to be reloaded at next Creo Parametric launch
|
|
For Creo 4.0, the new config.pro option will only be supported in Creo 4.0 M010.
|
e. Close and relaunch Creo Parametric
f. Register PKI configured Windchill server from > or using the Workspace user interface of the same server.
g. Login is processed with the certificate in the browser
• Windchill Workgroup Manager browsers
a. Import the user-specific certificate in the web browser
▪ Internet Explorer: > >
▪ Chrome: > >
b. Configure embedded browsers. From Windchill Workgroup Manager installation point, open the wgmclient.ini file in a text editor
c. Find the preference pki.authentication.url and set it to the value to the URL of the Windchill server.
d. Save wgmclient.ini and launch Windchill Workgroup Manager
e. Register PKI configured Windchill server from >
f. Login is processed with the certificate in the browser
Configuring some clients for SSL client certificate authentication is unsupported. Before you implement SSL authentication at your site, you should examine the extent to which these clients are used and whether these client exclusions are an impediment to using SSL authentication. PTC does not support SSL authentication configurations for the following clients:
• Windchill Archive
• Windchill Gateway for Creo Elements/Direct Model Manager
• Windchill ProjectLink Plugin for Microsoft Project. Alternatively, use the Import Plan action as a workaround. For more information, refer to the following knowledge base article: https://support.ptc.com/appserver/cs/view/case_solution.jsp?n=249852.
• Windchill STEP Connector
For up-to-date information about client compatibility with SSL/TLS authentication, refer to the following article: https://support.ptc.com/appserver/cs/view/solution.jsp?n=CS250038.
Java-Based Client Configuration
Most web browsers have a process for importing the client certificate into its user certificate database. When requested, the web browser prompts the user for the certificate. Java-based clients have their own SSL certificate database that requires line parameters to enable it. The following parameters are required to allow Java-based clients to present the SSL client certificate when challenged:
• -Djavax.net.ssl.keyStoreType=pkcs12
• -Djavax.net.ssl.keyStore=(path to pkcs12 file)
• -Djavax.net.ssl.keyStorePassword=(password for client certificate)
For Java clients, these parameters can be added to the Java Runtime parameters in the Java Console. For command line applications, these parameters must be specified as arguments to the command line Java virtual machine.