Enabling Secure Search

Much of the information within an organization is publicly accessible. However, there are other sources that are protected. For example, while a user can search in their own e-mail folders, they should not be able to search anyone else's e-mail. A secure search returns only search results that the user is allowed to view based on access privileges.

Oracle SES can use the following two security modes: OracleAS Single Sign-on (SSO) or non-SSO. This is set on the Global Settings - Query Configuration page:

  • Require login to search secure content only: anyone can search public content. This is the default. This is also known as secure mode 2.

  • Require login to search secure and public content. This is also known as secure mode 3.

This is applied to both the default query application and Oracle SES Web services. In mode 3, if a user tries to perform any Web services operation (search or document service) without logging in first, then a SOAP exception is thrown indicating that this secure mode requires login for any operation.

This section describes the authorization methods that Oracle SES supports. The authorization methods prevent search users from accessing documents for which they do not have privileges.

Oracle Secure Enterprise Search offers several options for secure search:

User Authorization Cache

The User Authorization Cache (UAC) source type can crawl and cache user authorization information such as groups and accessible values of user security attributes. This cached information is used at query time to build a security filter. Querying a local cache is much faster than retrieving the authorization information from external repository and identity systems, and thus it significantly reduces the time to build the security filters for the current user. As a result, users can log in to Oracle SES much more quickly. Moreover, you can set up UAC sources to crawl the user authorization information off line, which reduces the load on target repositories at query time.

You can use UAC for sources that are based on either of the security models supported in Oracle SES:

  • Identity-based security: UAC is enabled for Oracle Internet Directory, Active Directory, and Lotus Notes.

  • Attribute-based security: UAC is enabled for Oracle Content Database and Oracle Content Server sources. This type of security is also called the user-defined security model.

The crawler stores the following information in the User Authorization Cache:

  • User groups: The list of groups that a user belongs to.

  • User attribute values: The values of a specified list of attributes for particular data sources. The values can be single values or arrays of values.

To create a UAC source for an identity plug-in: 

  1. Click the Sources tab.

  2. For Source Type, select User Authorization Cache, then click Create.

    The Create User-Defined Source page is displayed.

  3. Configure the UAC source with the parameters described in Table 11-5. Set Retrieve user groups to true.

  4. Create and activate the identity plug-in. Configure the plug-in to use the cache.

    For example, set these parameters for an OID plug-in:

    • Use User Cache: true

    • User Cache Source Name: Name of the UAC source that caches the user group information.

To create a UAC source for attribute-based security: 

  1. Click the Sources tab.

  2. For Source Type, select User Authorization Cache, then click Create.

    The Create User-Defined Source page is displayed.

  3. Configure the UAC source with the parameters described in Table 11-5. Be sure to set Source names for which security attributes should be crawled.

  4. Configure the data sources to use cached user authorization information for building security filter by setting appropriate UAC related parameters in the authorization plug-in.

    For example, set these parameters for Oracle Content Server source:

    • Use cached user and role information to authorize results: true

    • User role data source to cache the filter: Name of the UAC source that caches the user authorization information for this data source.

Table 11-5 User Authorization Cache Parameters

Parameter Setting

User search query

Query expression defining the set of users to be crawled. For example, enter a* to crawl all users whose names begin with the letter a. Leave this parameter blank to crawl all users who have logged into Oracle SES.

This expression is interpreted by the active identity plug-in. When the active identity plug-in is Oracle Internet Directory or Active Directory, specify the LDAP query to select the set of users to crawl.

User attributes to be synchronized from identity system

Comma-delimited list of user attributes to crawl, such as name, groups.

Not used in this release: Leave blank.

Retrieve user groups

Enter true to cache groups for users; otherwise, enter false.

Source names for which security attributes should be crawled

Enter a comma-delimited list of source names with security attributes to crawl. For example, source1, source2. The security model in these sources must be attribute-based security.

Federated User Authorization Cache

The Federated User Authorization Cache maintains a single User Authorization Cache (UAC) for use by all Oracle SES instances in a federated environment. Any identity plug-in or authorization plug-in can use a Federated UAC.


  • Define one or more UAC sources for an Oracle SES instance in the federated environment, as described in "User Authorization Cache". A local cache created on this system can be accessed as a federated UAC source by any other instance with an identically configured identity or authorization plug-in.

To create a federated UAC: 

  1. Click the Sources tab.

  2. For Source Type, select Federated UAC, then click Create.

    The Create Federated UAC page is displayed.

  3. Configure the federated UAC source with the parameters described in Table 11-6.

  4. Configure an identity or authorization plug-in:

    1. Select the Global Settings secondary tab.

    2. Under System, choose Identity Management Setup.

    3. Activate an identity or authorization plug-in. Enter the name of the federated UAC as the value of the User Cache Source Name parameter.

  5. Repeat these steps for each additional Oracle SES instance in the federated environment.

Table 11-6 Federated UAC Parameters

Parameter Setting

Connection String

JDBC connection string to a remote Oracle SES instance with one or more UAC sources. (Required)

Remote Cache Config File

Full path name of the XML configuration file for the remote cache, as described in Example 11-1. (Required)


Password for the eqsys user on the Oracle SES instance identified by Connection String. (Required)

Modifying the Remote Cache Configuration File

You can create the remote cache configuration file anywhere on the computer where you defined a federated UAC. You identify the location of the file when defining a Federated UAC source. The file provides details about the remote UAC source. Example 11-1 shows a sample file.

Example 11-1 Remote Cache Configuration File

<?xml version="1.0" encoding="UTF-8"?>


The name of a UAC source in a remote instance of Oracle SES from which the federated UAC retrieves user and attribute information. (Required)


Not supported in this release.


Maps the local source to a remote source with an identically configured authorization plug-in. (Required for attribute-based security)

Use these elements to provide the mapping information:

  • RemoteSourceName: Name of a remote source defined with a UAC and an authorization plug-in that is configured identically to the plug-in for LocalSourceName. (Required)

  • LocalSourceName: Name of the local source defined with a federated UAC and an authorization plug-in. (Required)

XML Schema Definition for Remote Cache Configuration Files

The following is the XML schema definition for remote cache configuration files:

<?xml version="1.0" encoding="windows-1252" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://www.example.org" attributeFormDefault="unqualified">
  <xsd:element name="FederatedUAC">
      <xsd:documentation>Federated Source Configuration</xsd:documentation>
        <xsd:element name="UserCache">
              Remote UAC Source Config Details
              <xsd:element name="Name" minOccurs="1">
                    UAC source name in remote instance from which 
                    user/attribute information must be retrieved
              <xsd:element name="UserRouting" minOccurs="0">
                     Which users should be routed to this UAC cache. Used for
                     identity-based security model.
              <xsd:element name="SourceMapping" minOccurs="0" maxOccurs="1">
                    To map data source prefix for user-defined security
                    attribute retrieval. This will be used in case of user
                    defined security model. The mapping information must be
                    mentioned in the form of remote and local data source names.
                    <xsd:element name="RemoteSourceName" maxOccurs="1" minOccurs="1">
                          Remote Instance Data source name prefixed to the
                          attribute while caching security attribute information
                    <xsd:element name="LocalSourceName" minOccurs="1">
                          Local Instance Data source name for which security
                          attribute is being retrieved

Administrator-Based Authorization

With administrator-based authorization, the administrator can specify an authorization policy when creating a source. This policy governs which users can view each document. Administrator-based authorization is based on ACLs. When a source is crawled, each document is stamped with an ACL. When a user enters a search, the result list only includes documents for which the user credentials match the document ACL.

See Also:

"Authentication and Authorization" for more information about ACL policies

Oracle SES performs ACL duplicate detection. If a crawled document's ACL exists in the Oracle SES system, then that ACL is used to protect the document, instead of creating a new ACL within Oracle SES. This policy reduces storage space and increases performance.

