4.8.1.2. eXo Platform server configuration

The eXo Platform server configuration is quite different between the Tomcat and JBoss packages. Here are instructions for both Tomcat and JBoss bundles.

In Tomcat

Note

If you are using eXo Platform bundled with Tomcat, there may be failure of SSO caused by the $PLATFORM_TOMCAT_HOME/lib/jacc-x.y.jar. This file is not necessary, so you can workaround just by removing it.

  1. Add the following to the $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties file (see Configuration overview for this file):

    # SSO
    	gatein.sso.enabled=true
    	gatein.sso.callback.enabled=${gatein.sso.enabled}
    	gatein.sso.login.module.enabled=${gatein.sso.enabled}
    	gatein.sso.login.module.class=org.gatein.sso.agent.login.SSOLoginModule
    	gatein.sso.server.url=http://localhost:8888/cas
    	gatein.sso.portal.url=http://localhost:8080
    	gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.CASLogoutFilter
    	gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout
    	gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@portal.container.name@@/initiatessologin

    In previous versions of eXo Platform, there were much more changes needed in various configuration files. But now, all JARS are available in $PLATFORM_TOMCAT_HOME/lib or $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear/lib, so you do not need to manually add any JAR files. If you are interested in technical details about the single properties and configuration, you can see the below.

    • gatein.sso.enabled - This option will generally enable SSO integration and informs eXo Platform about that.

    • gatein.sso.callback.enabled - This will enable REST callback authentication handler, which is needed if you want CAS server to use SSO Authentication plugin for CAS own authentication. By default, the Callback handler is enabled when the gatein.sso.enabled option is true. You can switch it to "false" if you do not want to use Authentication Plugin on the CAS server side.

    • gatein.sso.login.module.enabled & gatein.sso.login.module.class - There is a special login module configured for gatein-domain in $PLATFORM_TOMCAT_HOME/conf/jaas.conf (Tomcat) or $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml (JBoss) called SSODelegateLoginModule. If SSO is disabled, this SSODelegateLoginModule is simply ignored during authentication process. But if SSO is enabled by this property, it delegates the work to another login module configured via the next option gatein.sso.login.module.class. SSODelegateLoginModule will also resend all its options to its delegate. In case of CAS server, org.gatein.sso.agent.login.SSOLoginModule will be used as delegate. The point of this architecture is, that people do not need to manually change any login module configurations in jaas.conf or standalone-exo.xml.

    The main eXo Platform configuration file for SSO integration is portal.war!/WEB-INF/conf/sso/security-sso-configuration.xml. All needed SSO components like agents and SSO interceptors (former servlet filters) are configured in this file. The idea is that you never need to manually edit this file as most of the options are configurable via exo.properties (see Configuration overview for this file). But in case that something is really not suitable for your usecase or you need to add another custom interceptor or something else, you can manually edit it here. All the additional configuration properties are used especially for substitute values in this security-sso-configuration.xml file.

    • gatein.sso.server.url - Here you need to configure where your CAS server is deployed. In this context, that is http://localhost:8888/cas.

    • gatein.sso.portal.url - Here is URL for access to your GateIn Portal server (actually server you are just configuring). In this context, that is http://localhost:8080.

    • gatein.sso.filter.logout.class - Class of logout filter, which needs to be set to org.gatein.sso.agent.filter.CASLogoutFilter. This filter is able to redirect to CAS server and performs logout on CAS side.

    • gatein.sso.filter.logout.url - CAS server logout URL, which will be used for redirection by logout filter.

      Note

      If you want to disable logout on CAS side, you can simply disable this logout interceptor by adding the gatein.sso.filter.logout.enabled with the "false" value. This will cause that click to Sign out on portal side will logout user from eXo Platform but not from CAS server. In this case, both gatein.sso.filter.logout.class and gatein.sso.filter.logout.url will be ignored.

    • gatein.sso.filter.login.sso.url - CAS server login URL, which will be used by LoginRedirectFilter for redirection to CAS server login page.

      Note

      The @@portal.container.name@@ string will be dynamically replaced by the correct name of portal container, where it will be executed. The SSO component will do it, so in configuration, you should really use the @@portal.container.name@@ string instead of some hard-coded portal container name (like portal or sample-portal).

    Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form. And on CAS you will be able to authenticate with portal credentials (like john/gtn) thanks to Authentication plugin.

  2. Add <Valve className="org.gatein.sso.agent.tomcat.ServletAccessValve" /> to $PLATFORM_TOMCAT_HOME/conf/server.xml. The content of this file now looks like:

    
    ...
        <Engine name="Catalina" defaultHost="localhost">
            <Host name="localhost" appBase="webapps" startStopThreads="-1"
                  unpackWARs="${EXO_TOMCAT_UNPACK_WARS}" autoDeploy="true">
                <Valve className="org.gatein.sso.agent.tomcat.ServletAccessValve" />
                ... 
                <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
                ...
                <Listener className="org.exoplatform.platform.server.tomcat.PortalContainersCreator" />
                ...
            </Host>
        </Engine>
    ...

In JBoss

  1. Edit the $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties file (see Configuration overview for this file):

    # SSO
    		gatein.sso.enabled=true
    		gatein.sso.callback.enabled=${gatein.sso.enabled}
    		gatein.sso.login.module.enabled=${gatein.sso.enabled}
    		gatein.sso.login.module.class=org.gatein.sso.agent.login.SSOLoginModule
    		gatein.sso.server.url=http://localhost:8888/cas
    		gatein.sso.portal.url=http://localhost:8080
    		gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.CASLogoutFilter
    		gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout
    		gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@portal.container.name@@/initiatessologin

    In which:

  2. Uncomment the below login module in $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml, then change ${gatein.sso.login.module.enabled} and ${gatein.sso.login.module.class} into #{gatein.sso.login.module.enabled} and #{gatein.sso.login.module.class} respectively.

    
    <login-module code="org.gatein.sso.integration.SSODelegateLoginModule" flag="required">
        <module-option name="enabled" value="#{gatein.sso.login.module.enabled}"/>
        <module-option name="delegateClassName" value="#{gatein.sso.login.module.class}"/>
        <module-option name="portalContainerName" value="portal"/>
        <module-option name="realmName" value="gatein-domain"/>
        <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>

    Now, you can move to the next section for testing.

Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus