Search
Clear search
Close search
Google apps
Main menu
true

Managing Search for Controlled-Access Content

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.

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 See 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

See Redirect URL

Silent Authentication

Cookie Cracking

Used In


 

 
     

See Scenario 1: Normal Forms Authentication


 
 
 
   

See Scenario 2: Cannot Use Universal Login Form


 
 
 

 

 

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

   
 
   

See Scenario 4: Cannot Provide a Sample URL


 

 
 
 

 

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


 

 
     

See Scenario 6: Use an HTTP Basic Challenge to Get Cookies


 
 
 

 
 

See 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.

Back to top

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:

  • The user’s password is never sent to the search appliance.
  • The redirect URL server can interact directly with the user. This can facilitate login scenarios where the user’s browser must perform operations (such as evaluating complex JavaScript) that the search appliance form-filling emulator cannot perform.

Disadvantages of redirect URL authentication:

  • It is generally slower than standard cookie-based forms authentication.
  • It requires setting up the server for the redirect URL to respect the return URL parameter, which gives the server for the redirect URL information about the quickest path back to the search appliance.
  • It does not result in a verified user-name unless the sample URL is also a cookie cracker.

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 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:

  • Specify a Sample URL
  • Check When sample URL fails, expect the sample page to redirect to a form, and log in to that form

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.

  1. The user requests a secure search.
  2. The browser sends a GET message to the search appliance.
  3. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  4. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance checks the content server by using the sample URL to detect whether other cookies that the browser has sent are valid.

  5. If the user is logged in, the content server sends a 200 response to the search appliance and authentication is complete.

    If the user is not logged in, the content server sends a 302 redirect response to the search appliance.

  6. The search appliance sends a GET message to the SSO Login Form located at the URL where it was redirected.
  7. The SSO Login Form sends an empty SSO Login Form to the search appliance.
  8. If the search appliance has the user credentials, it completes the SSO Login Form and sends it to the SSO system. If the search appliance does not have user credentials, it sends an empty Universal Login Form to the browser.
  9. The user provides a username and password for each credential group in the Universal Login Form and submits it.
  10. The browser sends the completed Universal Login Form to the search appliance.
  11. The search appliance adds the username and password to the SSO Login Form and sends it to the SSO system.
  12. The SSO system logs in the user, sets a cookie, and sends it with a redirect response that points the search appliance to the content server.
  13. The authentication phase begins again at step 4. The search appliance checks the content server by using the sample URL to detect whether the cookie is correct.

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:

  • Specify a Sample URL
  • Specify the SSO Login Form as the Redirect URL

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.

  1. The user requests a secure search.
  2. The browser sends a GET message to the search appliance.
  3. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  4. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance checks the content server by using the sample URL to detect if other cookies that the browser has sent are valid.

  5. If the sample URL check for the user credentials is successful, the content server sends a 200 response to the search appliance and authentication is complete.

    If the sample URL check is not successful, the content server sends any response except a 200 to the search appliance.

  6. The search appliance sends a redirect response pointing to the redirect URL that includes a return URL parameter to the browser (see Return URL Parameter).

    This action forces the user to visit the Redirect URL.

  7. The browser sends a GET message with a return URL parameter to the Redirect URL.
  8. The user interacts with the Redirect URL and gets a cookie.
  9. The Redirect URL sends a redirect response with a cookie to the address specified in the return URL parameter, which leads to the search appliance.
  10. The authentication phase begins again at step 4. The search appliance checks the content server by using the sample URL to detect whether the cookie is correct.

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.

Back to top

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:

  • Specify a Sample URL
  • Specify the SSO Login Form as the Redirect URL

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.

  1. The user requests a secure search.
  2. The browser sends a GET message to the search appliance.
  3. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  4. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance checks the content server by using the sample URL to detect if other cookies that the browser has sent are valid.

  5. If the sample URL check is successful, the content server generates a 200 response that includes a response HTTP header with X-Username: value and/or X-Groups: value and sends it to the search appliance.

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

    If the sample URL check is not successful, the content server sends any response except a 200 to the search appliance.

  6. The search appliance sends a redirect response that includes a return URL parameter to the browser (see Return URL Parameter).

    This action forces the user to visit the Redirect URL.

  7. The browser sends a GET message with the return URL parameter to the Redirect URL.
  8. The user interacts with the Redirect URL and gets a cookie.
  9. The Redirect URL sends a redirect response with a cookie to the search appliance.
  10. The authentication phase begins again at step 4. The search appliance checks the content server by using the sample URL to detect whether the cookie is correct.

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.

