Form-based Authentication

Before you can configure Windchill for form-based authentication, you must select a form-based authentication solution and make any required modifications for its use with Windchill. There are a variety of form-based authentication solutions ranging from SiteMinder to the form-based authentication support built into the embedded servlet engine. Although the individual configuration details are specific to the solution and are not documented here, the following sections include Windchill details that are important to understand. For details on setting up a form-based authentication solution, see the documentation provided by the solution.

Any changes you make to files that are delivered with your Windchill application should be treated as customized files that can be overwritten by PTC during any maintenance installation process. Ensure that customized files are backed up as described in Managing Customizations.

Since the log off capability that is available with form-based authentication is not available with the default basic authentication and, therefore, is not described in detail in end user documentation, users may not be aware of the ability to log off. When rolling out a Windchill environment in which form-based authentication is enabled, alert users as to how they can log off. If you change the default log off behavior for the Log Off menu option (which is described later in this section), be sure to also communicate the new behavior to users.

As part of setting up a form-based authentication solution, you must establish a login page that produces a simple XHTML representation of your login form that can be used by non-browser clients (for example, Java applications) to collect login data and post it to the URL specified by the wt.auth.form.submitUrl property. This page is necessary since non-browser clients need assistance in handling form-based authentication (which is, after all, an application convention intended for browser clients).

PTC provides the login.jsp file as the required login page representation used by non-browser clients. The file is located in the codebase/login subdirectory where Windchill is installed. Since the login.jsp file is used to represent the credential data fields required by the login form, you can edit the file to include appropriate display labels and form field names.

PTC recommends that you do not use the login.jsp file as the actual login form configured for your form-based authentication solution.

When configuring the form-based authentication solution, access to some Windchill URLs must be constrained by the solution, whereas others must not be constrained.

Relative Windchill web application URLs are stored in the <Windchill>/apacheConf/config/authResAdditions.xml file, where <Windchill> is the Windchill installation directory.

Each URL is stored in a resource tag. For example, the following resource tags are contained in the file:

<resource>pdmlink/jsp</resource>
<resource>servlet/WindchillAuthGW</resource>
<resource type="protocolAuth">protocolAuth</resource>
<resource type="anonymous">servlet/WindchillGW</resource>

With regard to form-based authentication, the URLs can be grouped as follows:

The URLs in resource tags with a specified type must not have a form-based authentication constraint applied; those URLs without a specified type must have a form-based authentication constraint applied.

Review the complete list of relative URLs in the file and ensure that only the set of URLs listed in resource tags that have no type attribute are constrained from the form-based authentication solution.

The following notes can helpful when considering which form-based authentication solution to use and implementing required changes:

• Clients that are not Java applications or browser pages do not have a plugin mechanism for logging in and, therefore, cannot support form-based authentication unless a login can be affected through collection of simple inputs and a POST to a specified URL. If you cannot simply collect inputs and POST form data to a URL to log in with the form-based authentication solution you have selected, then it will likely be necessary to produce a custom form-based login handler for non-browser Java clients.

• When implementing form-based authentication, you should be aware of how timeouts are handled. A default servlet session timeout of 30 minutes is set in <Windchill>/codebase/WEB-INF/web.xml. Additionally, you can provide an authentication timeout that is set within the form-based authentication solution. The authentication timeout is used whenever the form-based authentication solution is used and does not rely on the timeout of a servlet session.

When using a simple Tomcat-based file-based authentication, the session timeout and the authentication timeout are the same and are set in <Windchill>/codebase/WEB-INF/web.xml according to the J2EE standard. When using another file-based authentication solution, there are settings that can include an idle timeout as well as a hard timeout for limiting the maximum session duration.

After becoming aware that there is a form-based authentication timeout (set in the authentication solution) and that credential data (such as dynamically generated SecurID tokens) is used, it becomes clear that you cannot rely upon form-based authentication for non-interactive, unattended clients. For such clients, access should either use an anonymous trusted client arrangement, or use protocol-based authentication:

◦ For anonymous trusted client access (also known as Trusted Host Authentication), you can insert trustedAuth/ after the WindchillWebAppName/ in Windchill URLs.

