Skip Headers
Oracle® Secure Enterprise Search Administrator's Guide
10g Release 1 (

Part Number E10418-03
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

4 Security in Oracle Secure Enterprise Search

This chapter describes the architecture and configuration for Oracle Secure Enterprise Search (SES) security model.

This chapter contains the following topics:

Overview of Oracle Secure Enterprise Search Security

This section describes the Oracle SES security model. It contains the following topics:

Oracle Secure Enterprise Search Security Model

Oracle SES provides access to a variety of content repositories through a single gateway. Each one of these external repositories has its own security model that determines whether a particular user can access a particular document. All the aspects of security in Oracle SES must be carefully considered to respect the security of documents coming from multiple data repositories.

Oracle SES uses the following security services in its security model:

  • Oracle SES can use an identity plug-in to obtain user and group information directly from any identity management system. An identity plug-in is Java code that sits between Oracle SES and an identity management system, allowing Oracle SES to read user and group information.

  • Secure socket layers (SSL): This is the industry standard protocol for managing the security of message transmission on the Internet. This is used for securing RMI connections, HTTPS crawling, and secure JDBC.


Connecting to the Oracle SES server using SQL*Plus, except as documented in the guide, is not supported.

As an additional security measure, Oracle SES is configured to reject connection requests using SQL*Plus from remote hosts. The only protocols supported for connection to Oracle SES from remote hosts are HTTP, HTTPS, and AJP13. Changing the Oracle SES server directly using SQL and modifying initialization parameter files is not supported. User management, including password changes, should only be done using the Oracle SES administration tool.


The user name for Oracle SES is eqsys. You can change the password specified during installation on the Global Settings - Change Password page. After clicking Apply, a confirmation message appears if the password successfully changed. A password must have between 6 and 100 characters, including at least one numeric and and alphabetic character.

Temporary Passwords

For added security, a temporary password feature is provided. When creating table sources, e-mail, OracleAS Portal, or Web sources, login credentials for use by the crawler can be entered. (For Web sources, authentication can be performed with HTTP authentication, HTML forms, and OracleAS Single Sign-On.) These passwords can be removed from the Oracle SES repository after the schedule they are in completes. To use the temporary password feature, click the option to Delete Passwords After Crawl when creating or editing the source. This option is not available if self service for Web sources is enabled.

If a source has the Delete Passwords after Crawl option enabled, then the administrator will be prompted for all required passwords whenever the schedule for that source is launched. The supplied passwords will be removed immediately after the corresponding schedule completes. Because the administrator will be prompted for the passwords when launching the crawler, schedules containing sources having the Delete Passwords after Crawl option enabled must be launched manually.

Authorization and Authentication

This section contains the following topics:

Overview of Oracle SES Authorization and Authentication

Oracle SES security is implemented at the following levels:

  • User authentication

    This is the identification of a user through an identity management system. You can register an identity plug-in to any identity management system. (Oracle SES provides registered identity plug-ins for many identity management systems.) The plug-in that you activate is responsible for all authentication and validation activity in Oracle SES. This is done on the Global Settings - Identity Management Setup page.

    Security filter configuration for the identity plug-in is done on the Global Settings - Query Configuration page. A login does not force refresh the user's security filter. For a query request, Oracle SES checks the timestamp of an existing cached security filter and refreshes it if it has exceeded the specified life span. The default latency is 60 minutes.

  • User authorization

    This determines whether a user can access information about a particular item in the result list. It can be implemented in the following two layers.

    The first layer utilizes access control lists (ACLs). An ACL lists the users or groups of users that have access to the document. The ACL can be assigned by the administrator to an entire source through the administration tool (source-level ACLs), or it can be provided by the source itself for each document (document-level ACLs).The second layer uses a Java class to dynamically filter documents at search time (query-time authorization).

    Oracle SES can make use of the following types of ACL policies:

    • Source-level ACLs: These are defined on the Home - Sources - Authorization page. An individual source can be protected by a single ACL, which governs access to every document in that source.

    • Document-level ACLs: Oracle SES provides mapped security to repositories by retrieving the ACL for each document at the time of crawling and indexing. At crawl time, the ACL for each document is passed to the crawler along with the document content, and the ACL is stored in the index. Currently Oracle SES supports document-level ACLs for user-defined sources and OracleAS Portal sources. (The ACL policy is Documents Controlled by the Source.) With user-defined sources, ACLs are returned by the crawler plug-in implemented by the user. With OracleAS Portal sources, ACLs are returned by the OracleAS Portal server. At search time, Oracle SES does not need any connection with the repository to validate access privileges.


    For both source-level ACLs and document-level ACLs, all users and roles defined in the ACLs must exist in the identity plug-in.

    The following table shows when documents are visible with the document ACL types supported in Oracle SES:

    Table 4-1 Document ACL Types in Oracle SES Security Model

    Document ACL Type Public User Authenticated User Authenticated User with "allow" Permission to Document Authenticated User with "deny" Permission to Document

    No ACL

    document visible

    document visible



    "deny" Permission Only


    document visible



    "allow" Permission Only


    document visible


    "deny" with "allow" Permissions


    document visible


    The following table compares the document-level user authorization methods in Oracle SES.

    Table 4-2 User Authorization Methods in Oracle Secure Enterprise Search

    Method How Authorization is Determined Advantages Disadvantages


    The ACL is supplied by a crawler plug-in or an OracleAS Portal server.

    Faster secure search performance.

    No additional programming is required for ACL-based OracleAS Portal security. (If implementing a crawler plug-in, then some additional work is necessary to supply ACLs.)

    ACLs are static: they are updated only when crawling the source repository or when the administrator changes Oracle SES ACLs in the administration tool

    Query-time Authorization

    ResultFilterPlugin Java class.

    Dynamic authorization.

    Reflects real-time user access privilege on documents.

    There is performance overhead in cases when the search is not selective, returning large number of rows before query-time authorization.

    Extra work is required to implement a ResultFilterPlugin.


    For sources that do not fit the user/group model, an authorization plug-in provides a more flexible security model. With an authorization plug-in, a crawler plug-in can add security attributes similar to document attributes. The authorization plug-in is invoked at login time to build security filters onto the query string. The security filters are applied against the values of the security attributes for each document. Only documents whose security attributes' values match the security filter are returned to the user.

    See Also:

Restrictions on Changing the ACL Policy

On the Home - Sources - Authorization page, you can set and change the ACL policy. The following ACL policy options are available:

  • No ACL: With this setting, all documents are considered searchable and visible

  • Oracle Secure Enterprise Search ACL: With this setting (also known as source-level ACLs), you can protect the entire source with one ACL. The same ACL protects every document in that source.

  • ACLs Controlled by the Source: This setting (also known as document-level ACLs) is available only for OracleAS Portal sources and user-defined sources. This preserves authorizations specified in OracleAS Portal. For user-defined sources, crawler plug-ins (or connectors) can supply ACL information together with documents for indexing, which provides finer control document protection. (That is, each document in the source can have different access privileges.)

The following restrictions apply to changing the ACL policy:

  • If the schedule associated with the source is not currently being crawled, and if the source has never been crawled, then all ACL policy changes are allowed.

  • If the schedule associated with that source is currently being crawled (that is, the schedule status is Launching, Executing, or Stopping), then all ACL options are grayed out, and you cannot change the ACL policy.

  • If the schedule associated with the source is not currently being crawled, but the source has been crawled in the past, then the only change allowed is between No ACL and Oracle Secure Enterprise Search ACL (in either direction). This is visible in the administration tool as follows:

    • If the ACL option selected before the crawl started was ACLs Controlled by the Source, then all options are grayed out.

    • If the ACL option selected before the crawl started was No ACL or Oracle Secure Enterprise Search ACL, then the ACLs Controlled by the Source option is grayed out.


    If a secure ACL policy was selected but the identity plug-in is deactivated, then the ACL policy can be changed to No ACL, regardless of the crawl status.
  • OracleAS Portal sources are subject to the same restrictions as other sources. That is, no changes are allowed while being crawled, and only changes between No ACL and Oracle Secure Enterprise Search ACL are allowed after crawling completes. However, the ACL policy for an OracleAS Portal source can also change if it is inheriting the ACL policy from its OracleAS Portal server parent; for example, when the OracleAS Portal server's ACL policy is modified or when the OracleAS Portal source is changed from specifying the ACL policy locally to inheriting it from the server. Therefore, changes on an OracleAS Portal server are restricted so that no disallowed changes can occur on any children that inherit the ACL policy.

    If any child inheriting the ACL policy is being crawled, then no changes are allowed on the OracleAS Portal server. If any child inheriting the ACL policy has already been crawled, then the only changes allowed are between No ACL and Oracle Secure Enterprise Search ACL. (If the OracleAS Portal server policy is ACLs Controlled by the Source, then no changes are allowed). Similarly, the OracleAS Portal source cannot be set to inherit its ACL policy from the OracleAS Portal server if the associated change in ACL policy would be disallowed.


There is a difference between a source that is being crawled and a source whose associated schedule is being crawled. Oracle SES restricts all ACL policy changes for a source when the schedule associated with that source is being crawled. A source might not be crawling, but the schedule associated with it could be crawling if another source in the same schedule is being crawled.

Activating an Identity Plug-in

You can register an identity plug-in to any identity management system. Oracle SES provides registered identity plug-ins for many identity management systems. The plug-in that you activate is responsible for all authentication and validation activity in Oracle SES. Activate an identity plug-in on the Global Settings - Identity Management Setup page.


If you deactivate an identity plug-in, then you must restart the middle tier with searchctl restart.

The following table lists which identity plug-ins are available for each enterprise content source.

Table 4-3 Identity Plug-ins for Enterprise Content Sources

Source Type Versions Supported Identity Plug-in


Any databases with a JDBC driver


EMC Documentum Content Server

5.1, 5.2.5, 5.3 SP2

Active Directory, Oracle Internet Directory, Native

EMC Documentum eRoom


Active Directory, Oracle Internet Directory

FileNet Content Engine


Active Directory

FileNet Image Services

4.0 (ISRA 3.2)

Active Directory, Oracle Internet Directory, Native

Hummingbird Document Management Server

2004, 2005

Active Directory, Native

IBM DB2 Content Manager



Lotus Notes

5.0.9, 6.5.4,7.0

Active Directory, Oracle Internet Directory, Native

Microsoft Exchange

Windows 2000, Windows 2003

Active Directory

Microsoft SharePoint Portal Server


Active Directory


Windows 2000, Windows 2003

Active Directory, Oracle Internet Directory

Open Text Livelink

9.2, 9.5, 9.5.5

Active Directory, Native

Oracle Calendar

10.1.2 or later

Oracle Internet Directory

Oracle Content Database

Oracle Content Services 10.1.2 or later, Oracle Content Database 10.2 or 10.1.3

Native, Query-time authorization

Oracle E-Business Suite 11i



Oracle E-Business Suite 12



Oracle Mail


Oracle Internet Directory

Siebel 7.8



Siebel 8



Oracle Content Server

7.1.1, 7.5.2, 10gR3


Activating the Active Directory Identity Plug-in

When connecting to Active Directory, Oracle SES will assume that the Active Directory domain name can be resolved to an IP address of the Active Directory Domain Controller. This is generally not the case, especially when Oracle SES is installed at non-Windows computer or Window computer within different domain. The IP address of the Active Directory domain must be added to the hosts file.

For example, to connect to an Active Directory domain called, you must add something similar to this to the hosts file: 123.321.1.2 The hosts file is usually found at C:\Windows\System32\Drivers\etc\HOSTS on Windows, and /etc/hosts on UNIX.

For the Active Directory identity plug-in enter values for the following parameters:

  • Directory URL: ldap://<Active Directory server>:389

  • Directory account name: <User Logon Name> Confirm the user logon name on the Active Directory Users and Computers application. Under the User folder, right-click username. Select Property and go to the Account tab. For example, assume the user account adtest in domain, which is associated with the target Active Directory. You may try domain1\adtest or or cn=adtest,cn=users,dc=domain1,dc=company,dc=com if you are not sure the actual user logon name. The user account does not need to be an administrator account.

  • Directory account password: <Password for this Directory account>

  • Directory subscriber: dc=domain1,dc=company,dc=com, if your domain name is

  • Directory security protocol: none

Re-registering Preinstalled Identity Plug-ins

If a pre-installed identity plug-in is accidentally removed, you can re-register it with the following steps:

  1. On the Global Settings - Identity Management Setup page, click Register new Identity Plug-in.

  2. Enter the class name and jar file name of the removed identity plug-in:

    Table 4-4 Identity Plug-in Class Names and Jar File Names

    Identity Plug-in Plug-in Class Name Jar File Name

    Documentum Content Services


    FileNet Image Services


    Hummingbird DMS


    Open Text Livelink Content Services




    Oracle E-Business Suite 11i


    Oracle E-Business Suite 12


    Siebel 7.8


    Siebel 8


    Oracle Content Server


    Oracle Internet Directory


    IBM DB2 Content Manager


    Active Directory


    Sun Java System Directory Server


    OpenLDAP Directory


    Lotus Notes


  3. Click Finish.

Restrictions on Changing the Identity Plug-in

The information Oracle SES saves from the identity plug-in (that is, the correspondence between names and canonical attribute values) may not be valid on different identity plug-ins. If you keep the same identity plug-in server (for example, to change port numbers or to switch to SSL), or if you use a new directory server that has identical user information, then you can deactivate and re-activate the identity plug-in anytime without restriction. This section describes steps you must perform if you change identity plug-in servers with user information that is not identical.

If you have sources using the ACL policy Oracle Secure Enterprise Search ACL and you decide to use a different identity plug-in server, then you must clear the ACL data before deactivating the original identity plug-in. If the ACL data is not cleared, then the ACL policy configured for that source while connected to the old identity plug-in server will not be correctly enforced after connecting to the new identity plug-in server.

The existing ACL data can be cleared using either of the following two ways:

  • Before deactivating the identity plug-in, for each source using the ACL policy Oracle Secure Enterprise Search ACL, switch the ACL policy to No ACL. After connecting to the new identity plug-in server, restore the ACL policy to Oracle Secure Enterprise Search ACL and add the ACLs again. Note: This will temporarily make the source public. If this is unacceptable, then use the next option.

  • Before deactivating the identity plug-in, delete each source that uses the ACL policy Oracle Secure Enterprise Search ACL. After connecting to the new identity plug-in server, add the sources back and configure them again. The documents are never made public; but this may involve more work than the previous option.

If you have sources using the ACL policy ACLs Controlled by the Source and you decide to use a different identity plug-in server, then after activating the new identity plug-in server, each source that uses this ACL policy must be re-crawled with the Process All Documents option. This forces the reloading and indexing of all of ACL information for such sources with respect to the new identity plug-in server. Set the Process All Documents option on the Home - Schedules - Edit Schedule page.


if the ACL data is not cleared before switching identity plug-in servers, then you will see a message that some users and groups could not be found by the identity plug-in. Those users and groups are still displayed on the Home - Sources -Authorization page. They can be manually deleted.

Authentication Methods

The Oracle SES front-end interface collects user credentials, which are then validated against the active identity plug-in. In addition to authentication of search users, Oracle SES must also authenticate the crawler when accessing external data repositories. Administrators supply credentials to crawl private content through the following authentication methods:

  • HTTP authentication (both basic and digest authentication)

  • HTML forms

  • OracleAS Single Sign-On

It is the administrator's responsibility to check the authorization policy to make sure that crawled documents are properly protected.

Oracle Secure Enterprise Search User Repository

Oracle SES has two types of users:

  1. Administrative User: The administrative user is called eqsys. This user is natively defined in Oracle SES. Only this user can use the administration tool.

  2. Search Users: Oracle SES lets you register an identity plug-in as an interface to any identity management system. (Oracle SES provides registered identity plug-ins for Oracle Internet Directory and other identity management systems.) The plug-in that you activate is responsible for all authentication and validation activity in Oracle SES. Use the Global Settings - Identity Management Setup page in the administration tool to associate Oracle SES with an identity management system.


    Oracle Internet Directory is Oracle's native LDAP v3-compliant directory service. It is part of the Oracle Identity Management infrastructure. It is not included in Oracle SES. Oracle Internet Directory should be version 9.0.4 or 10.1.2 (with the latest patch release applied) for connection with Oracle SES. Oracle Internet Directory is not a part of Oracle SES, and therefore Oracle SES can be linked to any existing or new Oracle Internet Directory.

Oracle Secure Enterprise Search Authentication Interface

For the administrative user eqsys, there is a form login screen in the Oracle SES administration tool. This is the only way an administrative user can log in to Oracle SES.

For search users, there are three possible front-end authentication interfaces:

  • HTML form login page. Oracle SES provides an authentication page, and it authenticates against the identity plug-in.

  • Web Services API. The login and logout Web Services operations authenticate against the identity plug-in.

  • Single sign-on login screen. This can be made available by front-ending Oracle SES with OracleAS Single Sign-On and Oracle HTTP Server. These are available as part of the Oracle Identity Management infrastructure in OracleAS.


  • Only form login or single sign-on login can be used for search users at any point in time. Using single sign-on with the Web Services authentication interface is not supported.

  • Oracle strongly recommends that you SSL-protect the channel between the Oracle HTTP Server and the Oracle SES OC4J instance for secure content.

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: single sign-on (SSO) or non-SSO. This is set on the Global Settings - Query Configuration page:

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.

See Also:

The Oracle SES administration tutorial at

Secure Search Options

Oracle Secure Enterprise Search offers several options for secure search:

Admin-based Authorization

With admin-based authorization, when creating a source, the administrator can specify an authorization policy. This policy governs which users can view each document. Admin-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 will only include documents for which the user's credentials match the document's ACL.

See Also:

"Authorization and Authentication" for more information about ACL policies

Oracle SES performs ACL duplicate detection. This means that if a crawled document's ACL already exists in the Oracle SES system, then the existing 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, it is possible that end users are inadvertently granted permission to documents that they should not be able to access.

When secure search is enabled, you could 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 administration tool for the source.

Authentication credentials can be provided to the plug-in through parameters in the administration tool. 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 admin-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.

Admin-Based Authorization

Follow these steps to use admin-based authorization:

  1. On the Home - Sources page, select a source to use admin-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. Select User as Type, or select Group as Type.

  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.

Custom Crawler Plug-ins

Follow these steps to use custom crawler plug-ins:

  1. Create a custom crawler plug-in with the 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);