Back to top

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.

  1. The user requests a secure search
  2. The browser sends a GET message to the search appliance.
  3. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  4. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance sends a redirect response that includes a return URL parameter to the browser (see Return URL Parameter).

    This action forces the user to visit the Redirect URL.

  5. The browser sends a GET message with the return URL parameter to the Redirect URL.
  6. The user interacts with the Redirect URL and gets a cookie.
  7. The Redirect URL sends a redirect response with a cookie the browser.
  8. The browser redirects to the search appliance.
  9. The search appliance assumes that authentication was successful and uses any cookies sent by the redirect URL in head requests.

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.

  1. The user logs in to a system in the enterprise that is connected to the SSO system, such as a portal.
  2. The system authenticates the user and send a cookie to the browser.
  3. When the user requests a secure search, the browser sends a GET message with the cookie to the search appliance.
  4. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  5. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance checks the content server by using the sample URL to detect if the cookie from the portal is correct.

  6. If the sample URL check is successful, the content server generates a 200 response that includes a response HTTP header with X-Username: value and/or X-Groups: value and sends it to the search appliance.
  7. value becomes a verified identity for the credential group that is associated with the sample URL and authentication is complete.

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:

  1. Open the Content Sources > Web Crawl > Start and Block URLs page and add a URL pattern for the content protected by HTTP Basic and cookies under Start URLs and Follow Patterns.
  2. Click Save.
  3. Open the Content Sources > Web Crawl > Secure Crawl > Forms Authentication page and enter a sample URL for the content protected by HTTP Basic and cookies in the Sample Forms Authentication protected URL box.
  4. Enter a URL pattern in the URL pattern for this rule box.
  5. Click Create. The Admin Console displays an error page, but ignore this error page.
  6. Click Save and Close.
  7. On the Content Sources > Web Crawl > Secure Crawl > Crawler Access page, enter the URL pattern for the content protected by HTTP Basic and cookies under For URLs Matching Pattern, Use.
  8. Complete the row by entering a username, and password.
  9. Click Save.

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

  1. Specify a Sample URL.
  2. Check When sample URL fails, expect the sample page to redirect to a form, and log in to that form.

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:

  1. Open the Content Sources > Web Crawl > Start and Block URLs page and add a URL pattern for the content protected by NTLM HTTP and cookies under Start URLs and Follow Patterns.
  2. Click Save.
  3. Open the Content Sources > Web Crawl > Secure Crawl > Forms Authentication page and enter a sample URL for the content protected by NTLM HTTP and cookies in the Sample Forms Authentication protected URL box.
  4. Enter a URL pattern in the URL pattern for this rule box.
  5. Click Create. The Admin Console displays an error page, but ignore this error page.
  6. Click Save and Close.
  7. On the Content Sources > Web Crawl > Secure Crawl > Crawler Access page, enter the URL pattern for the content protected by NTLM HTTP and cookies under For URLs Matching Pattern, Use.
  8. Complete the row by entering a username, domain name, and password.
  9. Click Save.

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

  1. Specify a Sample URL.
  2. Specify the NTLM login page as the Redirect URL 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 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.

  1. The user requests a secure search.
  2. The browser sends a GET message to the search appliance.
  3. The search appliance checks its own session cookie to find out if authentication was previously completed.

    The search appliance sets a session cookie the first time a browser requests a secure search.

  4. If the search appliance’s session cookie is still valid, the authentication phase is complete.

    If the search appliance’s session cookie is not valid, the search appliance checks the content server by using the sample URL to detect if other cookies that the browser has sent are valid.

  5. If the sample URL check for the user credentials is successful, the content server sends a 200 response to the search appliance and authentication is complete.

    If the sample URL check is not successful, the content server sends any response except a 200 to the search appliance.

  6. The search appliance sends a redirect response pointing to the redirect URL that includes a return url parameter to the browser (see Return URL Parameter).

    This action forces the user to visit the NTLM login page (redirect URL).

  7. The browser sends a GET message with the return URL parameter to the NTLM login page.
  8. The user interacts with the NTLM login page and gets a cookie.
  9. The NTLM login page sends a redirect response with a cookie to the address specified in the return URL parameter, which leads to the search appliance.
  10. The authentication phase begins again at step 4. The search appliance checks the content server by using the sample URL to detect whether the cookie is correct.

Back to top

Was this article helpful?
How can we improve it?