You can use trusted authentication for both non-interactive authentication and for running tasks on behalf of various users without requiring authentication credentials. For more information, see the Javadoc on wt.httgw.filter.TrustedAuthFilter.

• Windchill Java command line utilities are generally treated as interactive, attended clients. If this is inappropriate for a given utility, the RMI authentication behavior of such clients can be adjusted.

After your form-based authentication solution is ready for use, complete the following configuration steps:

◦ Set the wt.auth.form.enabled property in wt.properties to true. This setting enables form-based authentication and updates the WindchillQuick Links menu to include the Log Off menu option.

◦ Set the wt.auth.form.submitUrl property in wt.properties to the URL used by clients to submit credentials for form-based authentication.

◦ Set wt.logout.url property in wt.properties to the URL you want used with the form-based authentication solution to perform a logout for the current authentication session.

The default URL is the Windchill base URL. Using the default URL assumes that the log off consists terminating the servlet session and sending a logout event to Windchill auditing services. Depending on the form-based authentication solution you have implemented, you may need different logout actions which then would require a different URL.

Form-based authentication cannot be transparently handled at the protocol level and some clients used to access Windchill must be specifically designed to support form-based authentication. For example, Windchill programs, such as visualization services or Windchill Desktop Integration, may require changes when form-based authentication is used.

For information about making visualization changes for form-based authentication, see WVS Considerations with Form-based Authentication.

For information about making Windchill Desktop Integration changes, see Desktop Integration under Advanced Customization.

Custom JSPs, SOAP services and Info*Engine tasks can be used with a form-based authentication solution.

When using a form-based authentication solution, the URLs used by clients to access the IE servlet, RPC, or the SimpleTaskDispatcher servlet must include the /protocolAuth URL prefix.

For additional information, see Interacting with Info*Engine.

If you are using supported third-party products, you must determine if any changes are needed in those products to support form-based authentication.

Cognos, for example, does not use the Windchill servlet engine and authenticating code; therefore, the built-in Windchill servlet-engine-based form-based-authentication cannot be used as a consistent single-sign-on between Windchill and Cognos. In a normal configuration, Cognos latches onto REMOTE_USER directly. If REMOTE_USER is not set, then Cognos requires special configuration to use form-based authentication.

Remove all but anonymous and protocol-based authentication constraints from the web server configuration.

For the Windchill web application from Apache-based web servers that are configured for Windchill, complete the following steps to remove all authentication constraints except those for protocol-only authentication and those asserting anonymous access:

1. Open a Windchill shell and navigate to the <Windchill>/<httpserver_home> directory, where <Windchill> is the Windchill installation directory and <httpserver_home> is the web server installation directory.

where <WindchillWebAppName> is the name of your Windchill web application as defined in the wt.webapp.name property in the wt.properties file (for example, Windchill).

The wt.properties property that enables the use of a form-based authentication solution is wt.auth.form.enabled.

By default, the use of a form-based authentication solution is disabled. To enable it, use the xconfmanager utility to set the property to true. For example from a Windchill shell, enter:

By enabling the use of a form-based authentication solution, you also enable the display of the Log Off menu option from the WindchillQuick Links menu that is located at the top right corner of the Windchill page:

When a user selects the Log Off menu option, the default behavior is that the Windchill servlet session ends and the log off event is captured in the Windchill audit log. User-initiated activities that are in progress at log off continue unless the activity attempts to access the servlet session. For example, if a user logs off after starting a search but before the search completes, the search errors out when it attempts to display the results. If a user has clicked Log Off after starting a checkin action, but before the check in confirmation has displayed, the checkin will complete, but an error will be logged when the confirmation cannot be displayed.

By default when the servlet session is the same as the authentication session, the user loses any state data associated with that session and is no longer logged in. After a user has logged off using the Log Off menu option, the page executes the Windchill base URL and, because the user is no longer logged in, the URL presents the user with a login form to allow the user to log back in.

You can change this default log off behavior by selecting different configuration settings in your form-based authentication solution and by setting a different URL in the wt.logout.url property in wt.properties. In the case of a form-based authentication solution that is not based on the servlet session (and thus whose authentication session is not terminated by terminating the servlet session), the URL set in the wt.logout.url property should be one that causes a logout for the current authentication session with your form-based authentication solution.