I recently had to undertake some work to enable users to seamlessly authenticate to Google Apps using an identity stored in a custom Secure Token Service such as the excellent IdentityServer open source STS by Dominick Baier. The work involved is mostly configuration in Google Apps and ADFS but there are quite a number of steps and as it was non-trivial I thought I’d document it here for reference. Note that Google Apps uses SAML 2.0 tokens and because ADFS is brokering the authentication, you shouldn’t have any problems with compatibility as ADFS 2.0 can issue SAML 2.0 tokens.
Here’s a quick architecture diagram:
Green arrows = user request flow
Blue arrows = service response flow
For those of you impatient, here’s a quick overview of the steps required:
- Enable SSO in Google Apps
- Enter correct ADFS urls into Google Apps
- Upload ADFS Token Signing Certificate so Google Apps can verify the SAML tokens
- Add Google Apps as a Relying Party in ADFS
I will now walk through each stage in detail, for those who like the details.
Enable SSO in Google Apps
The first stage is to enable Single Sign-on in Google Apps. Log in to your administration console at /">http://www.google.com/a/<your-domain>/. Click on Advanced Tools and in the Authentication section click on Set up single sign-on (SSO):
This will take you through to a configuration screen. Make sure the checkbox next to Enable Single Sign-on is ticked, and then enter the following values:
Sign-in page URL: https://adfs.yourdomain.com/adfs/ls/
Sign-out page URL: https://adfs.yourdomain.com/adfs/ls/
Change password URL: https://sts.yourdomain.com/startersts/users/password.aspx
Verification certificate: Upload the ADFS Token Signing cert (.cer file) which you can obtain from the AD FS 2.0 Management Console (under Service > Certificates). Remember to click Upload.
Check the box next to “Use a domain specific issuer”.
Enter some network addresses into the Network masks box if you wish.
At this point Single sign-on is configured and enabled. Note that this will take immediate effect on your access to Google Apps services so beware! However it does not affect your login to the admin console – that is always accessed via a manual login, so you can get in and turn it off again.
Open up the AD FS 2.0 Management Console and navigate to the Relying Parties section. Click Add Relying Party Trust and follow these steps:
Choose Enter data about the relying party manually
Provide a name for the trust (not important, only so you can easily identify it)
Choose AD FS 2.0 profile
Tick Enable support for the SAML 2.0 WebSSO protocol and enter /acs">https://www.google.com/a/<your-domain>/acs into the Relying party SAML 2.0 SSO service URL
Enter google.com/a/<your-domain> as the relying party identifier
Complete the wizard.
Then click on the newly added item and click Properties. Click on the Signature tab and click add:
Here we add the Token Signing Certificate – it must be the same one that we uploaded in the Google admin console, and this should be the ADFS Token Signing Certificate.
Once you’ve done that click OK to close the Properties dialog.
Now click Edit Claim Rules and click Add Rule:
Select Transform an Incoming Claim from the Claim rule template drop-down:
Give the rule a name, select E-Mail Address as the Incoming Claim Type, set the Outgoing claim type to Name ID and the Outgoing name ID format to Email:
Finish the wizard.
I’ve assumed here that you’ve already got your custom STS configured as a Claims Provider in ADFS. To test the end-to-end service, visit http://mail.google.com/a/<your-domain>. You should get redirected to ADFS. Choose your STS and then enter your credentials. You should then be redirected back to Google Apps and arrive at your mailbox, logged in.
If you hit problems, check these items:
- You’ve got the correct certificate uploaded to Google Apps and configured in ADFS
- The time on the ADFS server and custom STS servers is correct
- Google Apps SSO configuration is correct
- If all else fails, try Googling!