Google Search Appliance software version 5.0
Posted October 2007
The SAML Authentication and Authorization Service Provider Interfaces (SPIs) enable a Google Search Appliance to communicate with an existing access control infrastructure via standard Security Assertion Markup Language (SAML) messages. The Authentication and Authorization SPIs are also required in order to support Windows Integrated Authentication with the Google SAML Bridge for Windows.
This document describes how to set up the Identity Provider and Policy Decision Point web services that are required by the Authentication and Authorization SPIs.
This document describes features that are available in version 4.6 and later of the Google Search Appliance. These features are not available in the Google Mini.
Skip over ContentsAuthentication (AuthN) is used to identify users, and authorization (AuthZ) is used to allow users access to documents according to their credentials.
The Authorization SPI requires web services from a Policy Decision Point and an authentication method. The Authorization SPI can be used with any one of the following authentication methods:
Note: Authentication through LDAP integration or x.509 certificates is configured on the Google Search Appliance. For more information on these authentication methods, refer to Managing Search for Controlled-Access Content.
To write an Identity Provider and Policy Decision Point web service, you should be familiar with these technologies.
The sample messages in this document conform to the XML schemas on the SAML web site.
Tip: One way to implement an Identity Provider and Policy Decision Point is to access a SOAP server using Apache Axis.
When implemented, the Authentication SPI allows search users to authenticate to the Google Search Appliance. It is designed to allow customers to integrate the appliance into an existing access control infrastructure. Instead of authenticating search users itself, the appliance redirects the user to an Identity Provider (IP), a customer-implemented server, where the actual authentication takes place. The IP then redirects the user back to the appliance, while passing information that includes the identity of the search user. The protocol that governs this communication between the appliance, the browser, and the customer's IP is based on SAML 2.0, an XML-based standard.
Figure 1: The Google Search Appliance communicates through an Identity Provider to authenticate users' access to intranet web pages.
Note: If you use the Authentication SPI, you must use the Authorization SPI as well. However, if you decide to authenticate your users with x509 certificates, or LDAP, you do not need to implement the Authentication SPI. You can go on to the Authorization section.
The Authentication SPI exposed by the Google Search Appliance is based on the SAML 2.0 standard; specifically, on the "Web Browser SSO Profile." The Web Browser SSO profile makes use of the "Authentication Request Protocol," a request-response protocol. The appliance sends a SAML <AuthnRequest> message to the customer's Identity Provider, and the Identity Provider responds with a SAML <Response> message that contains an <Assertion>, which in turn contains an <AuthnStatement>. These messages are transferred between the appliance and the customer's Identity Provider, via the browser, using the "HTTP Redirect" and the "HTTP Artifact" bindings.
The authentication sequence between the user/appliance/Identity Provider goes like this:
The Identity Provider runs a SOAP message service, which accepts queries from the appliance, and returns an <ArtifactResponsee> element as a child of the SOAP <Bodye> element. This connection is made over a mutually authenticated HTTPS connection, ensuring origin integrity, data integrity, and confidentiality. To dereference the artifact and actually obtain the SAML response message, the appliance uses the SAML SOAP binding to send an <ArtifactResolve> message to the Identity Provider. This message contains the artifact. The response message from the Identity Provider is an <ArtifactResponse> message, which contains a <Response> element, which contains an <AuthnStatement>, which contains the identity of the search user.
An artifact should not be reusable. Once an artifact is dereferenced, the Identity Provider should reject attempts to dereference the same artifact again.
After a search user logs in using the Authentication SPI, the appliance will maintain a session with the search user so that the user doesn't have to reauthenticate to the Identity Provider on every search.
This session is maintained with a session cookie. This cookie is securely sent over HTTPS and is set for the appliance's hostname only. The cookie value will contain the user identity and the time that the session cookie will expire.
When a search user performs a query (having no session cookie set), the appliance responds with a redirect that looks something like this:
HTTP/1.1 302 Object Moved Date: 23 Feb 2005 19:00:49 GMT Location: https://ac.corp.company.com/SAML_login?SAMLRequest=BASE64URLENCODEDELEMENT&RelayState=https://search.corp.company.com/search?q=query Content-Type: text/html; charset=iso-8859-1
The element BASE64URLENCODEDELEMENT is similar to:
<AuthnRequest ID="foobar" Version="2.0" IssueInstant="2005-10-08T11:32:19Z"/>
which is first DEFLATE-compressed, then Base 64 encoded, then URL encoded.
The ID attribute in the AuthnRequest element is a randomly generated string that is used to identity this particular <AuthnRequest> message. Currently, this ID attribute's only purpose is to ensure that the message is SAML compliant. Since it's not used by the appliance, there is no need to inflate the AuthnRequest element when processing the request. Note that the RelayState parameter name is case-sensitive. If a URL contains the parameter name with incorrect cases, the user recieves a 500 error with no indication of why.
When the Identity Provider redirects the browser to the appliance, here's what it might look like:
HTTP/1.1 302 Object Moved Date: 9 Feb 2005 18:22:03 PST Location: https://search.corp.company.com/SamlArtifactConsumer?SAMLart=RANDOMLOOKINGSTRING&RelayState=https://search.corp.company.com/search?q=query Content-Type: text/html; charset=iso-8859-1
The appliance gets the artifact as the SAMLart parameter's value, and sends it to the Identity Provider via SOAP over a mutually authenticated HTTPS connection:
POST /SAMLResponder/resolve HTTP/1.1
Host: ac.corp.company.com
Content-Type: text/xml
Content-Length: nnn
SOAPAction: http://www.oasis-open.org/committees/security
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<samlp:ArtifactResolve
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
ID="randomlooking" Version="2.0"
IssueInstant="2005-02-09T18:42:32Z">
<Issuer>search.corp.company.com</Issuer>
<samlp:Artifact>RANDOMLOOKINGSTRING</samlp:Artifact>
</samlp:ArtifactResolve>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Note that the SAMLart parameter name is case-sensitive. If a URL contains the parameter name with incorrect cases, the user recieves a 500 error with no indication of why.
The Identity Provider returns:
HTTP/1.1 200 OK
Date: 9 February 2005 18:22:04 PST
Content-Type: text/xml
Content-Length: nnn
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<samlp:ArtifactResponse
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
ID="alsorandomlooking" Version="2.0"
InResponseTo="randomlooking"
IssueInstant="2005-02-09T18:43:32Z">
<Issuer>ac.corp.company.com</Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<samlp:Response
ID="blahblah"
Version="2.0"
IssueInstant="2004-10-08T14:38:05Z">
<samlp:Status>
<samlp:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<Assertion
Version="2.0"
ID="blahblah2"
IssueInstant="2004-10-08T14:38:05Z">
<Issuer>ac.corp.company.com</Issuer>
<Subject>
<NameID>CN=Joe Bob</NameID>
</Subject>
<AuthnStatement
AuthnInstant="2004-10-08T11:32:19Z">
<AuthnContext>
<AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
</AuthnContextClassRef>
</AuthnContext>
</AuthnStatement>
</Assertion>
</samlp:Response>
</samlp:ArtifactResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The Google Search Authorization SPI is exposed to allow a customer's web service to communicate between the Authorization SPI and the customer's server that provides access control services, which this document will refer to as the Policy Decision Point (PDP). The PDP provides a layer between the Google Search Appliance and the customer's access-control system. The PDP will be implemented, tested, and maintained by the customer.
When a user performs a search over access-controlled documents, the user must first authenticate to the Google Search Appliance. This allows the Google Search Appliance to reference the user's identity when making authorization checks, and to include the search user's identity in search logs.
There is an option to turn off cache links and snippets for access-controlled documents. This allows the administrator to assess the risk of storing access-controlled documents on the Google Search Appliance.
As with AuthN, the protocol used between the Google Search Appliance, the browser, and the PDP is taken from SAML 2.0, an XML-based standard, whose primary use case is inter-domain single sign-on. For example, suppose a user is logged in at organization A, and wants to access content at organization B. Instead of forcing the user to log in again, SAML provides a way for the SSO system at A to vouch for the user by communicating with the SSO system at B. In our scenario, the PDP will act as organization A, while the Google Search Appliance will act as organization B.
When the Google Search Appliance needs to check whether a search user has access to a URL, it creates a message containing the user identity and the URL, and sends it to an authorization server. This authorization server is the Policy Decision Point (PDP), a service provided by the customer. In response to authorization check requests, the Policy Decision Point responds with a message that says either "Permit," "Deny," or "Indeterminate." (these terms are defined by the SAML standard.)
For each URL in a search results list, the Google Search Appliance will issue an <AuthorizationDecisionQuery> element, containing the identity of the user and the URL in question, to the Policy Decision Point. The PDP will send back a <Response> message, which will contain an <AuthzDecisionStatement>, and will say whether the user is authorized for the URL. These messages will be exchanged using the SAML SOAP binding over HTTPS.
The format of these messages are defined by SAML, and they are sent over SOAP over HTTPS. How the SAML messages are embedded in SOAP is also defined by SAML, as the "SAML SOAP binding". For complete details, please refer to the SAML standard.
When the Google Search Appliance makes an authorization check, it caches the result. The time that this information is valid is configurable in the Admin Console.
Here are the relevant portions of the SAML schema for the request:
<complexType name="RequestAbstractType" abstract="true">
<sequence>
<element ref="saml:Issuer" minOccurs="0"/>
<element ref="ds:Signature" minOccurs="0"/>
<element ref="samlp:Extensions" minOccurs="0"/>
</sequence>
<attribute name="ID" type="ID" use="required"/>
<attribute name="Version" type="string" use="required"/>
<attribute name="IssueInstant" type="dateTime" use="required"/>
<attribute name="Consent" type="anyURI" use="optional"/>
</complexType>
<element name="Extensions" type="samlp:ExtensionsType"/>
<complexType name="ExtensionsType">
<sequence>
<any namespace="##other" processContents="lax" maxOccurs="unbounded"/>
</sequence>
</complexType>
<element name="SubjectQuery" type="samlp:SubjectQueryAbstractType"/>
<complexType name="SubjectQueryAbstractType" abstract="true">
<complexContent>
<extension base="samlp:RequestAbstractType">
<sequence>
<element ref="saml:Subject"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="BaseIDAbstractType" abstract="true" mixed="true">
<complexContent>
<extension base="anyType">
<attribute name="NameQualifier" type="string" use="optional"/>
<attribute name="SPNameQualifier" type="string" use="optional"/>
</extension>
</complexContent>
</complexType>
<element name="NameID" type="saml:NameIDType"/>
<complexType name="NameIDType" mixed="false">
<simpleContent>
<restriction base="saml:BaseIDAbstractType">
<simpleType>
<restriction base="string"/>
</simpleType>
<attribute name="Format" type="anyURI" use="optional"/>
<attribute name="SPProvidedID" type="string" use="optional"/>
</restriction>
</simpleContent>
</complexType>
<element name="Subject" type="saml:SubjectType"/>
<complexType name="SubjectType">
<choice>
<sequence>
<choice>
<element ref="saml:BaseID"/>
<element ref="saml:NameID"/>
<element ref="saml:EncryptedID"/>
</choice>
<element ref="saml:SubjectConfirmation" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<element ref="saml:SubjectConfirmation" maxOccurs="unbounded"/>
</choice>
</complexType>
<element name="AuthzDecisionQuery" type="samlp:AuthzDecisionQueryType"/>
<complexType name="AuthzDecisionQueryType">
<complexContent>
<extension base="samlp:SubjectQueryAbstractType">
<sequence>
<element ref="saml:Action" maxOccurs="unbounded"/>
<element ref="saml:Evidence" minOccurs="0"/>
</sequence>
<attribute name="Resource" type="anyURI" use="required"/>
</extension>
</complexContent>
</complexType>
The <Subject> element will contain the identity of the search user. For the <Subject> element, the <NameID> element will be used. The format of this identity will be whatever is passed to the Google Search Appliance from the Authentication portion of the Access Control framework. The Resource attribute will be the URL for which we are checking authorization.
For the <Action> element, the attribute for the namespace will have the value "urn:oasis:names:tc:SAML:1.0:action:ghpp". The value for the text of the <Action> element is GET.
The following elements will not be sent to the Policy Decision Point by the Google Search Appliance.
Here are some relevant portions of the SAML schema for the response:
<element name="Response" type="samlp:ResponseType"/>
<complexType name="ResponseType">
<complexContent>
<extension base="samlp:StatusResponseType">
<choice minOccurs="0" maxOccurs="unbounded">
<element ref="saml:Assertion"/>
<element ref="saml:EncryptedAssertion"/>
</choice>
</extension>
</complexContent>
</complexType>
<complexType name="StatusResponseType">
<sequence>
<element ref="saml:Issuer" minOccurs="0"/>
<element ref="ds:Signature" minOccurs="0"/>
<element ref="samlp:Extensions" minOccurs="0"/>
<element ref="samlp:Status"/>
</sequence>
<attribute name="ID" type="ID" use="required"/>
<attribute name="InResponseTo" type="NCName" use="optional"/>
<attribute name="Version" type="string" use="required"/>
<attribute name="IssueInstant" type="dateTime" use="required"/>
<attribute name="Recipient" type="anyURI" use="optional"/>
</complexType>
<element name="Status" type="samlp:StatusType"/>
<complexType name="StatusType">
<sequence>
<element ref="samlp:StatusCode"/>
<element ref="samlp:StatusMessage" minOccurs="0"/>
<element ref="samlp:StatusDetail" minOccurs="0"/>
</sequence>
</complexType>
<element name="StatusCode" type="samlp:StatusCodeType"/>
<complexType name="StatusCodeType">
<sequence>
<element ref="samlp:StatusCode" minOccurs="0"/>
</sequence>
<attribute name="Value" type="anyURI" use="required"/>
</complexType>
<element name="Assertion" type="saml:AssertionType"/>
<complexType name="AssertionType">
<sequence>
<element ref="saml:Issuer"/>
<element ref="ds:Signature" minOccurs="0"/>
<element ref="saml:Subject" minOccurs="0"/>
<element ref="saml:Conditions" minOccurs="0"/>
<element ref="saml:Advice" minOccurs="0"/>
<choice minOccurs="0" maxOccurs="unbounded">
<element ref="saml:Statement"/>
<element ref="saml:AuthnStatement"/>
<element ref="saml:AuthzDecisionStatement"/>
<element ref="saml:AttributeStatement"/>
</choice>
</sequence>
<attribute name="Version" type="string" use="required"/>
<attribute name="ID" type="ID" use="required"/>
<attribute name="IssueInstant" type="dateTime" use="required"/>
</complexType>
<complexType name="StatementAbstractType" abstract="true"/>
<element name="Issuer" type="saml:NameIDType"/>
<element name="AuthzDecisionStatement" type="saml:AuthzDecisionStatementType"/>
<complexType name="AuthzDecisionStatementType">
<complexContent>
<extension base="saml:StatementAbstractType">
<sequence>
<element ref="saml:Action" maxOccurs="unbounded"/>
<element ref="saml:Evidence" minOccurs="0"/>
</sequence>
<attribute name="Resource" type="anyURI" use="required"/>
<attribute name="Decision" type="saml:DecisionType" use="required"/>
</extension>
</complexContent>
</complexType>
<simpleType name="DecisionType">
<restriction base="string">
<enumeration value="Permit"/>
<enumeration value="Deny"/>
<enumeration value="Indeterminate"/>
</restriction>
</simpleType>
<element name="Action" type="saml:ActionType"/>
<complexType name="ActionType">
<simpleContent>
<extension base="string">
<attribute name="Namespace" type="anyURI" use="required"/>
</extension>
</simpleContent>
</complexType>
The namespace set in the <Action> element attribute will be "urn:oasis:names:tc:SAML:1.0:action:ghpp". If the string in an <Action> element is "GET", the Google Search Appliance will display the URL in the search results, along with snippets and the cache link.
Since the URL found in the cache link (the cache URL pointed to by the cache link, not the URL that points to the original document) is not secret, we must again check "GET" authorization for a document when the user tries to access the corresponding cache link URL.
If the value for the Decision attribute in the <AuthzDecisionStatement> is "Indeterminate", rather than "Permit" or "Deny", the Google Search Appliance will then try to check authorization using Basic Authentication, NTLM, or Forms Authentication, if they are configured. If they aren't configured, an answer of "Indeterminate" will be treated as if authorization was denied.
Here is an example of a message the Google Search Appliance might send to the Policy Decision Point:
POST /authz HTTP/1.1
Host: ac.abc.com
Content-Type: text/xml
SOAPAction: http://www.oasis-open.org/committees/security
Content-length: nnn
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<samlp:AuthzDecisionQuery
ID="kmigpcackfenaibdninipcnmkmajfplommhfapbk"
IssueInstant="2004-10-20T17:52:29Z"
Version="2.0"
Resource="http://www.abc.com/secret.html"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<saml:Subject>
<saml:NameID>Joe Bob</saml:NameID>
</saml:Subject>
<saml:Action
Namespace="urn:oasis:names:tc:SAML:1.0:action:ghpp">
GET
</saml:Action>
</samlp:AuthzDecisionQuery>
</soapenv:Body>
</soapenv:Envelope>
Here's an example of a possible response from the Policy Decision Point:
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: nnn
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<samlp:Response
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="blahblah"
Version="2.0"
IssueInstant="2004-10-08T14:38:05Z">
<samlp:Status>
<samlp:StatusCode
Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion
Version="2.0"
ID="blahblah2"
IssueInstant="2004-10-08T14:38:05Z">
<saml:Issuer>abc.com</saml:Issuer>
<saml:Subject>
<saml:NameID>Joe Bob</saml:NameID>
</saml:Subject>
<saml:AuthzDecisionStatement
Resource="http://www.abc.com/secret.html"
Decision="Permit">
<saml:Action
Namespace="urn:oasis:names:tc:SAML:1.0:action:ghpp">
GET
</saml:Action>
</saml:AuthzDecisionStatement>
</saml:Assertion>
</samlp:Response>
</soapenv:Body>
</soapenv:Envelope>
© Google Inc. 2008 - Privacy Policy - Terms and Conditions - About Google
Last modified: