As part of an ongoing series, we’re helping to explain ways to configure SimpleSAMLphp as a centralized identity provider (IDP) for your organization.
Last week, we integrated our existing SimpleSAMLphp server with Azure Active Directory so that we could use it as an identity provider for Microsoft’s Office 365. This week, we’ll do the same type of integration, but with Google’s G-Suite. When logging into tools like Gmail with our domain, users will be directed to our server for authentication instead.
Key Components
In order to follow along with this tutorial, you’ll need access to the following components:
SimpleSAMLphp Server – You can (and should) use the same server we’ve been working with for the past few weeks. As with last week, continuing to use Tozny for authentication is not a requirement so long as you have some authentication provider configured.
Google G-Suite – a hosted suite of office productivity apps produced, hosted, and maintained by Google. If you’ve used Gmail or Google Docs you’ve used the free version; the G-Suite is the business-ready version that works with your own domain. You will need to set up an account and have administrator credentials.
Configuring SimpleSAMLphp
As with previous weeks, we will assume the users’ authentication domain is somesite.com and the SimpleSAMLphp server is running on a dedicated subdomain like sso.somesite.com.
IDP and Authentication
To make things simpler, we’ll use the same configuration from our last few tutorials – you will have an authentication source called “somesite” that uses the “tozyauth:External” module for authentication against Tozny’s secure API. For reference, the configuration in authsources.php will look like:
'somesite' => array( 'toznyauth:External', 'realm_key_id' => 'sid_...', 'realm_secret_key' => '49f127...fd9', 'api_url' => 'https://api.tozny.com', 'attributes' => array( 'IDPEmail' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:emailAddress', ), ),
The configuration in /metadata/saml-20-idp-hosted.php will look like:
$metadata['https://sso.somesite.com'] = array(
// The hostname of the server this SAML entity will use.
'host' => 'sso.somesite.com',
// X.509 key and certificate. Relative to the /cert directory.
'privatekey' => 'somesite.key',
'certificate' => 'somesite.crt',
'auth' => 'somesite',
);
Remote Service Provider
For this walkthrough, we will set up a new hosted service provider for G-Suite to use – this means telling SimpleSAMLphp what set of metadata to use when it prepares the SAML document after a user authenticates.
To create the new service provider, add the following to /metadata/saml20-sp-remote.php, replacing somesite.com with the appropriate domain you’re configuring:
// Google configuration for Tozny IDP $metadata['google.com/a/somesite.com'] = array( 'AssertionConsumerService' => 'https://www.google.com/a/somesite.com/acs', 'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:email', 'simplesaml.nameidattribute' => 'IDPEmail', 'simplesaml.attributes' => FALSE, );
When Google redirects users to SimpleSAMLphp, the server will load this information and use it to prepare the SAML response and send it to the correct location (the AssertionConsumerService field above) when the user has completed authentication. Google uses the email address of the newly-logged-in user to identify them in their own system, so the “mail” field needs to be passed along as the primary identifier.
Configuring the G-Suite
Configuring the Google side of things requires an administrator account and takes place entirely in the Google Admin Console at https://admin.google.com/somesite.com.
Note: Even when configuring Tozny’s app-powered authentication for your users, administrators will still need to use a password to login. This allows them to login independent of any external IDP configuration.
After logging in, select the “Security” tile. Then scroll to the bottom of the page and click “Set up single sign-on (SSO).”
Only administrators can manage security and configure SSO settings.
The SSO configuration page has many options; we want to select the “Setup SSO with third party identity provider” section to configure the SimpleSAMLphp connection. The values that you need here are as follows:
- Sign-in page URL: https://sso.somesite.com/saml2/idp/SSOService.php
- Sign-out page URL: https://sso.somesite.com/module.php/core/authenticate.php?as=somesite
- Change password URL: https://sso.somesite.com/module.php/core/authenticate.php?as=somesite
In the options above, we point at our SimpleSAMLphp server and specify the “somesite” authentication source where explicitly needed. If your server is powering multiple authentication systems, this differentiation is important to keep credentials from getting lost during the back-and-forth communication with the server.
Finally, you will need to upload the verification certificate configured for your server – you can download your certificate at https://sso.somesite.com/module.php/saml/idp/certs.php/idp.crt – so Google can verify the signature on any SAML assertions sent during login.
Provisioning Users with Google
Creating users is a two-step process. The users must exist both in Tozny’s system (or your chosen authentication service) to power authentication and in Google’s system to power licensing and authorization to various services. If you haven’t already created a user with Tozny, visit the admin portal and do so, setting the IDPEmail field to be equal to the email address the user will use when authenticating with Google (i.e. alice.smith@somesite.com).
If you’re using an authentication source besides Tozny, create your user there and set the IDPEmail appropriately.
Now, return to the Google admin portal and select the “Users” tile. From here, you can create as many users as you need for your organization – just be sure the email addresses match those configured on the Tozny side.
While you can configure multiple settings and application permissions through the admin portal, the only required component for remote SimpleSAMLphp authentication is that the user exist.
Remember: Super users and administrators should still use passwords for authenticating against Google services so they can log in for management independently of the external IDP. This will help protect against potential outages should anything go wrong with either SimpleSAMLphp or the external IDP you use for authentication.
Testing the Workflow
Once the users are created in both the Tozny and Google systems, you can test the account by visiting the default Gmail login page.
Enter the email address you’ve just configured – Google will automatically detect that it’s tied to an external authentication provider and will redirect to SimpleSAMLphp to proceed with authentication.
When successful, SimpleSAMLphp will create a signed document providing the user’s information and pass it back to Google’s access control service. Google will then check to see which products the user is authorized to use and, if allowed, take them to their Gmail inbox.
The same authentication flow is present for any G-Suite service. Once a user is logged in, they will have access to any G-Suite service for which your organization has authorized them.
Related Reading
While this tutorial itself was geared towards using Tozny as an identity provider, the steps above can be used to integrate Google’s G-Suite with other SAML providers as well. Like Office 365, you can also turn things around and use Google as an identity provider for other hosted platforms.
Google also supports OpenID Connect, both as an identity provider (login to other platforms via Google) or as a service provider (login to Google using credentials from another platform). This support for additional identity and authentication frameworks opens the doors for numerous third-party integrations.