Oracle SES supports only a single LDAP domain. The LDAP users and groups specified in the ACL must belong to the same LDAP domain.


If ACLs are crawled from sources, then ensure that the sources being crawled belong to the same LDAP domain. Otherwise, the end users might inadvertently be granted permission to documents that they should not be able to access.

When secure search is enabled, you may encounter up to a 15 minute delay viewing the private documents. This delay could be due to newly added secure sources or a user/group membership change in the identity management system.

Custom Crawler Plug-in

Oracle Secure Enterprise Search provides an API for writing custom crawler plug-ins (or connectors) in Java. With this API, you can create a secure crawler plug-in to meet your requirements.

The custom crawler plug-in passes back URLs directly to be indexed. Each URL can be accompanied by an ACL, which restricts the access to that particular document. Alternatively, an ACL can be set in the Oracle SES Administration GUI for the source.

Authentication credentials can be provided to the plug-in through parameters in the Oracle SES Administration GUI. The plug-in uses these credentials to access the secure source.

Within the Crawler Plug-in API, the DocumentAcl object implements identity-based security. Identity-based security is a security policy based on users and groups that is defined by the active identity plug-in.

Identity-Based Secure Search

You can do identity-based secure search with administrator-based authorization or custom crawler plug-ins.

Oracle SES provides identity plug-ins for OpenLDAP release 2.2 and 2.3 and Sun Java System Directory Server release 5.1 and 5.2. Activate either of these identity plug-ins on the Global Settings - Identity Management Setup page.

To use administrator-based authorization: 

  1. On the Home - Sources page, select a source to use administrator-based authorization.

  2. On the Home - Sources - Customize Source page, click the Authorization tab.

  3. Under Crawl-time ACL Stamping, select Oracle Secure Enterprise Search ACL.

  4. For Type, select User or Group.

  5. Click Add Another Row.

  6. For User, select USER_NAME or something you want to use as Format and enter user name as Name. For Group, select DN as Format and input cn=<Group>,<Group search bases> as Name.

  7. Click Apply.

To use custom crawler plug-ins: 

  1. Create a custom crawler plug-in with the Crawler Plug-in API. See "Crawler Plug-in API".

  2. For User & Group, add the following line:

    DocumentAcl acl;
    // For User
    acl.addPrincipal("<User>", DocumentAcl.SIMPLE, DocumentAcl.USER);
    // For Group
    acl.addPrincipal("cn=<Group>,<Group search bases>", DocumentAcl.DN, DocumentAcl.GROUP);
  3. If you get an error registering the identity plug-in, check the WebLogic log files at ORACLE_HOME/search/base_domain/servers/AdminServers/logs/.

  4. For more detailed information, turn on debug mode and try again to register the identity plug-in. See "Turning On Debug Mode".

Limitations with OpenLDAP and Sun Java System Directory Identity Plug-ins

The LDAP entry of users and groups on OpenLDAP or Sun Java System Directory Server requires the following conditions:


  • Belong to the following objectClasses: person, organizationalPerson, and inetOrgPerson

  • Have the following attributes: dn, cn, sn

  • The entry's location: uid=<User>,<User search bases>


  • Belong to one objectClasse: groupOfUniqueNames

  • Have the following attributes: dn, uniqueMember

  • The entry's location: cn=<Group>,<Group search bases>

Query-time Authorization

Query-time authorization provides another form of filtering. Query-time authorization can be enabled or disabled for Web, file, table, e-mail, mailing list, OracleAS Portal, and user-defined source types from the Home - Sources - Edit Source page. It is not available for federated or self-service sources. Query-time authorization can be used with or without ACLs. For example, a source could be stamped with a relatively broad ACL, while query-time authorization could be used to further filter the results.

In query-time authorization, the Oracle SES administrator associates a Java class that is called at run time. The Java class validates each document that is returned in a user query.

Query-time authorization requires these steps:

  1. The Oracle SES administrator registers a Java class implementing the ResultFilterPlugin interface with a source that requires query-time authorization.

  2. Oracle SES crawls, collects, and indexes all documents. If ACL stamping has been set up, then it ACL stamps the documents.

  3. At search time, the search result list initially contains all documents accessible under crawl-time ACL policies, unfiltered by query-time user privilege checking.

  4. For the top-N results requested by the user, Oracle SES calls the registered Java class, passing in the search request and document information for any documents belonging to the protected source. The Java class returns an integer value for each document indicating if the document should be removed from the result or not.

  5. Only items the user is privileged to see are returned to the user in their result list.

Notes for Using Query-time Authorization: 

  • The Browse application is also filtered by the query-time authorization mechanism. The ResultFilterPlugin class controls which folders are visible to the user, and documents within folders are filtered by the same process as the standard search result list.

  • Set the Hit Count Method to Exact count (adjusted for query-time filtering) on the Global Settings - Query Configuration page. If it is not set to Exact Count, then the hit count displayed could be larger than the actual number of documents the user is authorized to view. The page in the Oracle SES Administration GUI contains other query-time authorization configuration settings you might want to consider.

    Oracle SES reports an approximate count of search results. The number of documents Oracle SES fetches determines the accuracy of the estimation. When the hit count is high enough to go beyond one page of results, then the count changes to a more accurate count as you click Next pages. Exact count shows an accurate count, but this option impacts query response time.


    While crawling secure data sources, the crawler skips infosource count-hit. Changing the ACL policy for a data source from secure to public does not result in an automatic update of the infosource count-hit. If you wish to include the data source in the infosource count-hit, you must recrawl the data source or trigger infosource update_doc_count for the data source.
  • If you modify the contents of the jar file containing the ResultFilterPlugin implementation classes, but do not change the location of the jar file, then you must restart the Oracle SES middle tier. This ensures that the search application picks up your changes and that the Java Virtual Machine does not use a cached version of the class within the old jar file. Restart the middle tier with searchctl restart.

  • If a ResultFilterPlugin class is enabled for an OracleAS Portal server, then all of its page group sources are automatically protected by that query-time filter.

  • It may take up to five seconds for query-time authorization changes applied in the Oracle SES Administration GUI to take effect in the Oracle SES search engine. The relevant settings are the following:

    • Enabling a ResultFilterPlugin class for a source

    • The hit count method

    • The Query-time Authorization Configuration settings on the Global Settings - Query Configuration page.

See Also:

"Query-time Authorization API" for more information about implementing a ResultFilterPlugin Java class

Self Service Authorization

Self service authorization allows end users to enter their credentials needed to access an external content repository. Oracle Secure Enterprise Search crawls and indexes the repository using these credentials to authenticate as the end user. Only the self service user is authorized to see these documents in their search results. Self service authorization works well out of the box, as the crawler appears to be a normally authenticated end user to the content repository.

To set up a self service source, create a template source, defining the target data repository but omitting the credentials needed to crawl. From the search application, an end user can view the Customize page and subscribe to a template source by entering their credentials in an input form. A new user-subscribed source is created, along with a copy of the template's schedule. Oracle SES creates an ACL for this user to be applied to the source.

User-subscribed sources are viewable in the Home - Sources - Manage Template Source page, and the associated schedules are administered in the Home - Schedules page. Any changes applied by the administrator to a template source are dynamically inherited by the associated user-subscribed sources for the next crawl.

The self service option is available for e-mail and Web sources. Self service e-mail sources require the administrator to specify the IMAP server address and the end user to specify the IMAP account user name and password. Self service Web sources are limited to content repositories that use OracleAS Single Sign-On authentication. The administrator specifies the seed URLs, boundary rules, document types, attribute mappings, and crawling parameters, and the end user specifies the single sign-on user name and password.

Crawling of user-subscribed sources is controlled by the administrator. End users do not see any search results for their subscribed source until that source is crawled by the administrator's schedule. Allowing a crawl to automatically launch immediately after an end user subscribes to a source might be useful. However, it makes it possible for users to load the system at inconvenient times.