JCMS SSO Plugin 2.1

This plugin requires JCMS 9.0 or above.

1. Introduction

This module provides Single Sign On and Member synchronization accross multiple instances of JCMS.
Any webapp other than JCMS can benefit from this SSO using a custom developpement based on JCMS OpenAPI.

The following terms will be used throughout this documentation :

• Main JCMS instance : the one JCMS webapp which is used as the central repository for authentication and Members.
• JCMS client webapp : any JCMS webapp on which the module is installed in order to benefit from authentication of the main JCMS instance.
• External client webapp : any webapp (other than JCMS) that wants to benefit from authentication of the main JCMS instance.
• SSO Ticket : this is an authentication ticket generated on the main JCMS instance and used by client webapps to authenticate members.

2. Principles

A JCMS Single Sign On is performed in three steps :

1. STEP 1 on the client webapp : redirection of unautheticated user to the main instance for the SSO request.
2. STEP 2 on the main JCMS instance : the SSO request is validated and user is redirected to the client webapp with a SSO ticket.
3. STEP 3 on the client webapp : the client webapp read the SSO ticket and use it to perform an Open API request to authenticate (and synchronize the member if needed).

Here is a more detailed explanation of what happens during those three steps :

• STEP 1 (on the client webapp) :
  1. The user access a client webapp unauthenticated.
  2. The client webapp redirects the user to the main JCMS instance asking for an SSO ticket. (through JSP plugins/JcmsSSOPlugin/jsp/sso.jsp).
