Configuring Operator Advisor for Session User (Windchill Authentication)
The Session User authentication option uses Windchill to authenticate with ThingWorx. When a user accesses ThingWorx, they are routed to Windchill to authenticate. Once authenticated, the user is routed back to ThingWorx. This configuration requires that the same user exists in both Windchill and ThingWorx.
ThingWorx includes a configuration option to automatically create users in ThingWorx once they have been authenticated in Windchill. If this configuration option is not selected, users must independently exist in both Windchill and ThingWorx. The ThingWorx user must be added to the appropriate ThingWorx user group to have access to the Operator Advisor entities and services. If you select the option to automatically create users in ThingWorx, you can designate the user group to which they are automatically added.
Configuring Operator Advisor to use the Session User authentication option requires configurations in Windchill, ThingWorx, and Operator Advisor.
Prerequisites for Windchill Authentication
• Windchill must be configured for SSL.
• ThingWorx must be configured for SSL.
Configuring Operator Advisor and ThingWorx to Use Windchill Authentication
Complete the following steps to configure Operator Advisor and ThingWorx to use Windchill for authentication:
1. Make the ThingWorx Java instance aware of the certificates for the Windchill server. Import the (root) certificate into the Java keystore used by ThingWorx.
2. If EnableSSO appears in the platform-settings.json file for ThingWorx, set it to false, and restart your ThingWorx server. Otherwise, proceed to step 3.
3. Create a new Data Shape in ThingWorx named CustomHeadersDataShape. Under Field Definitions, create the following two field definitions with Base Type=String:
◦ Accept-Language
◦ Authorization
4. Create a duplicate of the PTC.SCA.SCO.MPMLink_ODataConnector Thing for your configurations, because customizations, such as overriding a service, must be performed on a duplicate. For more information, see Configuring the MPMLink OData Connector and Duplicating Extension Entities.
a. Under Configuration, set the following values:
▪ Under Generic Connector Connection Settings, select None for the Authentication Type
▪ Under CSRF Settings, enter /servlet/odata for Relative URL For CSRF Get Request
▪ Under HTTP Connector Connection Settings:
▪ Leave Username and Password blank
▪ For Base URL enter https://<Windchill Hostname>:<port>/Windchill/sslClientAuth, where <Windchill Hostname> and <port> are the appropriate values for your Windchill system
▪ For Relative URL enter /servlet/odata
▪ For Connection URL enter /servlet/WindchillGW/wt.httpgw.HTTPServer/ping
Click Save.
b. Under Services, override the GetCustomHeaderParameters service. Add the following code to the service:
var Language = Resources["CurrentSessionInfo"].GetCurrentUserLanguage();
var params = {
infoTableName: "InfoTable",
dataShapeName: "CustomHeadersDataShape"
};
var result = Resources["InfoTableFunctions"].CreateInfoTableFromDataShape(params);
params = {
tableName: "GenericConnectorConnectionSettings" /* STRING */
};
var configTable = me.GetConfigurationTable(params);
var row = configTable.getRow(0);
var authType = row.getStringValue("AuthenticationType");
if ("None".equals(authType)) {
var CurrentUser = Resources["CurrentSessionInfo"].GetCurrentUser();
var baseEncodedStr = base64EncodeString(CurrentUser + ':');
var authHeaderValue = "Basic " + baseEncodedStr;
row = {
"Accept-Language": Language,
"Authorization": authHeaderValue
};
} else {
row = {
"Accept-Language": Language
};
}
result.AddRow(row);
var params = {
infoTableName: "InfoTable",
dataShapeName: "CustomHeadersDataShape"
};
var result = Resources["InfoTableFunctions"].CreateInfoTableFromDataShape(params);
params = {
tableName: "GenericConnectorConnectionSettings" /* STRING */
};
var configTable = me.GetConfigurationTable(params);
var row = configTable.getRow(0);
var authType = row.getStringValue("AuthenticationType");
if ("None".equals(authType)) {
var CurrentUser = Resources["CurrentSessionInfo"].GetCurrentUser();
var baseEncodedStr = base64EncodeString(CurrentUser + ':');
var authHeaderValue = "Basic " + baseEncodedStr;
row = {
"Accept-Language": Language,
"Authorization": authHeaderValue
};
} else {
row = {
"Accept-Language": Language
};
}
result.AddRow(row);
c. Click Done.
d. Click Save.
5. Open the PTC.SCA.SCO.MPMLinkWorkDefinitionConverter Thing for editing. Ensure that the Connector field references the duplicate connector that you configured in step 4.
6. Open the PTC.SCA.SCO.OperatorAdvisorContentProxyMediaEntity Thing for editing. Under Configuration, set the following values:
◦ Under Content Source Connection Information:
▪ Select the Dynamic Content checkbox
▪ For URL, enter https://<Windchill Hostname>:<port>, where <Windchill Hostname> and <port> are the appropriate values for your Windchill system
▪ Select the Ignore SSL Errors checkbox
▪ For Authentication Type, select Session User
▪ Leave Username and Password blank
▪ For Test Connection URL, enter https://<Windchill Hostname>:<port>/Windchill/sslClientAuth/servlet/odata, where <Windchill Hostname> and <port> are the appropriate values for your Windchill system
◦ Under SSL Connection Configuration, set the following values:
▪ For SSL Key Store Path, enter the path to the ThingWorx keystore
▪ For SSL Key Store Password, enter the password for your ThingWorx keystore
▪ For SSL Trust Store Path, enter the path to the truststore
▪ For SSL Trust Store Password, enter the password for your truststore
◦ Under Session User Configuration, for Session User Query Parameter, enter wt.effectiveUid
7. Click Save.
8. Set up the integration runtime. For more information, see Configuring the Integration Runtime.
9. Test the configuration for ThingWorx:
a. Navigate to the PTC.SCA.SCO.MPMlink_ODataConnector Thing from step 4.
b. Under Services, execute the ValidateConnection service. The following result confirms a successful connection:
Configuring the PTC Identity Provider Authenticator
 | Before configuring the PTC Identity Provider Authenticator, ensure that the latest ptc-windchill-extension-[ReleaseVersion] extension is imported into ThingWorx. To access the latest extension: 1. Download and unzip the contents of the PTC-Windchill-Extension-for-ThingWorx file. To locate the download, go to the PTC Software Download page, and expand the following folders: > > . 2. Open the ptc-windchill-extension-<version>.zip file, and delete the ptc-thingview-extension.zip file. A more recent version of ptc-thingview-extension.zip has already been imported as part of Operator Advisor. 3. Import the ptc-windchill-extension-<version>.zip file. |
