Answer

Performing secure search in the Java programming language can be divided into two major functions:

• Building user security context (USC) information
• Setting the constructed USC to a query and running the query

The Identity Management Component (IMC) API helps you to create security context information in Java. The USC contains all of the credential information for a user who is authorized by a search application. For the data source to be searched, this credential information includes the applicable data source type, security domain, user name, encrypted password or single sign-on token, and names of groups to which the user belongs. The USC needs to be set to a query for later use by secure search.

The IMC API also provides a USC cache capability in the search server. For some types of data sources, it might take time to get group information for the given user. The USC cache can reduce the number of group extraction calls by reusing previously obtained credentials. It works effectively especially if the application needs to reuse credential information beyond multiple web sessions for the same user.

For example, the provided search application constructs the USC at the first login to the application, After that, it stores the USC into the IMC database for reuse. At the next login, it checks the expiration value for the cached credential and reuses it if it is valid. All of this processing can be done through the IMC API.

Here is a typical program flow for USC construction and reuse, assuming that the web user name can be obtained from underlying application server.

Initialization
Obtain an IdentityManagementFactory instance and create IdentityManagementService and ApplicationInfo instances. You can use a credential of Administrator for the search server authentication to get these instances.

The first time the search application user is authenticated
At this point, the USC for the user is not stored in the IMC database. You must construct the USC for the user:

1. Obtain a list of the secured data sources that are currently available for secure search by calling IdentityManagementService#getSecuredDataSources().
2. (Optional) Request the user to enter credentials for each data source.
3. Create a new Identity object and copy required parameters from a secured data source into the identity, and also set the given credential into the identity.
4. (Optional) Validate that the given credential is valid on the data source by calling IdentityManagementService#validateUserInformation().
5. (Optional) Have IBM Content Analytics with Enterprise Search extract group information from the data source by calling IdentityManagementService#getUserInformation().
6. Repeat steps 3 through 5 for all secured data sources.
7. Create a new SecurityContext instance with the web user name and all identities.
8. (Optional) Store the SecurityContext into the IMC database by calling IdentityManagementService#setSecurityContext().

The second time the user logs into the search application
This time, the USC might be stored in the IMC database. Check whether the stored information is valid or not, and reuse it if possible:

1. Load the SecurityContext for the user by calling IdentityManagementService#getSecurityContext().
2. Go through all of the identities inside the SecurityContext to validate whether the identity information is valid or expired. You can check the creation data with the property named "creationDate".
3. If one of the identities is expired, construct the USC again.

During the second phase for performing secure search, the USC that is set to a query is used by the search engine component to filter documents to make sure that the search results contain only documents that the given search user is allowed to see in terms of document security.

Assuming that you already constructed or loaded the SecurityContext, you can use the following code to set it to a Query object:

query.setACLConstraints("@SecurityContext::'" + context.serialize(true) + "'");


For coding examples of USC construction and secure search, see the IdentityManagementExample.java and SecuredSearchExample.java examples in the ES_INSTALL_ROOT/samples/siapi directory.

Note that you must construct USC information before performing secure search. The SecuredSearchExample.java example cannot be used on its own to implement an end-to-end search application.

You can also see more practical examples in the source code for the provided search application in the ES_INSTALL_ROOT/samples/search/src directory. The USC construction occurs in com.ibm.es.searchui.helpers.IdentityManagementHelper

For more detailed information, see the IMC API and SIAPI documentation in the ES_INSTALL_ROOT/docs/api directory.