4 Security in Oracle Secure Enterprise Search

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. (Oracle SES no longer requires access control lists in Oracle Internet Directory for secure search.) 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.

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

Oracle SES security is implemented at the following levels:

• User authentication

  This is the identification of a user through an identity management system. 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. This is done on the Global Settings - Identity Management Setup page.

  See Also:

  "Activating an Identity Plug-in"

• User authorization

  This determines whether a user can access information about a particular item in the results list. It is implemented in 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.

  Note:

  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 compares the document-level user authorization methods in Oracle SES.

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

  Method	How Authorization is Determined	Advantages	Disadvantages
  ACLs	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	QueryTimeFilter 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 QueryTimeFilter.

  
  

  See Also:

  • "Admin-based Authorization" for more information about using ACLs

  • "Query-time Authorization" for more information on using a Java filter class

  • "Crawler Plug-in API"

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.

Secure Search Options

Oracle Secure Enterprise Search offers several options for secure search:

• Admin-based Authorization

• Custom Crawler Plug-in

• Query-time Authorization

• Self Service Authorization

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.

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.

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.

SSL 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, in some acting as the SSL client, and others acting as the SSL server.

Examples when Oracle SES acts as the SSL client:

• 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)

An example of when Oracle SES acts as the SSL server:

• The Oracle SES middle tier, configured to use SSL, responds to HTTPS or AJP13 requests.

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.

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.

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"... >
      ...
   </web-site>
   
   

   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" 
                  keystore-password="changeit" 
                  needs-client-auth="false" />
   </web-site>
   
   

   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.

   Note:

   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 machine. For example, myoses.us.oracle.com.

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

Previous sections 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 machine 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, CN=myhost.oracle.com,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, clientapp.crs).

      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