Process Engine authentication

In a change from previous releases, Process Engine relies on Content Engine for authentication and directory service access operations. The following sections describe the steps that occur as a client of Process Engine authenticates with Content Engine, and then sends the credentials obtained from Content Engine to Process Engine with each request.

Authenticating the Process Engine Java API client using Content Engine EJB Transport

The next figure shows a Process Engine Java™ API client in a FileNet P8 server environment. Note that both the Process Engine Java API and the Content Engine Java API must be present on the client machine. The Content Engine Client installation program installs the Content Engine Java API component, and the Process Engine Client installation program installs the Process Engine Java API. Note also that the figure assumes that the Content Engine Java API is configured to work over the EJB transport. See the following section for a discussion of how this will differ if the Content Engine web service transport is in use.

This figure represents a two-level authentication process, where the client first authenticates with JAAS. The client then authenticates with Content Engine, with the application server validating the JAAS credentials by invoking one of the configured Login Modules to confirm that the client's credentials are of a type accepted by this server and that they are valid. This establishes the caller's identity, and provides access to FileNet P8.

rocess Engine client first authenticates with JAAS on the app server and then with the Content Engine server.

Process Engine client first authenticates with JAAS on the app server and then with the Content Engine server.

The following steps occur as the Process Engine client application initializes and then makes a call to the Process Engine server:

  1. The Process Engine client performs a JAAS login, using the Login Module configured in the client environment. This login probably occurs before any interaction occurs with the Content Engine or Process Engine APIs. It may happen automatically as a result of a J2EE configuration, or the client may invoke the Login Module programmatically.

    Depending on what Login Module is in use, the Login Module may make a call to the enterprise directory service, possibly through a proxy or some intermediate SSO solution.

    NOTE  In the case of legacy applications (pre-4.0.0) which pass the user name and password to the Process Engine API, the API will perform a JAAS login using the FileNet P8 JAAS Login Context.

  2. The Process Engine Application makes a call to the Process Engine Java API.
  3. The Process Engine Java API sees that the client has not been authenticated to FileNet P8 yet, and therefore makes a call to the Content Engine Java API to obtain a FileNet P8 identity token.
  4. The Content Engine Java API makes a call to the server. At the Content Engine server, the call arrives at the J2EE application server's EJB container with the caller's JAAS Subject. The application server examines its security policy configuration, as well as how the Content Engine EJB is configured, to determine what security policy is in place. The application server determines whether the JAAS Subject associated with the incoming request matches one of the authentication providers that are configured and enabled for use with the EJB. If it does, the application server makes a call to this authentication provider which performs any necessary checks on the JAAS Subject (this might involve contacting a directory service or SSO provider to validate the Subject). If any part of this application server authentication process fails, an appropriate error is returned to the caller (note that this would occur before any logic within the Content Engine EJB is invoked).
  5. If the incoming JAAS Subject is validated by the application server, then the call is passed through to the Content Engine EJB, and the JAAS Subject is available to the Content Engine EJB.
  6. Within the Content Engine EJB, the Principal name is extracted from the JAAS Subject, and searched for in the Content Engine user cache. If not found, Content Engine calls the enterprise directory service to expand the caller's identity information.
  7. The EJB processes the incoming request. In this case, a FileNet P8 identity token is created, and returned to the caller (the Process Engine Java API).
  8. If all the above steps are successful, the Process Engine Java API now has a FileNet P8 identity token, obtained from a Content Engine server. The Process Engine Java API makes a call to the Process Engine server, passing the identity token as a parameter. The Process Engine server examines the identity token, and the signature on it is validated. If the signature is valid, then the Process Engine server trusts that the token and the user identified by the token are valid.
  9. This optional step is unrelated to the authentication process, but will occur in many cases. In this step, Process Engine wishes to retrieve the detailed user information (full name, DN, e-mail address, group memberships, etc.). It does so by calling Content Engine to retrieve the requested user and group objects.

The FileNet P8 identity token used to convey the identity of the caller from Content Engine back to Process Engine is protected by a pair of cryptographic keys. One of these keys is a secret shared between the Process Engine server and the Content Engine server, while another key is dynamically generated for use with each token.

Authenticating the Process Engine Java API client using the Content Engine web service transport

Process Engine authentication through Content Engine over the web service transport is supported only for the username/password case. Alternate credential types over the web service transport are not supported.

The diagram for this scenario is the same as in the previous topic, with the exception that the arrow in step 4 goes to the Web Service Listener, rather than going to the EJB Listener. The Web Service Listener then extracts the user's credentials from the WS-Security header, and performs a JAAS login using a Login Module that has been configured at the server. Once that step is complete, the web service listener forwards the call along to the EJB listener, and everything thereafter is the same as in the previous topic.

The Process Engine Web Service API client

The following graphic shows shows the Process Engine web service listener which is always co-resident with the Content Engine server.

Process Engine web service client sends a request to the Process Engine web service listener.

The following steps occur as Content Engine responds to a Process Engine web service-based application call:

  1. The Process Engine client sends a web service request to the Process Engine web service listener.
  2. The Process Engine web service listener obtains the JAAS subject by using the CE Web Services Authentication Framework, which expects to find the Username and Password in the SOAP Header based on the WS-Security UsernameToken profile.
  3. The Process Engine Application makes a call to the Process Engine Java API.
  4. The Process Engine Java API sees that the client has not been authenticated to FileNet P8 yet, and therefore makes a call to the Content Engine Java API to obtain a FileNet P8 identity token.
  5. The Content Engine Java API makes a call to the CE EJB home interface with the JAAS Subject obtained in step 2.
  6. Within the Content Engine EJB, the Principal name is extracted from the JAAS Subject and searched for in the Content Engine user cache. If not found, Content Engine calls the enterprise directory service to expand the caller's identity information.
  7. The EJB processes the incoming request. In this case, a FileNet P8 identity token is created, and returned to the caller (the Process Engine Java API).
  8. If all the above steps are successful, the Process Engine Java API now has a FileNet P8 identity token, obtained from a Content Engine server. The Process Engine Java API makes a call to the Process Engine server, passing the identity token as a parameter. The Process Engine server examines the identity token, and the signature on it is validated. If the signature is valid, then the Process Engine server trusts that the token and the user identified by the token are valid.
  9. This optional step is unrelated to the authentication process, but will occur in many cases. In this step, Process Engine wishes to retrieve the detailed user information (full name, DN, e-mail address, group memberships, etc.). It does so by calling Content Engine to retrieve the requested user and group objects.

NOTE  The only credential type supported for this scenario are username/password credentials. The Process Engine web service does not support the Web Services Extensible Authentication Framework (WS-EAF).