Cookie-Based Authentication Scenarios

This section provides detailed explanations of how selecting different options in the Admin Console affects the process of cookie-based authentication.

Back to top

Overview of Scenarios

Different organizations set up cookie-based authentication rules for the Google Search Appliance’s Universal Login in a variety of different ways. The selections that you, as a search appliance administrator, make by using the Admin Console depend on your system’s capabilities and your organization’s requirements.

For example, an organization might have a relatively simple system where, when a user does not have the correct credentials for a content server, the content server redirects the search appliance to a login system for log in, then the login system’s server redirects the search appliance back to the content server after login. This instance is described in Scenario 1: Normal Forms Authentication.

In a different organization, the system might be more complex. For example, the system might require redirecting to one URL to get cookies and then to another URL to get a verified identity. This instance is described in Scenario 3: Cannot Use Universal Login Form and Need Identity Verified Silently.

Although this document does not cover every possible variation of setting up cookie-based authentication rules, it provides the following scenarios, which represent just a few possible configurations that might apply to your system’s capabilities and your organization’s requirements:

Each scenario contains detailed information about the interactions between the user, the search appliance, the content server (sample URL, see Sample URL) and login server (redirect URL, see Sample URL Redirect to Login Form) that take place in the different configurations. Read the scenarios so that you can decide which configuration best matches your system’s capabilities and your organization’s requirements.

Back to top

Cookie-Based Authentication Options

To set up cookie-based authentication, you, as a search appliance administrator, use the following options on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page in Admin Console:

The effects of choosing these options depend on how your system is configured, and whether your system is set up for silent authentication (see Silent Authentication) and cookie cracking (see Cookie Cracking).

Each of the scenarios in this document explains the best combination of options to choose for the situation that the scenario illustrates. The following table shows which selections and system configurations are involved in each scenario.

 

Sample URL	Sample URL Redirect to Login Form	Redirect URL	Silent Authentication	Cookie Cracking	Used In
					Scenario 1: Normal Forms Authentication
					Scenario 2: Cannot Use Universal Login Form
					Scenario 3: Cannot Use Universal Login Form and Need Identity Verified Silently
					Scenario 4: Cannot Provide a Sample URL
					Scenario 5: Necessary Cookie is Available for Getting a Verified Identity
					Scenario 6: Use an HTTP Basic Challenge to Get Cookies
					Scenario 7: Use an NTLM HTTP Login Page to Get Cookies

The following sections provide overviews of each of the options listed in the table.

Sample URL

A sample URL is any page that should not be displayed unless the user who requests the content is logged in and authorized to view it. A sample URL enables the search appliance to detect if a user is logged in, and, if so, avoid the authentication page.

An example of a sample URL is http://it.abcreports.com/status.html. To detect if a user is logged in, the search appliance sends an HTTP GET message to the sample URL.

If a user is logged in, the sample URL’s content server, it.abcreports.com, returns a 200 response to the search appliance. The 200 response indicates that the request has succeeded. If the user is not logged in, the content server returns a redirect response to the search appliance (see Sample URL Redirect to Login Form).

Google recommends that you provide a sample URL whenever possible because it enables a quick and efficient authentication check.

To specify a sample URL, enter it in the Sample URL box on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page.

Sample URL Redirect to Login Form

If sample URL (see Sample URL) authentication fails, the content server can return a redirect response to the search appliance. The redirect response leads the search appliance to a single sign-on (SSO) system login form.

For example, the sample URL, http://it.abcreports.com/status.html, can redirect the search appliance to an SSO login form at http://abcreports.com/login/login.html. The search appliance can automatically log in to the form by using credentials of the credential group associated with the forms authentication mechanism.

However, for automatic login to occur, the login form must not contain any JavaScript that is critical to its submission. Otherwise, the search appliance cannot automatically log in to it.

To enable the sample URL to send a redirect response that leads to a login form, check When sample URL fails, expect the sample page to redirect to a form, and log in to that form on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page.

Redirect URL

You, as a search appliance administrator, can specify a redirect URL for the search appliance to use instead of the one supplied by the sample URL. In this case, the search appliance is redirected to URL that you specify, which can authenticate the user.

For example, suppose you specify http://insideabcreports.com/login/login.html as the redirect URL. When authentication at the sample URL fails, the search appliance redirects the user to the SSO login form at http://insideabcreports.com/login/login.html, where it can automatically log in.

If you supply a redirect URL, the authentication mechanism changes significantly. In non-redirect mode, the search appliance transfers a username / password from the Universal Login Form to a login form found when attempting to retrieve the sample URL. With a redirect URL, the search appliance will automatically redirect to that URL. The service at that URL can then authenticate the user in whatever way it wishes. Upon completion of that authentication, the service at the redirect URL should grant a cookie to the user which provides access to secure content (and to the sample URL, if provided), and redirect the user back to the search appliance.

