User Tokens

This is a developer-level activity.

This topic shows how to use FileNet® P8 authentication tokens to set up a single sign-on mechanism for multiple Web applications. A token holds user ID, password, and other user credential information that is required to establish an application session. In the context of accessing multiple Web applications, the purpose of a user token is to allow a signed-on user of one application to access a resource on a second application without having to explicitly sign on to the second application. In effect, user tokens eliminate nuisance logons.

As discussed in the FileNet Web Application Toolkit Developer's Guide, Workplace and other FileNet P8 applications are built from Web Application Toolkit, and use the Toolkit's default implementation for generating and authenticating user tokens. The primary focus of this topic is to describe token sharing between Workplace and your custom Toolkit-based applications.

This topic consists of the following major sections:

Use Cases for Tokens

Workplace can be configured to generate and/or accept user tokens. One case for setting Workplace to accept tokens is presented by the Application Engine UI Service, allowing external applications to execute Workplace operations. When invoked by a call that includes a token, the AE UI Service will respond with the requested resource without first posting the Workplace sign-on page.

Common use cases for configuring Workplace to generate tokens are as follows:

In each of the above cases, you would configure Workplace to generate tokens to avoid the sign-on of the external application, that is, your Toolkit-based custom application. You would configure the external application to accept tokens.

In the case where you want to make Workplace resources available to users outside of your organization, you would set Workplace to both generate and accept tokens. For example, you could create a Workplace action on document objects that emails recipients with an HTML link for downloading a document via Workplace's WcmWorkplaceGetContentServlet. The link would include a user token so recipients could be authenticated with the credentials in the token, and thus gain access to the document.

NOTE  FileNet P8 4.0 provides support for Java™ Authentication and Authorization (JAAS) container-managed authentication, which represents enhancements to existing application-managed authentication features. JAAS facilitates integration with third-party SSO products that integrate with Java 2 Enterprise Edition (J2EE)/JAAS systems, such as Netegrity. However, when using JAAS container-managed authentication, Workplace does not generate user tokens because it does not have access to full user credentials and therefore, has nothing to encrypt as the basis for the token. As a result, in situations where Workplace might expose an action that invokes some piece of UI hosted by, for example, Records Manager (RM), and container-managed authentication is in use, the user will be presented with a second sign-in page when launching the RM-based action. To avoid the second sign-in page, the site must install and configure an SSO solution which offers JAAS support, such as Netegrity SiteMinder.

Configuring Applications to Use Tokens

This section describes how to configure multiple Toolkit-based applications to pass user tokens between one another.

NOTE The Workplace installer provides the option to generate maximum-strength or limited-strength keys. If you selected maximum-strength keys, your Java Development Kit (JDK) must include the Unlimited Strength Java™ Cryptography Extension (JCE) policy files. For more information, see "Working with Security" in the FileNet Content Java API Developer's Guide.

Token configuration requires the following tasks. For details on each task, click the applicable link.

UTCryptoKeyFile.properties

UTCryptoKeyFile.properties is the encryption key file used to encrypt and decrypt tokens. The Workplace installer creates UTCryptoKeyFile.properties and places it in the FileNet/Authentication directory.

For multiple applications to pass user tokens between one another, each participating application must use the same encryption key file. Therefore, copy the UTCryptoKeyFile.properties file installed with Workplace to all servers that are hosting a token-sharing application. (Token-sharing applications running on the same server can reference the same UTCryptoKeyFile.properties file.)

WcmApiConfig.properties

With the synched UTCryptoKeyFile.properties file available as a local file on each server hosting a token-sharing application, each application's WcmApiConfig.properties file must specify the token-encryption mode and the path to UTCryptoKeyFile.properties. WcmApiConfig.properties is located in <AE_install_path>/FileNet/Config/AE. Open WcmApiConfig.properties and set:

Note that the "UserToken" part of the key is the application ID; it identifies configuration settings for a particular application that will use them, in this case Workplace. For more information about application IDs, see "Security Concepts" in the FileNet Content Java API Developer's Guide.

bootstrap.properties

You must set the user token options in the bootstrap.properties file for each token-sharing application. If the participating applications are sharing a bootstrap.properties file, then you only have to set the options in the shared file.

The bootstrap.properties file is located in <AE_install_path>/FileNet/Config/AE. You can modify the token settings directly, or you can use the Site Preferences Bootstrap page provided by Toolkit-based applications, as shown in the screenshot below.

token-related options in bootstrap.properties

Set the following options:

Clock Synchronization

We strongly recommend that you set up an automated clock synchronization mechanism to synchronize clocks across all servers hosting a token-sharing application. If different servers' clocks are further apart than the configured timeout interval in bootstrap.properties, a just-generated token on one machine will appear expired on another machine.

