Google logo
Google Search Appliance Documentation
Managing Search for Controlled-Access Content
 PDF Previous Next
Front Matter
Overview
Crawl, Index, and Serve
Use Cases with Public and Secure Serve for Multiple Authentication Mechanisms
Cookie-Based Authentication Scenarios
Using Trusted Applications
Index

Using Trusted Applications

Overview of Trusted Applications
Trusted Applications with Registered Applications
Trusted Applications without Registered Applications
Supported Authentication Mechanisms
Early Binding
Process Diagram
Setup for Using Trusted Applications
Enabling and Registering Trusted Applications
Configuring Your Trusted Application
Search Query Formats
POST Support for Long Queries

This chapter describes the trusted applications feature, used for secure search. It provides details about the interaction between a trusted application and the search appliance and how to configure trusted applications.

Back to top

Overview of Trusted Applications

The search appliance enables trusted applications to send end-user's search requests, along with pre-validated ids when performing a secure search. The search appliance returns secure results without requiring more validation of the user.

An example of a trusted application is a web-based enterprise portal that provides secure access to search using the Google Search Appliance as its engine. With previous search appliance versions, an end user who is performing a secure search needs to supply credentials to both the portal and the search appliance. With trusted applications, the only time that end users need to supply credentials is when they log in to the portal.

Before using this feature, you enable the trusted applications feature and, optionally, register your application as a “trusted application” on the search appliance.

Trusted Applications with Registered Applications

After you register a trusted application, it can interact with the search appliance. Before sending a search request to the search appliance, the trusted application authenticates the user. After successfully verifying the user, it sends the search request, along with information about the end user's identity. Because the search appliance “trusts” the application, it returns secure results to the portal. It does not need to verify the end-user before doing so.

Trusted Applications without Registered Applications

If you enable trusted applications on the search appliance, but don’t register a trusted application, the end-user’s credentials are sent to the search appliance, which authenticates the user.

Supported Authentication Mechanisms

Take note that the search appliance only supports basic authentication and cookie authentication with trusted applications.

The search appliance does not support trusted applications with the following authentication mechanisms:

•
Client certificates
•
Integrated Windows Authentication/ Kerberos
•
SAML
•
Connectors
•
LDAP

Early Binding

The trusted applications feature only supports early binding (using per-URL ACLs and policy ACLs); it does not support late binding. In early binding the security permissions are stored on the search appliance. The trusted application only needs to send the end user's ID in addition to self credentials. The search appliance only needs to authenticate the application. The end user is verified automatically.

Process Diagram

The following diagram provides an overview of the secure search API process. For explanations of the numbers in the process, see the steps following the diagram.

Before the process begins, a secure web application has been designed and configured as a trusted application on the search appliance.

1.
The user signs in to the trusted application. The trusted application has the user’s verified identity.
2.
The user requests a secure search from the browser.
3.
The request is sent to the trusted application.
4.
If trusted applications is enabled and trusted applications are registered: In this mode, the trusted application forwards the secure search request to the search appliance using trusted user credentials together with the end user’s ID. The search appliance verifies the trusted application.

Internally, the security manager gets the credentials from the request and verifies them. After the normal authentication check, the security manager checks to see if the request is from a trusted application by checking against the trusted application user names and/or group. If so, it creates a verified end-user session for the end user.

There is no more credential gathering from the end user's agent. The search appliance uses the end user (X_GSA_USER and X_GSA_CREDENTIAL_GROUP headers) during the next phase (group resolution and authorization).

If trusted applications is enabled, but no trusted applications are registered: In this mode, the user’s credentials are sent to the security manager. It verifies the end user’s credentials, which are used for authorization.
5.
The search appliance returns secure search results to the trusted application.
6.
The trusted application returns the secure search results to the user agent.

Back to top

Setup for Using Trusted Applications

Set up your environment to use the trusted applications feature by performing the following tasks:

•
Configuring secure search on your search appliance:
•
Setting up Universal Login by using the Search > Secure Search > Universal Login page, as described in Universal Login.
•
Configuring a credential group for basic authentication or cookie authentication for trusted applications by using the Search > Secure Search > Universal Login Auth Mechanisms page, as described in HTTP-Based Authentication, and Cookie-Based Authentication.

Take note that the trusted applications feature does not support multiple credential groups.
•
Enable early binding authorization by Adding per-URL ACLs and/or policy ACLs to the search appliance, as described in Policy Access Control Lists.
•
Enabling and registering trusted applications and adding users and/or groups, as described in the following section.
•
Configuring your trusted application to send the required information to the search appliance, as described in Configuring Your Trusted Application.