If a sample URL is provided, it allows the search appliance to skip the redirect if the user already has cookies that provide access to the sample URL. A sample URL also allows verification of the user cookies upon return from the sample URL service.

Possible advantages of redirect URL authentication:

Disadvantages of redirect URL authentication:

On balance, Google does not recommend using a redirect URL as a preferred method of authentication.

To specify a redirect URL, enter it in the Redirect URL box on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page.

Return URL Parameter

A redirect response from the search appliance to a redirect URL includes a return URL parameter. A return URL parameter gives the server for the redirect URL information about the quickest path back to the search appliance. The server for the redirect URL follows this path when it sends a redirect response that leads back to the search appliance after it has authenticated the user.

To use a return URL parameter, the administrator of the server for the redirect URL must modify the server so that it respects a return URL parameter.

Silent Authentication

With silent authentication, users are authenticated without being directed to a login page. Inbound cookie forwarding from the content server to the search appliance can provide silent authentication without a verified identity, if the sample URL check passes.

If you require a verified identity, then silent authentication can only be achieved with cookie cracking (see Cookie Cracking).

Cookie Cracking

Your system might require a verified username and/or group, for example to use with authorization by means of policy ACLs, SAML, or connectors. One way of getting a verified username and/or group in addition to silent authentication is to configure the sample URL’s content server for cookie cracking (see Sample URL).

With cookie cracking, if a sample URL check for user credentials is successful, the sample URL’s content server generates the following response HTTP headers in addition to the standard headers:

X-Username:value

X-Groups:value1, value2

where value becomes a verified identity for the credential group that is associated with the sample URL.

The effect of the response header is that it has “cracked” open the cookie and revealed the username and/or group(s). To use cookie cracking, the administrator of the content server must modify the server so that it returns the appropriate response header.

If more than 2000 groups are used, there can be can increase in search latency and a decrease in queries per second (QPS). To avoid this issue, limit the number of groups to 2000.

There is a 3 second timeout limit for checking the sample URL. If the response time of the host is beyond this limit, the check for user credentials is not successful.

Using Quoted-Printable Encoding in Response Headers

If special characters are used in an X-Groups or X-Username HTTP response header, the header must be encoded in UTF-8 as quoted-printable. When the search appliance receives the response header, it attempts to decode the UTF-8 quoted-printable encoding.

For example, the search appliance crawls the following content, which contains special characters:

<html>

  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

    <meta name="google:aclusers" content="spécial"/>

    <meta name="google:aclusers" content="??"/>

    <meta name="google:aclgroups" content="spécial-group"/>

  </head> 

  <body>

    Some content

  </body>

</html>

Because the user "spécial" and group "spécial-group" include special characters, the following encoded headers should be used:

X-Username: sp=C3=A9cial (for spécial)

X-Groups: sp=C3=A9cial-group (for spécial-group)

In contrast, for the user "??" and the group "spécial-group", the following encoded headers should be used:

X-Username: =E6=97=A5=E6=9C=AC (for ??)

X-Groups: sp=C3=A9cial-group (for spécial-group)

If there are special characters in an X-Groups or X-Username HTTP response header that are not encoded, the search appliance is not able to parse the ACL properly. To avoid this problem, Google recommends that you always encode the headers.

Back to top

Scenario 1: Normal Forms Authentication

In Scenario 1, if the sample URL check fails because the user is not yet logged in, the content server redirects the search appliance to a login system for log in, then the login system’s server redirects the search appliance back to the content server after login.

Set Up for Scenario 1

For scenario 1, set up a cookie authentication rule by performing the following tasks:

The redirect to the login form is provided by the sample URL page response, so do not specify it in the Redirect URL box.

Process Overview of Scenario 1

The following diagram provides an overview of the cookie authentication process in scenario 1. For explanations of the numbers in the process, see the steps following the diagram.

Back to top

Scenario 2: Cannot Use Universal Login Form

In scenario 2, the system cannot use the Universal Login Form. For example, if a corporate SSO login system uses JavaScript, the Universal Login Form cannot log in to it. However, the user can be redirected to a form where she can log in and get cookies.

Set Up for Scenario 2

In scenario 2, if the search appliance does not receive a 200 response from the sample URL, the search appliance redirects to the SSO Login Form so that the user can log in and get cookies.

For scenario 2, set up a cookie authentication rule by performing the following tasks:

Because the sample URL does not redirect to a login form that is compatible with the search appliance, you do not need to check When sample URL fails, expect the sample page to redirect to a form, and log in to that form.

Process Overview of Scenario 2

The following diagram provides an overview of the cookie authentication process in scenario 2. For explanations of the numbers in the process, see the steps following the diagram.

Back to top