If you get any errors registering the identity plug-in, check the OC4J log file at $ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/log/oc4j.log. 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.

Here are the steps involved in query-time authorization:

  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 also 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 not, then the hit count displayed could be larger than the actual number of documents the user is authorized to view. The page in the administration tool 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.
  • 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 administration tool 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 will 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 unintentionally (or intentionally) load the system at inconvenient times.

Configuring Secure Search with OracleAS Single Sign-On

If you use OracleAS Single Sign-On (SSO), then you can configure Oracle SES to use your SSO server for authentication. This section describes the necessary configuration steps.


OracleAS supported versions are 9.0.4 and 10.1.2, with the latest patch sets applied.

$AS_HOME refers to the Oracle home directory of the OracleAS middle tier installation.

The following graphic illustrates the configuration:

Description of benri009.gif follows
Description of the illustration benri009.gif

To SSO-enable Oracle SES, perform the following steps:

  1. Front the Oracle SES instance with the Oracle HTTP Server of your OracleAS middle tier. (See "Using mod_oc4j to Front Oracle Secure Enterprise Search with an Oracle HTTP Server")

    On the OracleAS side, perform the following steps:

  2. Configure mod_osso to protect the search with SSO. Add the following lines to $AS_HOME/Apache/Apache/conf/mod_osso.conf in the IfModule element:

    <Location /search/query/formlogin.uix>
      require valid-user
      AuthType Basic
  3. Restart Oracle HTTP Server. On the OracleAS middle tier host, run the following command:

    $AS/opmn/bin/opmnctl restartproc process-type=HTTP_Server
    opmnctl: restarting opmn managed processes...

