Chapter 5. Security

Change the JAAS realm
Update the password encryption key of the RememberMe token

eXo Platform relies on JAAS for propagating the user identity and roles to the different applications deployed on the server.

The JAAS realm will be used by all eXo apps and even propagated to the JCR for Access Control

By default, Platform uses a JAAS realm named "gatein-domain". If your IT operations rules require you to use another JAAS realm, you will need to modify several files so that eXo can work on your JAAS realm.

Since the security configuration is highly dependent of the app server we'll cover each application sever separately.

In the Tomcat bundle, the jaas configuration is controled by this $TOMCATHOME/conf/jaas.conf : 

gatein-domain {
  org.exoplatform.web.security.PortalLoginModule required;
  org.exoplatform.services.security.jaas.SharedStateLoginModule required;
  org.exoplatform.services.security.j2ee.TomcatLoginModule required; 
};

Replace gatein-domain by your own domain name.

Tip

Learn more about the syntax in the JAAS tutorial. Read more about realms in tomcat in the Tomcat Realm Howto

For JBoss, you need to edit the default jaas security domain in 02portal.war!WEB-INF/jboss-web.xml 

<jboss-web>
  <security-domain>java:/jaas/gatein-domain</security-domain>
</jboss-web>

Additionnaly, you need to edit the application-policy to match the security-domain in gatein.ear!META-INF/gatein-jboss-beans.xml.

<deployment xmlns="urn:jboss:bean-deployer:2.0">

  <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-domain">
    <authentication>
      <login-module code="org.exoplatform.web.security.PortalLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>
      <login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>
      <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">
        <module-option name="portalContainerName">portal</module-option>
        <module-option name="realmName">gatein-domain</module-option>
      </login-module>
    </authentication>
  </application-policy>
  
</deployment>

Tip

Read More about JBoss security configuration in JBoss Web Docs

Finally, there are some common changes to do on both app servers.

First, change the JAAS realm to match your own security constraints, inside the configuration.properties file, identify the entry named "exo.security.domain

# Realm name
exo.security.domain=gatein-domain

Note

Internally, eXo will use this setting to set a new variable named "portal.container.realm" that is then used in kernel configuration files such as platform-extension/WEB-INF/conf/platform/repository-configuration.xml.

Inside portal.war, you should declare in the web.xml file the realm name:

<login-config>
  <auth-method>FORM</auth-method> 
		<realm-name>gatein-domain</realm-name> 
		<form-login-config>
		...
		</form-login-config>
	</login-config>

rest.war also needs to be modified to provide properly secured REST services.

<login-config>
  <auth-method>BASIC</auth-method> 
  <realm-name>gatein-domain</realm-name> 		
</login-config>

Note

This change is very important as it allows to secure the downlaod of files via WEBDAV.

In eXo Platform, the password encryption key of the RememberMe token is always a default key defined in the codeckey.txt file and this key is generated at the first bootstrap.

File location

File Tomcat Jboss
codeckey.txt TOMCAT-HOME/gatein/conf/codec JBOSS-HOME/server/<PROFILE>/conf/gatein/codec

Update the key

The administrators can simply update the key without doing any configuration as follows:

1. Remove the codeckey.txt file.

2. Restart the server.