Google Search Appliance

How to setup Forms Authentication with sso.py

Contents

  1. Introduction
  2. Installing sso.py
  3. Getting familiar with sso.py
  4. Setting up crawling on your GSA
  5. Setting up authentication on your GSA for each scenario
    1. Scenario 1: Normal Forms Authentication
    2. Scenario 2: Cannot Use Universal Login Form
    3. Scenario 3: Cannot Use Universal Login Form and Need Identity Verified Silently
  6. Well known pitfalls

Introduction

This document describes how to set up a cookie based authentication with the Google Search Appliance using an SSO server sso.py , which is a part of the GSA Admin Toolkit available at code.google.com. You can use this system to verify how cookie based authentication is supposed to work on the GSA. The SSO server provided is for use only in testing and not suitable for production or use as a reference implementation. The SSO server, sso.py, is a Python script that operates as both an SSO and web server. GSA interacts with sso.py via an internal security broker called the Security Manager. You can configure the Security Manager by using the “Serving >Universal Auth Mechanism” page in the Admin Console.

The working scenarios from “Managing Search for Controlled-Access Content: Cookie-Based Authentication Scenarios” covered in this document are as follows.

Installing sso.py

Getting familiar with sso.py

The following command starts sso.py serving on the TCP 7070 port.

% python sso.py --port 7070
  :
[28/Jun/2011:09:13:02] ENGINE Serving on sso.example.com:7070
[28/Jun/2011:09:13:02] ENGINE Bus STARTED

Try accessing http://sso.example.com:7070/ to see contents served by sso.py. The top page should look like the following example:

public
secure
authorized
logout
Additional secure links
................................................

Sso.py plays two roles; 1) a web server that serves both public contents and SSO protected secure contents. Try “public”, “secure”, “authorized” and “dots” links in the top page. It also works as 2) an authentication server which issues an SSO cookie for the session after authenticating a user. You see a login form when you click any secure contents. Sso.py actually accepts any user credentials except for the “authorized” link. The “authorized” link requires the user to be authenciated as "crawler". Try the “secure” link and provide anything you like as the user name and password. After clicking “Submit” in the login form, you see:

You must be authenticated to view this page.You are authenticated as "fuga". The value of param is 'None'.

You will see your user name in the place of "fuga". If you click one of the “dots” links, param will show the number.

Setting up crawling on your GSA

Once sso.py is up and running, you can setup your GSA to crawl the secure contents served by sso.py using the Admin Console (AC) which is accessible at http://your_gsa:8000/ .

  1. Login to the Admin Console and navigate to the page “Crawl and Index >Forms Authentication”
    1. Enter “http://sso.example.com:7070/secure/” in “Sample Forms Authentication protected URL:”
    2. Enter “http://sso.example.com:7070/” in “URL pattern for this rule:”
    3. Click “Create a New Forms Authentication Rule”
    4. “Forms Authentication Login Wizard” page will be shown in a new browser window / tab. The Login form of sso.py is shown in the Wizard page.
    5. Provide “crawler” as the user name and password, then click “Submit”. The contents of the “secure” link from sso.py will be shown.
    6. Click “Save Forms Authentication Rule and Close Window”
    7. The Wizard page will disappear. The new rule is added o the Forms Authentication setup page.
  2. At “Crawl and Index >Crawl URLs”, add “http://sso.example.com:7070/” in both “Start Crawling from the Following URLs:” and “Follow and Crawl Only URLs with the Following Patterns:”, then click “Save URLs to Crawl”.
  3. Give your GSA some time until those URLs are indexed. Visit “Status and Reports >Crawl Diagnostics” to see if they are indexed.
  4. Try fetching a secure URL from sso.py at “Status and Reports >Real-time Diagnostics” on AC.
    1. For instance, try “http://sso.example.com:7070/secure?param=48” and click “Fetch”
    2. “Fetch completed. State of the url is downloaded.” will be displayed at the end of the “Headers” textbox if you setup crawling successfully.

Setting up authentication on your GSA for each scenario

Now that sso.py is working and your GSA has successfully indexed the contents, you can configure your GSA’s authentication mechanism using the Admin Console in “Universal Login Auth Mechanisms >Cookie Based”:

Scenario 1: Normal Forms Authentication

In Scenario 1, if the user is not logged in, GSA (the Security Manager) will present the Universal Login Form to the user to collect the user credentials. The actual login happens between GSA (the Security Manager) and sso.py using the collected credentials.

