How to integrate Google Apps with WSO2 Cloud Identity ?

What is WSO2 Cloud Identity?

WSO2 Cloud Identity reduces the complexity of deploying and maintaining an identity management system locally. In addition to that, it takes away the burden and cost involved in managing hardware for running an identity management system. With WSO2 Cloud Identity organizations can achieve centralized identity management, which eliminates the requirement of maintaining multiple user bases. Centralized identity management combined with Single Sign-On facilitates organizations to achieve seamless integration across its internal applications as well as other applications and services hosted outside of the organization like Software as a Service solutions.

WSO2 Cloud Identity is based on open source WSO2 Identity Server. In simple words, WSO2 Cloud Identity is WSO2 Identity Server is in cloud. WSO2 Identity Server supports a range of open identity standards including OpenID, Information cards, XACML, SAML 2.0 and various WS-* specifications.

Single Sign-On with WSO2 Cloud Identity

Single Sign-on(SSO) allows users to sign-in once and access all authorized resources. Single Sign-On eliminates the necessity of maintaining multiple user bases and centralizes the identity management and authentication to a single point. Users do not need to remember several username/password pairs to access various applications and services. So organizations benefit a lot by having SSO enabled within their organization.

WSO2 Cloud Identity supports single sign-on based on SAML 2.0. It implements SAML 2.0 Web Browser Single Sign-On profile and Single Logout profile.

Google Apps integration with WSO2 Cloud Identity

Google Apps supports SAML 2.0 based Single Sign-On. With WSO2 Cloud Identity, organizations can easily use their existing user bases to access Google Apps. It eliminates the requirement of maintaining user credentials at Google Apps, rather maintain them in WSO2 Cloud Identity and use them to provide access to Google Apps along with other services and applications which supports SAML 2.0 based Single Sign-on. Configuring WSO2 Cloud Identity to work with Google Apps needs a couple of configurations which can be done in few minutes.

What are the prerequisites for integrating Google Apps with WSO2 Cloud Identity?

• You should own a Google Apps domain. You can try a 30-days evaluation(needs to prove the ownership of the domain) or 14 days sample account(having an Gmail account is sufficient).
• Register a domain in WSO2 Cloud Identity. This does not need to be the same domain name as Google Apps domain.
• Add the users to your domain in WSO2 Cloud Identity. Users can be added individually or using "bulk user import" functionality as explained in this article.
• Add users to Google Apps and configure the allowed Google Apps services for each of them. This step is required, because Google restricts the number of users depending on your subscription. Only the usernames should be added to Google Apps, while their credentials are maintained at WSO2 Identity Cloud's end. Hence this set of users should be available under you domain in WSO2 Cloud Identity.

How to integrate Google Apps with WSO2 Cloud Identity

1. To start with, you need to have a domain registered at WSO2 Cloud Identity. Then it is required to generate a key pair for your domain in WSO2 Cloud Identity. These keys will be unique across all domains and will be used to sign SAML assertions issued by WSO2 Cloud Identity. For that login as the admin of that domain and goto "Account Management" page under "Configure" menu.

2. At the bottom of the page, you will find the Key Generation section. Click on the "Generate Key" button if you haven't generated keys yet. This will generate a key pair for your domain and make the public key available to download.

3. Click on the "Download public key" link and save the public key file in your file system.

4. Now goto your Google Apps administration panel. Goto "Advanced tools" section.

5. You will find "Set up single sign-on" link under "Authentication" section. Goto this page to configure the single sign-on settings.

6. Now lets configure the single sign-on to use WSO2 Cloud Identity for authentication.