On the Oracle SES side, perform the following steps:

  1. Activate an identity plug-in on the Global Settings - Identity Management Setup page.

  2. Specify when end user authentication is required. Oracle SES requires end users to login to search secure content. This is the default. If you want to require end users to login to search both private and public content, then change the setting on the Global Settings - Query Configuration page.

Using mod_oc4j to Front Oracle Secure Enterprise Search with an Oracle HTTP Server

The Oracle SES middle tier runs in the embedded standalone OC4J. Oracle HTTP Server, on the other hand, contains a module called mod_oc4j that allows it to take the role of a frontend HTTP listener to OC4J. HTTP client requests go to the Oracle HTTP Server, which in turn, using mod_oc4j, communicates with OC4J through the AJP13 protocol. This makes it possible to front an Oracle SES instance using Oracle HTTP Server.


When using Oracle HTTP Server fronting, Oracle SES allows the Oracle HTTP Server to assert the identity of the current user; therefore, it is of outmost importance to limit this privilege to only trusted Oracle HTTP Server instances. This is done by SSL-protecting the communication between Oracle SES and Oracle HTTP Server.

Special configuration is necessary on both the Oracle SES side and the Oracle HTTP Server side.

On the Oracle SES side, do the following:

  1. Edit the $ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/config/http-web-site.xml file. To the <web-site> element, add the attribute protocol="ajp13". For example:

    <web-site ... protocol="ajp13" ... >
  2. Enable SSL. (See "SSL and HTTPS Support in Oracle Secure Enterprise Search".)

  3. Restart the Oracle SES middle tier using searchctl restart.