Scenario 3: Cannot Use Universal Login Form and Need Identity Verified Silently

Scenario 3 is a variation of scenario 2 (see Scenario 2: Cannot Use Universal Login Form). As in scenario 2, the system cannot use the Universal Login Form. But in this scenario, you need a verified identity to use with policy ACLs. The sample URL’s server provides the verified identity.

Set Up for Scenario 3

In scenario 3, sample URL’s server is configured for cookie cracking (see Cookie Cracking), meaning that it can provide silent authentication and a verified username and/or groups for the credential group that is associated with the sample URL.

If the search appliance does not receive a 200 response from the sample URL, the search appliance redirects to the SSO Login Form so that the user can log in and get cookies.

For scenario 3, set up a cookie authentication rule by performing the following tasks:

Because the sample URL does not redirect to a login form that is compatible with the search appliance, you do not need to check When sample URL fails, expect the sample page to redirect to a form, and log in to that form.

Process Overview of Scenario 3

The following diagram provides an overview of the cookie authentication process in scenario 3. For explanations of the numbers in the process, see the steps following the diagram.

Back to top

Scenario 4: Cannot Provide a Sample URL

In scenario 4, the system cannot provide a sample URL to enable the search appliance to detect if a user is logged in. However, the user can be redirected to a form where she can log in and get cookies.

Set Up for Scenario 4

For scenario 4, set up a cookie authentication rule by specifying a Redirect URL.

Because your system cannot provide a sample URL, leave the Sample URL box blank and do not check When sample URL fails, expect the sample page to redirect to a form, and log in to that form.

Process Overview of Scenario 4

The following diagram provides an overview of the cookie authentication process in scenario 4. For explanations of the numbers in the process, see the steps following the diagram.

Back to top

Scenario 5: Necessary Cookie is Available for Getting a Verified Identity

In scenario 5, it is a requirement to get a verified identity for use with policy ACLs, SAML Authorization, or connectors. The system is set up so that the search appliance never forces the user to log in, but the necessary cookie is available to the search appliance. In this scenario, a portal always forces the user to log in and the search appliance gets the cookie from the portal.

Because the user is already logged in before sending a request to the search appliance, the only way to get a verified identity is by using cookie cracking (see Cookie Cracking).

Set Up for Scenario 5

In scenario 5, the sample URL’s server is configured as a cookie cracker, meaning that it can provide silent authentication and a verified identity for the credential group that is associated with the sample URL. A 200 response from the sample URL includes the X-Username and/or X-Groups HTTP response headers.

For scenario 5, set up a cookie authentication rule by specifying a Sample URL.

Because a cookie is provided to the browser when the user logs into the portal, you do not need to check When sample URL fails, expect the sample page to redirect to a form, and log in to that form or specify a Redirect URL.

Process Overview of Scenario 5

The following diagram provides an overview of the cookie authentication process in scenario 5. For explanations of the numbers in the process, see the steps following the diagram.

Back to top

Scenario 6: Use an HTTP Basic Challenge to Get Cookies

In Scenario 6, your system is set up to use HTTP Basic authentication. The Google Search Appliance supports both crawl-time and serve-time authentication for content protected by an HTTP Basic challenge.

To set up a search appliance for this scenario, configure crawl of the protected content and then set up a cookie authentication rule by specifying a sample URL. If the sample URL check fails because the user is not yet logged in, the content server redirects the search appliance to an HTTP Basic Login page, then the login page redirects the search appliance back to the content server after login.

Set Up for Scenario 6

For scenario 6, first configure crawl of the content protected by HTTP Basic:

Next, set up a cookie authentication rule on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page:

The redirect to the HTTP Basic login page is provided by the sample URL page response, so do not specify it in the Redirect URL box.

Process Overview of Scenario 6

The process overview of scenario 6 is the same as the process overview of scenario 1 (see Process Overview of Scenario 1).

Back to top

Scenario 7: Use an NTLM HTTP Login Page to Get Cookies

In scenario 7, your system is set up to use an NTLM login page for authentication. The Google Search Appliance supports both crawl-time and serve-time authentication for content protected by an NTLM login page.

To set up a search appliance for this scenario, configure crawl of the protected content and set up a cookie authentication rule by specifying a sample URL and a redirect URL. If the search appliance does not receive a 200 response from the sample URL, the search appliance redirects to the NTLM login page so that the user can log in and get cookies.

Set Up for Scenario 7

For scenario 7, first configure crawl of the content protected by NTLM HTTP and cookies:

Next, set up a cookie authentication rule on the Search > Secure Search > Universal Login Auth Mechanisms > Cookie page:

Process Overview of Scenario 7

The following diagram provides an overview of the cookie authentication process in scenario 7. For explanations of the numbers in the process, see the steps following the diagram.