• STEP 2 (on the main JCMS instance) :
  1. The main JCMS instance ensure the SSO request comes from an authorized site (by checking parameter JcmsSsoRedirect against property specified in admin plugin properties).
  2. If the user is not yet authenticated on the main JCMS instance, he is request to do so.
  3. Once authenticated on the main JCMS instance, a SSO ticket is generated for this member. The SSO ticket can only be used to perform a REST request for this Member (http://www.example.com/rest/data/{memberId}) and is valid only during a specific duration.
  4. The user is redirected to the client webapp with the SSO ticket.
• STEP 3 (on the client webapp) :
  1. The client webapp reads the SSO ticket from parameters JcmsSsoMemberId and JcmsSsoAuthKey.
  2. Using OpenAPI, the client webapp performs a request to the main JCMS instance in order to validate the SSO ticket and retrieve all Member informations (http://www.example.com/rest/data/{memberId}).
  3. Once the login of the member has been retrieved from Open API, the synchronization occurs : 
     A first synchronization attempt is performd using LDAP if it is enabled. If LDAP is disabled or if LDAP synchronization failed, the member is synchronization using informations retrieved from OpenAPI. (See FAQ below for more information on synchronization rules).

3. Installation

3.1 Installation on the main JCMS instance

1. Deploy the module on the main JCMS instance and restart.
2. Edit the plugin admin properties and enter the following informations :
   • Main JCMS ? (required) : Set to true.
   • Main JCMS URL (required) : Enter the base URL of the main JCMS instance 
     e.g. http://www.example.com/
   • Authorized sites (required) : Enter the exact base URLs of all sites which are allowed to use this main instance as SSO. 
     e.g. http://site1.example.com/, http://site2.example.com/
   • Authorized groups (optionnal) : Enter the list of Group a Member MUST belong to in order to be allowed to authenticate using the SSO.
     Use this option as an added security layer for more control on who is authorized to use SSO and who is not.
   • SSO ticket duration (optionnal) : Default value is set to 15 seconds which is fine in most cases. Increase this value if your network suffer from very high latency, decrease value to improve security.
3. Edit the administration properties in the "Web Services" tab and enable OpenAPI.
   Make sure all the IP addresses of the clients webapps are authorized to perform OpenAPI requests.
4. Optionnal : configure your LDAP settings.

3.2 Installation on any JCMS client webapp

1. Deploy the module on the client JCMS webapp and restart.
2. Edit the plugin admin properties and make sure you enter the following informations (all other settings are only used by the main JCMS instance) :
   • Main JCMS ? (required) : Leave to false.
   • Main JCMS URL (required) : Enter the base URL of the main JCMS instance 
     e.g. http://www.example.com/
   • Authorized groups (optionnal but highly recommended) : Enter the Groups a Member MUST belong to to be allowed to authenticate using the JCMS SSO.
     Using this option prevent identity theft as explained below.
   • Default groups (optionnal) : Groups used when creating new Member through Open API synchronization.
     Useful to track which Members were created from SSO. This option should contains all the groups specified in Authorized groups
3. Optionnal : configure your LDAP using the same settings entered in the main JCMS instance.

VERY IMPORTANT note regarding SECURITY and identity theft of existing accounts :
Follow the recommendations below to fill the Authorized groups option. Without this option a malicious user could change its username on the main JCMS instance to match an existing user on the client webapp, thus gaining access to client webapp as a user with existing privileges. (e.g. the user "simpleuser" change its login to "someadmin" on the main JCMS, then he can access the client webapp and will be authenticated as "someadmin").
By specifying this option, existing member will NOT be allowed to authenticated using the SSO, UNLESS you add them to the proper group.

Recommendations :

1. Specify at least one group in the Authorized groups option,
2. Check existing account ONE BY ONE and add them to the previous group ONLY IF the corresponding member already exists on the main JCMS,
3. Specify the same group in the Default groups option to ensure Members created through OpenAPI synchronization are automatically authorized.

3.3 Installation on external client webapp

Use of this plugin for external client webapp requires a custom developpement, see section below.

4. External client developpment

4.1 Learn

• Read documentation of your web application to learn how to developp a custom authentication mecanism.
• Read section "Principles" above to make your you understand how JCMS SSO works and how to apply it in your client webapp.
• Read JCMS OpenAPI Client documentation to learn how to use it.

4.2 Develop

First ensure your client webapp has been authorized to use the JCMS SSO on the main JCMS instance.

The login process

• From your client webapp, redirect unauthenticated user to the following URL on the main JCMS instance (STEP 1 in the principles) :

  http://mainjcms.example.com/plugins/JcmsSSOPlugin/jsp/sso.jsp?JcmsSsoRedirect={redirectUrl}

  Where {redirectUrl} is the absolute URL where the user will be sent after authentication on the main site.
• Read parameters JcmsSsoMemberId and JcmsSsoAuthKey, then perform the Open API Request to synchronize and login the user (STEP 3 in the principles).
  Here is a simple (and incomplete) example in Java using JCMS OpenAPI Client :

    final String mainJcmsUrl = "http://mainjcms.example.com/";
    String remoteMbrId = request.getParameter("JcmsSsoMemberId");
    String authKey = request.getParameter("JcmsSsoAuthKey");
    if (Util.isEmpty(remoteMbrId) || Util.isEmpty(authKey)) {
      return null;
    }
    
    ClientSession clientSession = new ClientSession(mainJcmsUrl);
    JcmsApp jcmsApp = new JcmsApp(clientSession);
    String memberResourcePath = mainJcmsUrl + jcmsApp.getDataPath(remoteMbrId);
    clientSession.setAuthentication(new AuthKeyAuthentication(memberResourcePath, authKey));
    try {
      logger.info("[JCMSSSO-STEP3] Performing OpenAPI request : " + memberResourcePath);
      JcmsResource memberResource = jcmsApp.getData(remoteMbrId);
      MemberElement memberElement = MemberElement.getFirstMemberElement(memberResource, clientSession);
      String login = memberElement.getLogin();
      [...] // authenticate user from this login (synchronize it if needed)
    } catch (Exception ex) {
      logger.warn("[JCMSSSO-STEP3] An exception occured while performing Open API request on '" + mainJcmsUrl + "' to retrieve information for remote Member '" + remoteMbrId + "'. ", ex);
      [...] // display error message to user
    }
  

  Note : this example uses the class MemberElement which is avaible in JCMS OpenAPI Client from JCMS 6.1.2 but is also bundled in the JCMS SSO Plugin jar.

The logout process

From your client webapp, redirect authenticated user to the following URL on the main JCMS instance :

http://mainjcms.example.com/plugins/JcmsSSOPlugin/jsp/logout.jsp

The user will be logged out on the main JCMS instance. You are responsible to logout the user from your webapp before or after this operation.
You can provide an optionnal redirect parameter if you want to redirect the user to a specific location after the logout on the main JCMS instance.

5. Advanced Configuration

Access Rule for JCMS client webapps

On client webapps, you can configure one "Access Rule" in the proprties to trigger the redirection and authentication on the main JCMS instance only when some condition are met, as defined by the rule and its configuration.

Some basic access rules are provided in the package com.jalios.jcms.authentication.rules 
You can implement your own access rule by extending the AccessRule interface.

See Javadoc for more informations on existing rules and development of your own rule.
Javadoc of access rules is bundled inside the plugin, in the directory répertoire plugins/JcmsSSOPlugin/docs/javadoc/access-rules/ 

The following example declares an access rule based on the client IP address. In this example JcmsSSO will be used only for clients in the network 192.168.0.0/24 :

jcmsplugin.jcmssso.access-rule.class:     com.jalios.jcms.authentication.rules.IpAccessRule
jcmsplugin.jcmssso.ip-access-rule.regex:  ^192\\.168\\.0\\..*

If no access rule parameter is specified in properties , the default behavior of the JcmsSSO Authentication is applied (that is clients are always redirect from JCMS client webapps to the main JCMS instance when they are not logged in).