This article was written and submitted by an external contributor. The Google Apps team thanks Will Norris for his time and expertise.
Shibboleth is standards-based, open source middleware software which provides web single sign-on across or within organizational boundaries. It allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner.
Version 2.0 of the Shibboleth Identity Provider supports the SAML2 specification and is therefore ideal for use with Google Apps. This document will describe the steps required to configure a stock Shibboleth 2.0 Identity Provider to achieve single sign-on with Google Apps. It does not attempt to cover the steps required to install Shibboleth, for that please refer to the Shibboleth Wiki.
Configuring Google Apps
First configure your Google Apps instance to look to Shibboleth for single sign-on. To do this, go to the Google Apps domain management screen, click on Advanced tools, and then on Set up single sign-on (SSO). Configure the following options:
Enable Single Sign-on - check this box to turn on SSO for your domain.
Sign-in page URL - Set this to the URL of Shibboleth’s SAML2 Redirect SSO endpoint. If you followed the standard install instructions, this will likely be something along the lines of
Sign-out page URL - Shibboleth 2.0 does not yet support logout, so you can either implement your own mechanism or set up a static page that instructs the user to close their web browser. The URL of that page should go here.
Change password URL - Set this to the URL of your existing enterprise password change website.
Verification certificate - Shibboleth 2.0 generates a self-signed certificate during installation. That file should be located at
IDP_HOME/credentials/idp.crtwhere IDP_HOME is your Shibboleth installation path. Upload this certificate file to Google so that your assertions can be verified.
Add Google Metadata
The Shibboleth IdP must know some basic information about the Google relying party, which is defined in SAML metadata. The easiest way to do this is to create a new
IDP_HOME/metadata/google-metadata.xml file with the following contents. There is much more information that could be added here, but this is the minimum required to get things working. Be sure to replace
YOURDOMAIN.COM with the domain you have set up in Google Apps.
<EntityDescriptor entityID="google.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"> <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat> <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.google.com/a/YOURDOMAIN.COM/acs" /> </SPSSODescriptor> </EntityDescriptor>
Configure Relying Party
Instruct Shibboleth how to behave when talking to Google by defining a new
RelyingParty element in
IDP_HOME/conf/relying-party.xml. The following snippet should be added just after the
DefaultRelyingParty element. Be sure to replace the
provider attribute to include your entity ID (use whatever
provider is configured in the
<RelyingParty id="google.com" provider="YOUR-ENTITY-ID" defaultSigningCredentialRef="IdPCredential"> <ProfileConfiguration xsi:type="saml:SAML2SSOProfile" encryptAssertions="never" encryptNameIds="never" /> </RelyingParty>
Still in the
IDP_HOME/conf/relying-party.xml file, configure Shibboleth to use the new metadata file you created earlier. Add the following
MetadataProvider element next to the existing configured provider (it should have an
id value of “FSMD” or “URLMD”), making sure to replace
IDP_HOME with your actual installation path.
<!-- Google Metadata --> <MetadataProvider id="GoogleMD" xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" metadataFile="IDP_HOME/metadata/google-metadata.xml" maintainExpiredMetadata="true" />
Configure Attribute Resolver
Google expects the username of the user logging in to be passed as the SAML Name Identifier. Shibboleth’s attribute resolver must be configured to make this data available by modifying
IDP_HOME/conf/attribute-resolver.xml. The following attribute definition provides a very basic method to do this by sending the principal name that was used to authenticate to the IdP. For production deployments where the name used to authenticate the user might not match the account name at Google, you may need to store the Google Apps ID in a relational database or LDAP directory.
<resolver:AttributeDefinition id="principal" xsi:type="PrincipalName" xmlns="urn:mace:shibboleth:2.0:resolver:ad"> <resolver:AttributeEncoder xsi:type="SAML2StringNameID" xmlns="urn:mace:shibboleth:2.0:attribute:encoder" nameFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" /> </resolver:AttributeDefinition>
Configure Attribute Filter
Finally, configure the Shibboleth attribute filtering engine to release the
principal attribute (encoded as a NameID) to Google. Add the following XML snippet to
IDP_HOME/conf/attribute-filter.xml alongside the existing policy elements.
<AttributeFilterPolicy> <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="google.com" /> <AttributeRule attributeID="principal"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> </AttributeFilterPolicy>
If all went well, you should now have Shibboleth 2.0 successfully authenticating users to Google Apps. With the possible exception of a more robust attribute resolver configuration (retrieving the Google ID from LDAP or a database), this configuration should be well-suited for large-scale production deployments.
Shibboleth has a very active user community that can be found contributing to the Shibboleth wiki or on the mailing lists below.
Will Norris is a software engineer with extensive experience in identity technologies such as OpenID and SAML. He is a developer of the DiSo Project, as well as a member of the core development team for Shibboleth, a popular open source single sign-on product. He lives with his wife in Portland, OR and can be found online at http://willnorris.com.
This work is licensed under a Creative Commons Attribution-No Derivative Works 3.0 United States License.