Getting a Token

You must get a token before you can pass credentials to an application. How you get a token and from which application you get it depends on the following factors:

You can get a token in the following ways:

Getting a Token from the Content Java API

To get a user token from the Content Java API, you create a Session object, which generates a token, then you get the token from the object, as shown in the following code snippet.

   ...
   Session session = ObjectFactory.getSession("UserToken", null, "jDoe", "amico");
   String token = session.getToken(false);
   ...

In the above sample, the getSession() signature takes an application ID, domain, a user ID, and password. The application ID key "UserToken" is the default key used by Toolkit-based applications; in WcmApiConfig.properties, the key identifies the encryption key file used to encrypt and decrypt credentials. (The default is UTCryptoKeyFile.properties). With the application ID parameter set to "UserToken", the getSession() method generates an encrypted token. When the token is passed to another application, that application must use the same key file to decrypt the token.

Specifying false on the call to getToken() tells the Java API not to precompensate the token timestamp with the time difference between the machine running the Java API-based application and the Content Engine. When user tokens are being passed between two applications, precompensation should not be done.

NOTE  For more information on the Session class, see the Content Java API Reference, contained in the ZIP file "FileNet P8 Compatibility Layers for Content Engine APIs Help". To download this ZIP file from the IBM support site, see Accessing IBM FileNet documentation.

Getting a Token Using the Web Application Toolkit

The following code snippet is from a Java™Server Pages (JSP) page of a web application into which the user, Jon Doe, is currently signed in. It calls the static method getSessionToken() on WcmServerCredentials. Because user Jon Doe can be authenticated on any web application, the retrieved token is valid on any web application to which it is passed.

<jsp:useBean id="controller" class="<<webapp controller class>>" scope="request"></jsp:useBean>
<% // Get token from application that user is currently signed on to
   ...
   String token;
   token = controller.generateUserToken();
   ...
%>

Internally, the call to generateUserToken() generates the token based on the current signed-in user credentials and uses the application ID "UserToken". If you specify an application ID key, the returned token is encrypted. If you specify a null value for the application ID key, the returned token is clear. The recommended approach is to pass an encrypted or clear token to Workplace or other Toolkit-based web application. Note that in the bootstrap.properties file, the "acceptTokens" option of the target application must be set to true.

Using getUserToken() on UserTokenPolicy, a token can also be generated representing credentials for a user different from the current signed-in user. For example:

<jsp:useBean id="controller" class="<<webapp controller class>>" scope="request"></jsp:useBean>
<%
   UserTokenPolicyInterface userTokenPolicy = controller.getUserTokenPolicy();
   String token;
   token = userTokenPolicy.getUserToken("otherUser", "otherUserPassword", null, true);
%>

In the above example, the getUserToken() signature takes a user ID, password, extra parameters map (or null), and true or false to verify (or validate) the credentials. Internally, this call also uses the default "UserToken" application ID key value.

Sending Credentials

Once your application has the token, it can pass it to a Toolkit-based application on a request or as part of a set of page parameters (form data). A token is indicated by the following parameter:

WcmParameter.USER_TOKEN = <token>

  - OR -

ut = <token>

The following code snippet is from a JSP page of a Web application. The println statement creates a HTML anchor link that calls into the Workplace Application Engine UI Service. Note that before you pass the token, we recommend that you encode the token with the Java API method URLEncoder.encode(), or with the encodeURL method in the Workplace encode/decode utility class, WcmEncodingUtil.

<%
  ...
  token = URLEncoder.encode(token);
  out.println("<p><a href=\"http://server2:7001/Workplace/integrationWebBasedCommand?_commandId=2020" +
     "&WcmParameter.USER_TOKEN="+ token +
     "&_windowTitle="+ windowTitle +
     "&objectStoreName="+objStore +
     "&_responseURL=http://localhost:8080/custom/ThinClientOperations/OperationResult.jsp\"" +
     "target=\"newWindow\">Select Entry Template</a></p>");
  ...
%>

NOTE  If you use JavaScript to pass a user token, you can use the escape(…) function to encode the token. In addition, the URLEncoder.encode() method must be called two times, as follows:

...
String apiToken = fileNetSession.getToken(false);
String encodedAPIToken = URLEncoder.encode(apiToken);
String doubleEncodedAPIToken = URLEncoder.encode(encodedAPIToken);

...

In addition to the "WcmParameter.USER_TOKEN=..." or "ut=..." parameter, you can optionally pass the parameter impersonate="true". This parameter indicates that the the calling application should be signed on to the target application using the application ID provided in the token. The default behavior is for the calling application to be signed on with whatever application ID is defined for the Toolkit-based application.