For more detailed explanation of this scenario, please refer to Scenario 1 in our official documentation.

  1. On your PC, start sso.py by:
    % python sso.py --port 7070
    
  2. Login to the the Admin Console, navigate to the page "Serving >Universal Login Auth Mechanism" and choose "Cookie Based" tab.
  3. Check “When sample URL check fails, expect the sample page to redirect to a form, and log in to that form.”
  4. Enter your preferred name in “Mechanism Name:”. For instance “ssopytest”.
  5. Enter “http://sso.example.com:7070/secure/” in “Sample URL:”
  6. Leave “Redirect URL” (blank by default), “Return URL Parameter” (returnPath), “Trust Duration” (300) untouched.
  7. Click “Save”
  8. Go to the search interface (http://gsa.example.com/), select the “public and secure content” button and search for “secure”. Also try a public search for the same keyword.
  9. Also, look into AuthZ log and confirm that this authentication mechanism establishes a verified User ID as shown as “verifiedUserId: username” in the log.


Scenario 2: Cannot Use Universal Login Form

In Scenario 2, the user will be redirected from GSA to sso.py to complete login. When the user provides the correct credentials and authenticates successfully, sso.py redirects the user browser back to GSA using the URL provided by "returnPath" parameter.

One important thing about this scenario is that the Security Manager is not able to establish a verified user ID. Thus, you need to create a Credential Group which "Does not require a username".

For more detailed explanation of this scenario, please refer to Scenario 2 in our official documentation.

  1. Make sure that you set --cookie_domain option properly. If the cookie domain name is longer than the host name on which sso.py is running, GSA may not receive the cookie. This is described in Well known pitfalls .

    On your PC, start sso.py by:

    % sso.py --port 7070 --cookie_domain=".example.com"
    
  2. Login to the the Admin Console and navigate to the page "Serving >Universal Login".
  3. Enter "noname" in both "Credential Group Name:" and "Credential Group Display Name:"
  4. Uncheck both "Require a user-name for this credential group?" and "Group is optional? (i.e. allow it to be left blank.)"
  5. Click "Create New Credential Group". New Credential Group will be created and shown as below.
    noname (Does not require a username) (Not optional; cannot be left blank)
    
  6. Visit "Serving >Universal Login Auth Mechanism", choose "Cookie Based" tab.
  7. From Credential Group pull down, choose "noname".
  8. Uncheck “When sample URL check fails, expect the sample page to redirect to a form, and log in to that form.”
  9. Enter your preferred name in “Mechanism Name:”. For instance “ssopytest”.
  10. Enter “http://sso.example.com:7070/secure/” in “Sample URL:”
  11. Enter “http://sso.example.com:7070/externalLogin” in “Redirect URL:”
  12. Leave “Return URL Parameter” (returnPath) untouched and “Trust Duration” (300) untouched.
  13. Click “Save”
  14. Go to the search interface (http://gsa.example.com/), select the “public and secure content” button and search for “secure”. Also try a public search for the same keyword.
  15. Also look into AuthZ log and confirm that this authentication mechanism doesn’t establish a verified User ID. This can be verified by “verifiedUserId: is null” in the log.


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

Scenario 3 is just same as Scenario 2. It uses sso.py's login form directly. However, sso.py provides a user name and group memberships by cookie cracking and GSA can establish a verified user ID. Thus, you use a Credential Group which "Requires a username". "Default" Credential Group is configured as such by default.

For more detailed explanation of this scenario, please refer to Scenario 3

  1. Make sure that you set --cookie_domain option properly. If the cookie domain name is longer than the host name on which sso.py is running, GSA may not receive the cookie. This is described in Well known pitfalls . Also, provide cookie cracking option as well.

    On your PC, start sso.py by:

    % sso.py --port 7070 --cookie_domain=".example.com" --cookie_cracking
    
  2. Login to the Admin Console, navigate to the "Serving >Universal Login Auth Mechanism" and choose "Cookie Based" tab.
  3. From Credential Group pull down, choose "Default".
  4. Uncheck “When sample URL check fails, expect the sample page to redirect to a form, and log in to that form.”
  5. Enter your preferred name in “Mechanism Name:”. For instance “ssopytest3”.
  6. Enter “http://sso.example.com:7070/secure/” in “Sample URL:”
  7. Enter “http://sso.example.com:7070/externalLogin” in “Redirect URL:”
  8. Leave “Return URL Parameter” (returnPath) untouched and “Trust Duration” (300) untouched.
  9. Click “Save”
  10. Go to the search interface (http://gsa.example.com/), select the “public and secure content” button and search for “secure”. Also try a public search for the same keyword.
  11. Look into AuthZ log and confirm that this authentication mechanism establish a verified User ID. This can be verified by “verifiedUserId: username” and "groups: [ssopygrou]" in the log. This is done by “X-Username:” and “X-Groups:” header in Cookie Cracking.


Well known pitfalls

  • If the domain name of the cookie is longer than the hostname of your SSO server, version 6.4 or older will ignore the cookie and Forms Authentication will fail. For instance, if your SSO server (sso.example.com) tries to set a cookie with a domain name “.sso.example.com” (be careful; there’s a “dot” in front of the domain name), GSA will ignore the cookie. In this case, any of Forms Authentication (Crawling and Index), Cookied Based authentication (Serving) and Headrequestor (for authorization) will not work with the SSO server. 6.8 and later has a checkbox to relax this strict cookie name checking. For more details, see;
    http://code.google.com/apis/searchappliance/documentation/610/help_gsa/crawl_headers.html#relax
  • Also, if you don't use FQDN (Fully Qualified Domain Name) to access your GSA or web sites, your browser may not send Cookies to the web sites or GSAs. For instance, if you access "http://sso/" instead of "http://sso.example.com", the browser may fail to send right cookies.
  • HTTP headers configured in “Crawl and Index > HTTP Headers” is not used for Forms Authentication transaction.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.