• First enable the single sign-on by ticking the "Enable Single Sign-On" check box. Now the users will be redirected to WSO2 Cloud Identity for authentication instead of authenticating them against the Google Apps user store.
• Next fill the configuration details.
  • Sign-in page URL - https://identity.cloud.wso2.com/samlsso (users will be redirected to this URL for authentication)
  • Sign-out page URL - https://identity.cloud.wso2.com/samlsso (When an user signs out from Google Apps, WSO2 Cloud Identity should be notified about it.)
  • Change password URL - https://identity.cloud.wso2.com/t/<WSO2-cloud-identity-domain-name> (Changing the password should happen through the user management of WSO2 Cloud Identity)
  • Verification certificate - Upload the public key downloaded in step 3, after generating a key pair for the domain. This certificate will be used to validate the integrity of SAML 2.0 tokens issued by WSO2 Cloud Identity after authenticating an user.
  • Use a domain specific issuer - You can leave this check-box checked or unchecked. If you check it, then the Authentication Request issued by Google Apps will contain an unique issuer name,like "google.com/a/example.com", else it's value will be "google.com".  You can read more about this here. This issuer name will be required when configuring the WSO2 Cloud Identity for single sign-on. 
  • Finally "Save Changes".

Following is the sample configuration which will be used in this tutorial.

With this, necessary configurations at the Google Apps' end are completed. Now lets configure the WSO2 Cloud Identity to work with Google Apps.

7. Login as the admin of your domain. Goto the "SAML SSO" page which is under the "Manage" menu.

8. Now  add Google Apps as a service provider to WSO2 Cloud Identity. 

• Issuer - The value of this field depends on your choice of using a domain specific issuer during the SSO configuration at Google Apps. If you have checked "Use domain specific identifier" check box, then the value of this field should be "google.com/a/<google-apps-domain-name>", else it should be "google.com". Since it is not set to use a domain specific identifier in this tutorial, the value of this field should be "google.com"
• Assertion Consumer URL - https://www.google.com/a/<google-apps-domain-name>/acs (Identity Provider should use this URL to send the SAML assertion containing the authentication status)
• Enable Signature Validation in Authentication Requests and Logout Requests - Enabling this option will make sure that the integrity is protected in all the authentication and logout requests that WSO2 Cloud Identity SSO Service receives. Since Google does not sign the SAML Tokens in requests, it is not required to enable this.
• Certificate Alias : If the signature validation is enabled, the public key of the service provider is required to do the signature validation of the SAML Tokens. So the publlic key of the service provider should be imported to the keystore and point to that certificate using its alias. Since signature validation is not required for requests issued by Google Apps, specifying an alias is not required.
• Custom Logout URL - This URL will be used in Single Logout. Since Google Apps does not support it, this field can be left blank.

Now Click "Add" to save the configuration. Now Google Apps should be listed as a service provider.

With the above step, both Google Apps and WSO2 Cloud Identity are configured for SSO.

Now when some non-admin user tries to access a Google Apps service like mail, docs and calendar he should be redirected to WSO2 Cloud Identity for authentication. For instance, if an user wants to access google docs, he should be trying to access it through https://docs.google.com/a/<google-apps-domain>, and he should be redirected to WSO2 Cloud Identity SSO login page.

 Now enter your username and password. Please make sure, you are providing your complete username, i.e. username@wso2-cloud-identity-domain. For example, [email protected]-trial should be used as the username by the user called "clouduser" who belongs to the domain called "example.com-trial".

If the user is successfully authenticated, he is allowed to access the Google Apps service he requested.

Now there is a session created for the user at the WSO2 Cloud Identity, which allows him to login to any other service(external to Google Apps) without providing username/password again until user terminates the session or session gets expired.

If a user wants to sign out from Google Apps, he can click on "Sign out" link which will redirect him to WSO2 Cloud Identity which will terminate his session there.

WSO2 Cloud Identity supports Single Logout profile. So when an user's session at WSO2 Cloud Identity is terminated,  this has to be notified to other session participants who support Single Logout and (there should be a Custom logout URL in the SSO Config). So the user will be signed out from all the services. If any of the service providers does not support Single Logout, the "Custom Logout URL" field can be left blank in the SSO Configuration. So WSO2 Cloud Identity will not take them into account, when performing Single Logout.

To gain the actual benefit of WSO2 Identity Cloud's SSO capability, multiple services should be added as service providers and they should delegate user authentication to WSO2 Cloud Identity. It will enable a seamless integration across multiple services and applications while making the lives of users easier. WSO2 Cloud Identity will keep on adding support for widely used services and applications which support Single Sign-On.

To get a more understanding about WSO2's Cloud offerings visit here.

Author

Thilina Buddhika, Software Engineer, WSO2 Inc., thilinab AT wso2 DOT com.