Serving > Forms Authentication

The search appliance is designed to work with single sign-on (SSO) servers, such as eTrust™ SiteMinder from Computer Associates, Cams™ from Cafesoft, and Oracle Identity Management. If you are using single-sign on functionality, the search appliance can serve pages that are protected by forms-based authentication through the use of certificate authorities (CA). For more information, see Importing CA certificates.

Note: To have your protected pages crawled and indexed by the search appliance, go to Crawl and Index > Forms Authentication.

When serving SSO documents, if the end user does not have a cookie or if it has expired, the search appliance first challenges for credentials and then tries to obtain a cookie by submitting credentials to an SSO server.

The system provides two options for authentication. One is to authenticate against an external login server using cookie forwarding. The other is to authenticate against a protected URL, using either cookie forwarding or user impersonation.

If your system uses cookie forwarding, the hostname of the search appliance must be on the same domain as the cookie (domain-match) for the search appliance to get a cookie and send it to the user's browser. For cookie forwarding, multiple cookies can be used, but the only cookie that can perform a cookie expiration check is the one you define in the Admin Console.

For example, if the hostname of the search appliance is search.corp.yourcompany.com, these cookie domains would support cookie forwarding in your system:

corp.yourcompany.com
yourcompany.com

These cookies domains would not support cookie forwarding:

sso_docs.yourcompany.com
gsa.search.yourcompany.com

That is, if the SSO cookie domain is so specific that it doesn't cover the appliance's hostname, then cookie forwarding will not work on your system. You can, however, use User Impersonation.

You can use User Impersonation if your system restricts the cookie domain to something other than the search domain used by the appliance. In this case, we suggest using a fully qualified host name for the cookie domain. Also, in Serving > Forms Authentication, select the Only User Impersonation check box.

For example, these domains will allow the search appliance to impersonate the user and get a cookie on the user's behalf from your SSO server:

sso_docs.yourcompany.com
gsa.search.yourcompany.com

If you select Only User Impersonation, set the cookie duration to the proper length of time, depending on your company's policy. By default, the duration is set to zero, which means the cookie never expires.

To use forms-based authentication with the appliance:

1. Under Serving > Forms Authentication, select one of the following options:
   • Log in against a sample protected URL
   • Always redirect to an external login server. If you select this option, skip to step 3.
2. To specify user impersonation for the first option, do the following:
   • Click Only User Impersonation, and then enter the User Impersonated Cookie Name associated with full user impersonation.
   • Specify the User Impersonated Cookie duration, specifying the number of hours, minutes, or seconds before the cookie should expire.
3. Enter the URL that is protected by your security policy, or the URL to the external login server.
4. Enter the name of the forms authentication cookie.
5. Click Save Forms Authentication Serving Configuration.

Serving Logs

When problems related to serving occur, you can generate a log of forms-authentication related traffic to use in troubleshooting. The log generates two types of messages.

Message Type	Description
User login to front ends	This log contains messages that are generated when a user signs in and receives a cookie.
Verification of user access to secure documents	This log contains messages that are generated when a user searches public and secure content. The headrequestor component of the appliance verifies that the user's cookie provides access to the documents that contain search results.

This log is useful if users are unable to get results from documents that are protected by forms authentication. Look for the following types of errors:

• In the login log, look for 401 errors.
• In the verification log, look for 404 errors.
  

When you enable logging, the log is written to the Admin Console, until there is 1 megabyte of data. When the log contains one megabyte of data, it is cleared and restarted. To retain log data, select and copy the data from the log, then paste it into a text editor.

While the appliance is logging, performance is slowed and a warning message appears on each page. Don't forget to turn off logging when you no longer need it.

Importing CA certificates

The search appliances use certificate authorities (CA) to authenticate user credentials before allowing protected search results to be viewed. If your search appliance is configured to crawl and serve forms authenticated content, you must import CA certificates for all servers accessed through HTTPS.

To import CA certificates for servers accessed through HTTPS, complete the following steps:

1. In a web browser, display the Admin Console by using the following format:
   http://your-search-appliance-hostname:8000
2. Log in to the Admin Console as admin.
3. Identify servers that are hosting forms authenticated content. The server names, or IP addresses, appear in URLs beginning with https:// on the following pages:
• Under Crawl and Index > Cookie Sites, check the following text boxes:
  • URL of the login page:
  • Cookie rule matching this pattern:
  • Action: Visit this URL:
• Under Crawl and Index > Forms Authentication, check the following text boxes:
  • Sample Forms Authentication protected URL:
  • URL pattern for this rule:
    
• Under Serving > Forms Authentication, check the following text box: URL:
4. For each server accessed through HTTPS, request a CA certificate file from the CA administrator or vendor.
5. Under Administration > Certificate Authorities, upload the CA certificates. For more information, see the Administration > Certificate Authorities Help page.
6. (Optional): Upload a valid Certificate Revocation List (CRL) for each CA certificate.
   You can add a Certificate Authority without adding a CRL. However, if Enable Server Certificate Authentication or Enable OneBox Provider Certificate Authentication is checked under Administration > SSL Settings, then the following occurs:
   • Servers whose certificates are signed by that CA are not crawled.
   • OneBox providers whose certificates are signed by that CA are unable to respond to requests.

---