After set up is complete, start using secure search with your trusted applications.

It’s important that the trusted application keep and re-use the GSA session ID. If this doesn’t happen, every secure search request will create a new session. Also, the trusted application should handle the case where the GSA session ID expires.

Enabling and Registering Trusted Applications

Trusted applications is disabled by default on the search appliance.

To enable trusted applications:

1.
In the Admin Console, click Search > Secure Search > Trusted Applications.
2.
Click Enable Trusted Applications.

By registering a trusted application, you enable the search appliance to receive pre-validated ids from it. After a trusted application is registered, it can use the feature to interact with the search appliance. You register a trusted application by identifying it as a user or by the group where it has membership and associating it with a credential group.

If you don’t register a trusted application, the end-user’s credentials are sent to the search appliance, which authenticates the user.

To register trusted applications:

1.
In the Admin Console, click Search > Secure Search > Trusted Applications.
2.
Next to Trusted Users and Groups, click Add. 
3.
Select User or Group from the pull-down menu.
4.
Select a credential group from the pull-down menu.
5.
Optionally, type a domain and name for the end user.

If the domain and name are case sensitive, click the Case Sensitive checkbox.
6.
Click Save.

For more information about how to register trusted applications, click Admin Console Help > Search > Secure Search > Trusted Applications.

Configuring Your Trusted Application

To use the trusted applications feature, a search request from a trusted application should include the following headers:

•
X_GSA_USER: Header
•
X_GSA_CREDENTIAL_GROUP: Header

If no trusted applications are registered, do not use X_GSA_USER and X_GSA_CREDENTIAL_GROUP headers. Otherwise, a 502 error is returned.

X_GSA_USER: Header

The X_GSA_USER: header is required. It identifies the end user that the trusted application is performing the search for. This field can also include a domain, as shown in the following examples:

X_GSA_USER:user1
X_GSA_USER:user1@my_company.com
X_GSA_CREDENTIAL_GROUP: Header

The X_GSA_CREDENTIAL_GROUP: header is required. It identifies the credential group that the end user is associated with, as shown in the following example:

X_GSA_CREDENTIAL_GROUP:TAUsersCredGroup

Search Query Formats

The following sample queries show the format of a search query sent from a trusted application to the search appliance.

Cookie Authentication

If cookie authentication is used, the search query can be in one of the following formats:

curl -b "<cookie_name>=<cookie_value>" --header "X_GSA_USER:<user_name>" 
--header "X_GSA_CREDENTIAL_GROUP:<credential_group_name>" 
"http://www.mycompany.com/search?q=YOUR_QUERY_HERE&access=a"

where <cookie_value>=application's cookie

curl -b "<GSA_SESSION_ID>=<session_id>;<cookie_name>=<cookie_value>" 
--header "X_GSA_USER:<user_name>" 
--header "X_GSA_CREDENTIAL_GROUP:<credential_group_name>" 
"http://www.mycompany.com/search?q=YOUR_QUERY_HERE&access=a"

where <session_id>=application's GSA_SESSION_ID returned as a set cookie form a previous request

Basic Authentication

If basic authentication is used, the search query can be in one of the following formats:

curl --user user_name:password --header "X_GSA_USER:<user_name>" 
--header "X_GSA_CREDENTIAL_GROUP:<credential_group_name>" 
"http://www.mycompany.com/search?q=YOUR_QUERY_HERE&access=a"
 
curl -b "<GSA_SESSION_ID>=<session_id>" --user user_name:password 
--header "X_GSA_USER:<user_name>" 
--header "X_GSA_CREDENTIAL_GROUP:<credential_group_name>" 
"http://www.mycompany.com/search?q=YOUR_QUERY_HERE&access=a"

where <session_id>=application's GSA_SESSION_ID returned as a set cookie form a previous request

Back to top

POST Support for Long Queries

Google recommends that you use the HTTP POST request with trusted applications, especially if your query strings exceed the 2KB URL length limit of GET requests. If you use a GET request, the query string is truncated if it exceeds the limit. Truncation might occur when you submit dynamic navigation queries containing a large number of metadata filters. You can avoid this limitation by submitting POST requests instead, which have a much larger body limit (10KB). However, using the GET request is also an option.

Take note that, for secure searches, POST requests can only be used with trusted applications. They cannot be used with secure search requests that do not use trusted applications. This type of search request only uses the GET command.

For more information on this topic, see Using the POST Command in the Search Protocol Reference.

Back to top

PDF Previous Next