To configure the PTC Identity Provider Authenticator, complete the following steps:
1. In ThingWorx Composer, navigate to > in the navigation pane.
2. Open the ptc-identity-provider-authenticator.
3. Under General Information:
◦ Select the Enabled checkbox.
◦ For Priority, enter the appropriate value. By default, the value is 1, indicating that this authenticator is the first authenticator to be run. The Priority value is important if you want to implement checks by multiple authenticators. If the authenticator with a priority of 1 fails, then the next authenticator performs the authentication check, and so on.
4. Under Configuration:
◦ Under Authenticator Configuration, there are two options to configure: CreateUserDynamically and HomeMashup.
▪ CreateUserDynamically—When selected, the authenticator automatically creates a user in ThingWorx if the user does not yet exist and the user has been authenticated by Windchill. If the checkbox is not selected, the browser is still routed to Windchill for authentication, but fails to open ThingWorx if the user does not also exist in ThingWorx.
▪ HomeMashup—Assigns a home mashup to the newly created users. If no home mashup is specified, ThingWorx routes the browser to the ThingWorx search page.
◦ Under User Configuration, add a UserGroup. This is the user group to which the dynamically created ThingWorx users are automatically added. Select a user group which provides access to Operator Advisor entities and services.
5. Click Save.
Add Servlet Filters to Tomcat Configuration
The Windchill identity provider authentication filter is used to redirect an unauthenticated ThingWorx user to the Windchill login form for authentication. After successful authentication, the ThingWorx application receives a key and a user name.
The ThingWorx side of the filter is configured in the web.xml file found in the ThingWorx Tomcat installation directory:
1. Stop Tomcat and the Integration Runtime.
2. Open the previously downloaded PTC-Windchill-Extension-for-ThingWorx file, and copy the ptc-identity-provider-authentication-filter-<version>.jar file from the idp directory to the WEB-INF/lib directory of the ThingWorx Tomcat installation.
3. Navigate to the <ThingWorx Tomcat>\webapps\Thingworx\WEB-INF\web.xml file.
4. Make a copy of the web.xml file, and save it to a known location.
5. Replace the <ThingWorx Tomcat>\webapps\Thingworx\WEB-INF\web.xml file with the web.xml file from the \idp\twx-8.x.x directory of the previously downloaded PTC-Windchill-Extension-for-ThingWorx file.
6. Open that web.xml file, and add your Windchill server details to the IdentityProviderAuthenticationFilter and IdentityProviderKeyValidatorFilter entries in the following format:
[http or https]://[Windchill-host]:[Windchill-port]/[Windchill WebApp name]
The [Windchill WebApp name] can be found by searching for wt.webapp.name in <Windchill>\codebase\wt.properties.
7. Start Tomcat and the Integration Runtime.
Additional Windchill Configurations
1. Create a ca-bundle.crt file in <HTTPSERVER_HOME>\conf\.
2. Edit the ca-bundle.crt file:
◦ Append the content of the Windchill Server SSL certificate
◦ Append the content of the ThingWorx SSL certificate
| | If Windchill is configured with a third-party SSL chain certificate, then append or copy the content of the Windchill and ThingWorx certificates to ca-bundle.crt in the following order: a. Windchill root certificate b. Windchill intermediate certificate c. Windchill server certificate d. ThingWorx certificate |
3. Save the ca-bundle.crt file.
4. Create an sslclientauth.conf file in <HTTPSERVER_HOME>\conf\sslvhostconf.d.
5. Edit sslclientauth.conf to add the following line:
SSLCACertificateFile <PATH_TO>\ca-bundle.crt
Replace <PATH_TO> with the file path for the ca-bundle.crt file.
6. Save the sslclientauth.conf file.
7. Edit the <HTTPSERVER_HOME>\conf\conf.d\20-mod_ssl.conf file:
◦ Uncomment the line containing the following (remove the hash character ( # ) at the start of the line):
SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
◦ Uncomment the line containing the following:
SSLVerifyDepth
8. Save the 20-mod_ssl.conf file.
9. Edit the <HTTPSERVER_HOME>\conf\httpd.conf file. Ensure that the following lines are not commented (remove any hash characters ( # ) at the start of these lines):
LoadModule log_config_module modules/mod_log_config.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
10. Save the httpd.conf file.
11. Open the <HTTPSERVER_HOME>\conf\conf.d\30-app-Windchill-Auth.conf file. Confirm that an sslClientAuth entry similar to the following is present:
# SSL client certificate authenticated resources
<IfModule ssl_module>
<LocationMatch ^/+Windchill/+sslClientAuth(;.*)?>
Require all granted
SSLVerifyClient require
SSLOptions +ExportCertData
</LocationMatch>
</IfModule>
<IfModule ssl_module>
<LocationMatch ^/+Windchill/+sslClientAuth(;.*)?>
Require all granted
SSLVerifyClient require
SSLOptions +ExportCertData
</LocationMatch>
</IfModule>
12. Restart the PTC HTTP Server with the -DSSL option to activate SSL.
13. Edit the <Windchill>\codebase\WEB-INF\web.xml file.
a. Locate <filter-name>TrustedSSLAuthFilter</filter-name>
b. Add a new init-param after an existing one:
<init-param>
<param-name>trustedSubjectPattern.1</param-name>
<param-value>.*[hostname].* </param-value>
</init-param>
<param-name>trustedSubjectPattern.1</param-name>
<param-value>.*[hostname].* </param-value>
</init-param>
Use the hostname from the certificate subject for [hostname]. For example, if the subject is CN=mycompany.domain.com, use mycompany for [hostname].
14. Save the web.xml file.
15. Restart Windchill.
Verify Your Configuration
Both Windchill and ThingWorx must agree on the name of the administrator user. Consider the following options:
• If you have not made changes in Windchill, an administrator user named Administrator was created when Windchill was installed. Using a configured ThingWorx system, you can authenticate as that user, and have full access rights as the administrator user in ThingWorx.
• If you have modified Windchill so there is no user named Administrator, then you must decide on a user name that is common to both Windchill and ThingWorx, and add that user to ThingWorx, to the Administrators user group.
To verify the Windchill authentication configuration, open a browser to the ThingWorx URL. The browser is routed to Windchill for authentication. Provide the Windchill credentials for Administrator (or another user configured as the ThingWorx administrator). The browser is routed back to ThingWorx Composer. Verify that you are now running in ThingWorx as that user. This verifies that ThingWorx is properly configured with Windchill authentication.
If you have selected to have the authenticator automatically create users, test that next. To verify, open a browser to the ThingWorx URL. You are rerouted to Windchill for authentication. Provide Windchill credentials of a user that does not exist in ThingWorx. The browser is routed back to ThingWorx, to the page specified as the home mashup for dynamically created users. Verify that you are now running as that user in ThingWorx.