Apr 2, 2010

SAML 2.0 based single sign-on with WSO2 Identity Server

From its 3.0.0 release onwards, WSO2 Identity Server supports SAML 2.0 web browser single sign-on profile. With this feature, WSO2 Identity Server can act as the Identity Provider in single sign-on scenarios while third party service providers can delegate user authentication to Identity Server.

Why single sign-on ?

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.

If you want to experience Identity Server's SSO capabilities, try out WSO2 Cloud Identity. Here is a tutorial, which helps you to set-up single sign-on with Google Apps.

Single Sign-on with Google Apps

Google Apps supports SAML 2.0 based single sign-on. It is possible to point Google Apps to any third party identity provider who supports SAML 2.0 web browser SSO profile for authentication. 

* Configuring Google Apps for Single Sign-on with WSO2 Identity Server

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).

1. Log-in as the administrator of your Google Apps domain.

2. Goto the "Advanced Tools" or administrative panel.

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

 4. Now lets configure the single sign-on to use WSO2 Identity Server 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 Identity Server for authentication instead of authenticating them against the Google Apps user store.
  • Next fill the configuration details.

    • Sign-in page URL - https://{host-name/ip-address}:port/samlsso (users will be redirected to this URL for authentication)
    • Sign-out page URL - https://{host-name/ip-address}:port/samlsso (When an user signs out from Google Apps, WSO2 Identity Server should be notified about it.)
    • Change password URL - https://{host-name/ip-address}:port/carbon (Changing the password should happen through the user management of WSO2 Identity Server)
    • Verification certificate - Upload the public key of the key pair used by WSO2 Identity Server. If you have used your own key pair, then upload the corresponding public key here. If you using the default keys shipped with Identity Server, then the corresponding public key can be downloaded from here.
    • 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 Identity Server for single sign-on. 
    • Finally "Save Changes".

5. 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 Server's end. Hence this set of users should be available in WSO2 Identity Server as well.

The sample configuration used in this post is given below.

* Configuring WSO2 Identity Server for Single Sign-on with Google Apps

1. Change the server URL of Identity Server. This property is available in carbon.xml file which is available in ${WSO2_IS_HOME}/repository/conf.
This should be same as the domain-name/ip-address you have mentioned in the Google Apps SSO Configuration.

Also change the HostName to the ip-address or to the actual hostname. This configuration property is also available in ${WSO2_IS_HOME}/repository/conf/carbon.xml.

2.  Start the server and sign-in as the admin. Goto the "SAML SSO" page which is under the "Manage" menu.

3. Now  add Google Apps as a service provider to WSO2 Identity Server.
  • 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/", 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 Identity  Server 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.
A sample configuration looks similar to the following.

With the above step, both Google Apps and WSO2 Identity Server 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 Identity Server 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/, and he should be redirected to Identity Server's SSO login page.

 Now enter the username/password of the user. Please make sure that, this user should be listed in Google Apps as an authorized user for that domain.

After authenticating, you will be redirected to the Google Apps service you requested, i.e. Google Docs in this scenario.

This feature will be available in WSO2 Identity Server 3.0.0, which will be released soon. Until then you can try out this feature along with many other cool features in our beta packs.