Next, on the Oracle HTTP Server's middle tier, perform the following steps:

  1. Configure Oracle HTTP Server to forward requests to the Oracle SES middle tier. Edit the $AS_HOME/Apache/Apache/conf/mod_oc4j.conf file. In the IfModule element, add the following line:

    Oc4jMount  /search/*   ajp13://<sesHost>:<sesPort>

    where <sesHost> and <sesPort> are the host name and middle tier port number of the Oracle SES instance

  2. Enable SSL. (See "Enabling SSL in Oracle HTTP Server's mod_oc4j Module".)

  3. Restart Oracle HTTP Server. On the OracleAS middle tier host, run the following command:

    $AS_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server

At this point, to access the Oracle SES middle tier you need to go through the Oracle HTTP Server. In other words, for the Oracle SES URLs you now have to use the host and port of the Oracle HTTP Server. The original URLs are no longer accessible.


It is important to activate the identity plug-in before you configure SSO. After the Oracle SES instance is behind SSO, identity plug-in activation does not work.

SSL and HTTPS Support in Oracle Secure Enterprise Search

For SSL support, Oracle SES uses JSSE, a highly-customizable SSL package included in Sun Microsystem's J2SE. Oracle SES uses SSL for many operations, some acting as the SSL client, and others acting as the SSL server.

Oracle SES can crawl HTTPS-based URLs, and the Oracle SES middle tier can be configured to support HTTPS-based access. HTTPS is nothing more than HTTP running over a secure socket layer (SSL).

Understanding SSL

SSL is an encryption protocol for securely transmitting private content on the internet. With SSL, two parties can establish a secure data channel. SSL uses a cryptographic system that uses two keys to encrypt data: a public key and a private key. Data encrypted with the public key can only be decrypted using the private key, and vice versa.

In SSL terms, the party that initiates the communication is considered the client. During the SSL handshake, authentication between the two parties occurs. The authentication can be one sided (server authentication only) or two sided (server and client authentication).

Server authentication is more common. It happens every time a Web browser accesses a URL that starts with HTTPS. Thanks to server authentication, the client can be certain of the server's identity and can trust that it is safe to submit to the server secure data, such as login username and password.

The following list defines some common terms related to SSL:

  • Keystore: A repository that includes the following:

    • Certificates identifying trusted entities. When a keystore only contains certificates of trusted entities it can be called a truststore.

    • Private-key and the matching certificate. This certificate is sent as a response to SSL authentication challenges.

  • Certificate: A digital identification of an entity that contains the following:

    • SSL public key of the server

    • Information about the server

    • Expiration date

    • Digital signature by the issuer of the certificate used to verify the authenticity of the certificate

  • Certificate authority (CA): A well known and trusted entity (for example, VeriSign or Thawte). CAs are usually the issuers of other certificates

  • Root certificate: A self-signed certificate where the issuer is the same entity as what the certificate represents. CA certificates are generally root certificates.

  • Certificate chain: This chain is comprised of the certificate, its issuer, the issuer of the issuer, and so on, all the way to the root certificate. If one certificate in the chain is trusted (that is, it is in the keystore), then the rest of the certificate can be verified for authenticity. This makes it possible for a keystore to contain only a few well-known and trusted root certificates from which most other certificates originate.

Every SSL connection starts with the SSL handshake. There is quite a bit involved in the SSL handshake. This section describes the basic steps involved in it:

  1. The client contacts the server to establish a SSL connection.

  2. The server looks in its keystore for its own SSL certificate and sends it back to the client.

  3. The client checks its keystore to see if it trusts the server or any of the entities in the server's certificate chain. If not, then the handshake is aborted. Otherwise, the client positively identifies the server and deems it trusted. The expiration date of the certificate is also checked, and the name on the certificate is matched against the domain name of the server.

  4. If the server is configured to require client authentication, then the server will ask the client to identify itself, so the mirror image of steps 2 and 3 will take place.

  5. Session keys are generated. From now on, session keys are used for encrypting exchanged data.

Managing the Keystore

Out of the box, Oracle SES uses the default keystore in J2SE: $ORACLE_HOME/jdk/jre/lib/security/cacerts. The keystore's password is changeit. This keystore is populated with the root certificates representing the well known certificate authorities. (Most SSL-enabled Web sites use certificates that originate or chain from these main root certificates.)

Depending on requirements, the keystore might still need maintenance. For example:

  • If one of the main root certificates expires, then it will need to be replaced by a new issue.

  • If Oracle SES needs to trust another SSL-enabled peer whose certificate does not originate from one of the root certificates, then the peer's certificate, or one from its chain, needs to be added to the keystore.

  • To enable SSL in the Oracle SES middle tier, Oracle SES must act as an SSL server, and that calls for the keystore to contain a private key and the corresponding certificate with the public key. (The same holds true for the SSL client role where the server requires client side SSL authentication.)

Maintenance of the keystore can be done using Sun's keytool program, which ships with J2SE. (You can find this tool under $ORACLE_HOME/jdk/bin). Third-party keytool GUI wrapper programs are available.

See Also: for detailed instructions on how to add, remove or update certificates, generate keys, and create new keystores with keytool

Oracle SES Acting as an SSL Client

Oracle SES acts as the SSL client in the following situations:

  • The crawler accesses a data repository that uses SSL (for example, HTTPS Web sites).

  • The form registration wizard in the administration tool accesses HTTPS URLs.

  • Oracle SES federates queries to other SSL-enabled search services (for example, an SSL-enabled Oracle SES instance).

If you crawl an SSL-enabled Web site whose SSL key is not in the SSL keystore, the following error will occur:

@ No trusted certificate found 

To resolve this, do the following:

  1. Access the page in a browser, and accept the SSL certificate when prompted.

  2. View the certificate through your browser options.

  3. Import the certificate into the SES keystore.

  4. Try the crawl again.

See Also:

The following sections explain how to import certificates

Oracle SES Acting as an SSL Server

Oracle SES acts as the SSL server when the Oracle SES middle tier, configured to use SSL, responds to HTTPS or AJP13 requests. The Oracle SES crawler connects to SSL-enabled sites using the JSSE package, which contains a keystore with a few default certificates from well known CAs.

This section contains the following topics:

Configuring Oracle Secure Enterprise Search to Require SSL

Clients (Web browsers, Web service clients, and so on) interact with Oracle SES directly using HTTP. If Oracle SES is fronted by Oracle HTTP Server, as it is needed for SSO support, then HTTP clients interact with Oracle HTTP Server, and Oracle HTTP Server forwards the requests to Oracle SES using AJP13.


When Oracle SES is configured to use the AJP13 protocol (that is, when Oracle SES is fronted by an Oracle HTTP Server), it is strongly recommended that Oracle SES be configured to require SSL with client-side authentication for communication with the Oracle HTTP Server. Furthermore, a keystore other than the default one should be used. While the default keystore contains the trusted certificates of all the major Certificate Authorities, the keystore used for the AJP13 SSL channel must contain ONLY Oracle SES's own certificate and the trusted certificate of the fronting Oracle HTTP Server.

The communication channel between the client and Oracle SES is (by default) not SSL-enabled and not encrypted. To protect this channel with SSL, follow these steps:

  1. Shut down the middle tier with $ORACLE_HOME/bin/searchctl stop.

  2. Change to directory $ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/config.

  3. Edit the http-web-site.xml file.

    To the <web-site> element, add the attribute secure="true". For example:

    <web-site ... protocol="http" secure="true"... >

    To the web-site element, add the <ssl-config> subelement and its keystore and keystore-password attributes, which specify the directory path and password for the keystore. For example:

    <web-site ... secure="true" ... >
       <ssl-config keystore="$ORACLE_HOME/jdk/jre/lib/security/cacerts" 
                   needs-client-auth="false" />

    To the <web-app> elements, add the attribute shared="true". For example:

    <web-app application="search_query" . . . shared="true" />

    If the protocol attribute is set to AJP13 (that is, if Oracle SES is fronted with Oracle HTTP Server), then use SSL to control which Oracle HTTP Servers are allowed to front Oracle SES. To do this, configure Oracle SES to require client-side SSL authentication, and make sure that the keystore specified in the <ssl-config> element only contains the SSL certificate of the fronting Oracle HTTP Server.

    For example:

    1. In the <ssl-config> element added earlier, set the attribute keystore="./cacerts" and set needs-client-auth="true".

    2. From the administrator of the fronting Oracle HTTP Server, get its SSL certificate and import it into the keystore specified in the <ssl-config> element. For example:

      $ORACLE_HOME/jdk/bin/keytool -import -keystore ./cacerts -trustcacerts
      -alias myOHS -file <path to the file containing the Oracle HTTP Server's 
      certificate (for example, "/temp/ohs.cer")>

      If the keystore specified using the keystore argument does not already exist, then a new empty keystore will be created. You will be asked for the keystore password. The default keystore password is changeit. You will be asked for confirmation to import the certificate into your specified keystore.


    If Oracle SES is fronted with Oracle HTTP Server, and Oracle SES is configured to require SSL for its communication with Oracle HTTP Server, then Oracle HTTP Server's mod_oc4j module also needs to be configured for SSL. For more information, see "Enabling SSL in Oracle HTTP Server's mod_oc4j Module" or see the OracleAS documentation.
  4. Using keytool, add a key/certificate pair to the keystore specified in the <ssl-config> element.

    • The name on the certificate should be the host on which Oracle SES is running.

    • The key algorithm should be "RSA" (that is, use the keytool option "-keyalg RSA")

    • If the certificate is not issued or signed by a well-known CA, then the certificate, or one in its chain, must be added to the keystore of every client that will communicate with the Oracle SES instance.

    Suggestion: Backup the keystore before modifying it.

    For example:

    $ORACLE_HOME/jdk/bin/keytool -genkey -keyalg RSA -alias oses 
    -keystore <path to the keystore as specified in the keystore attribute 
    of the <ssl-config> element>

    You will be asked a series of questions. When asked, "What is your first and last name?", specify the host name of the Oracle SES computer. For example,

  5. If you are using a certificate that is not signed by a well-known CA (the earlier example creates a self-signed certificate), then export the Oracle SES certificate so that it can be imported as a trusted certificate for clients:

    $ORACLE_HOME/jdk/bin/keytool -export -alias oses 
    -keystore <path to keystore> 
    -file <path to file for exported certificate, for example /temp/oses.cer>
  6. Start the Oracle SES middle tier with $ORACLE_HOME/bin/searchctl start.

Enabling SSL in Oracle HTTP Server's mod_oc4j Module

The previous section described the configuration steps on the Oracle SES side of the communications channel. This section describes the configuration steps for the Oracle HTTP Server.

Configuring the Oracle HTTP Server to require SSL for its AJP13 communication channel with Oracle SES does not change the manner in which Web browsers or other HTTP clients communicate with the Oracle HTTP Server.

The following steps SSL-enable mod_oc4j:

  1. Set up an Oracle Wallet to be used as an SSL keystore by the mod_oc4j module. The Oracle Wallet must contain a valid key-cert pair. If such a wallet exists, then skip to step 2.

    1. Create a new wallet using Oracle Wallet Manager ($OH/bin/owm). You will be asked to specify the directory in which to hold the wallet and the password for the wallet. Under the Wallet menu, turn on the Auto Login option.

    2. Create a key-cert pair (that is, a user certificate). Note that the CN part of the DN of the subject of the user certificate needs to set to the computer host name. Also, note that the DN is case sensitive, so make sure to use the same case consistently.

      If the Oracle HTTP Server version is 10.1.2 or later, then you can do this using the orapki utility:

      $AS_HOME/bin/orapki wallet add 
      -wallet <path to directory containing the wallet> 
      -dn <DN of the subject 
      (for example,,OU=oses,O=oracle,ST=ca,C=US)> 
      -keysize 1024 -self_signed -validity 720

      If the Oracle HTTP Server version is earlier than 10.1.2, then you have to create a certificate request using the Oracle Wallet Manager, have the certificate request signed by a CA, and then use Oracle Wallet Manager to import the CA signed certificate back into the Oracle Wallet.

      The Operations menu lists the options to create a certificate request and then export that request. Export the request to a file (for example,

      To get the certificate signed you have three options:

      - Send the certificate request to a well known CA, such as VeriSign, to have it signed. A fee is charged for this. If you plan to use the same Oracle Wallet and certificate for HTTPS enabling your production Oracle HTTP Server, then this method is recommended.

      - If you are using OracleAS Certificate Authority, then you can use it to sign the certificate request.

      - You can use OpenSSL to create a CA and use it to have your certificate request signed. For instructions on how to do this, see "OpenSSL as a Certificate Authority".

      After you get your certificate request signed, import the response into the Oracle Wallet.

      See Also:

      "Managing Wallets and Certificates" in the Oracle Application Server Administrator's Guide for more information on Oracle Wallets and the orapki utility
  2. Exchange trusted certificates with the Oracle SES Server which is to be fronted by this Oracle HTTP Server. Use the Oracle Wallet Manager to import/export certificates to and from the Oracle Wallet and use the Java keytool for the Oracle SES keystore.

    When importing a certificate, if the certificate is not self-signed, then before importing it you must import the certificates in its chain.

  3. Enable SSL in the mod_oc4j module (if not already enabled).

    Navigate to the $AS_HOME/Apache/Apache/conf directory and edit the mod_oc4j.conf file by adding the following directives in the IfModule element:

    Oc4jEnableSSL On
    Oc4jSSLWalletFile <path to the DIRECTORY containing the oracle wallet>

    After mod_oc4j has been configured to use SSL, it will only be able to front AJP13 servers that also have been SSL-enabled.

  4. Restart Oracle HTTP Server. On the OracleAS middle tier host, run the following command:

    $AS_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
OpenSSL as a Certificate Authority

OpenSSL is an open source SSL toolkit that can be used to create a CA and use the CA to sign other certificate requests.

  1. Install OpenSSL

  2. Setup the OpenSSL directory structure:

    mkdir makecert
    cd makecert 
    mkdir demoCA
    cd demoCA
    mkdir certs crl newcerts private
    touch index.txt
    echo "01" > serial
    cd ..
  3. Create the CA (self signed key-cert pair):

    openssl genrsa -out ca.key 1024
    openssl req -new -x509 -key ca.key -out demoCA/cacert.pem

    At this point, you are ready to sign SSL certificate signing requests generated by tools like keytool or Oracle Wallet Manager. Assuming that the certificate signing request is, run the following commands:

    openssl ca -keyfile ca.key -in -out clientapp.pem
    openssl x509  -outform DER -in clientapp.pem -out clientapp.der

    The first command signs the certificate, and the second command transforms the signed certificate into the DER format.

    The signed certificate clientapp.der is ready to be imported in the keystore from which the certificate signing request was generated.


    Before importing clientapp.der, you must first import the certificate of its signer: demoCA/cacert.pem.

Security in a Federated Search Environment

To perform secure search in a federated search environment, various aspects of security must be considered. See "Setting Up Federated Sources".