12.1. JAAS Realm configuration

Warning

You are looking at documentation for an older release. Not what you want? See the current release documentation.

eXo Platform relies on JAAS for propagating the user identity and roles to the different applications deployed on the server. The JAAS realm is used by all eXo Platform applications and even propagated to the JCR for Access Control. Therefore, if you need to change the JAAS configuration, consider that your change impacts a lot and it may require you to unpackage and modify some .war files.

This section explains:

What is JAAS Realm?

The JAAS configuration requires a login.config file. This file contains one (or more) entry which is called a "Realm". Each entry declares a Realm name and at least one login module. Each login module consists of a Java class and some parameters which are specified by the class.

Below is the default Realm in the Tomcat bundle. In JBoss, it looks different but basically, the explanation is right for both.

gatein-domain {
  org.gatein.sso.integration.SSODelegateLoginModule required
    enabled="#{gatein.sso.login.module.enabled}"
    delegateClassName="#{gatein.sso.login.module.class}"
    portalContainerName=portal
    realmName=gatein-domain
    password-stacking=useFirstPass;
  org.exoplatform.services.security.j2ee.TomcatLoginModule required
    portalContainerName=portal
    realmName=gatein-domain;
};

In which:

gatein-domain is the Realm name which will be refered by applications. If you change this default name, you need to re-configure all the applications that use the Realm (listed later).
Two required login modules are: org.gatein.sso.integration.SSODelegateLoginModule and org.exoplatform.services.security.j2ee.TomcatLoginModule. The first, if authentication succeeds, will create an Identity object and save it into a shared state map, then the object can be used by the second.
These are some login modules available in eXo Platform. Refer to Existing login modules to understand how they match the login scenarios.

Declaring JAAS Realm in eXo Platform

In the Tomcat bundle

The default Realm is declared in the $PLATFORM_TOMCAT_HOME/conf/jaas.conf file. Its content is exactly the above example.
A "security domain" property in $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties (about this file, see Configuration overview) needs to be set equal to the Realm name:
```
exo.security.domain=gatein-domain
```

In the JBoss package

The default Realm is declared in the $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml file, at the following lines:


<security-domain name="gatein-domain" cache-type="default">

    <authentication>

        <!--

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

        -->

        <login-module code="org.exoplatform.services.security.j2ee.JBossAS7LoginModule" flag="required">

            <module-option name="portalContainerName" value="portal"/>

            <module-option name="realmName" value="gatein-domain"/>

        </login-module>

    </authentication>

</security-domain>

A "security domain" property in $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties (about this file, see Configuration overview) needs to be set equal to the Realm name:
```
exo.security.domain=gatein-domain
```

In the Native Installer

The same files are:

$NATIVE_INSTALLER_DIR/apps/exoplatform/conf/jaas.conf
$NATIVE_INSTALLER_DIR/apps/exoplatform/gatein/conf/exo.properties

List of applications using Realm

If an application (.war) uses the Realm for authentication and authorization, it will refer to the Realm name with either of the following lines.

In WEB-INF/jboss-web.xml:


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

In WEB-INF/web.xml:


<realm-name>gatein-domain</realm-name>

In META-INF/context.xml:
```
appName='gatein-domain'
```

As mentioned above, if you change "gatein-domain", you need to re-configure all the applications that use the Realm to refer to the new Realm. Here is the list of webapps and the files you need to re-configure:

In the Tomcat bundle or the Native Installer:

portal.war: /WEB-INF/jboss-web.xml, /WEB-INF/web.xml, /META-INF/context.xml.
rest.war: /WEB-INF/jboss-web.xml, /WEB-INF/web.xml.
ecm-wcm-extension.war: /WEB-INF/jboss-web.xml.
calendar-extension.war: /WEB-INF/jboss-web.xml.
forum-extension.war: /WEB-INF/jboss-web.xml.
wiki-extension.war: /WEB-INF/jboss-web.xml.
ecm-wcm-core.war: /WEB-INF/jboss-web.xml.
crash.war: /WEB-INF/crash/crash.properties in case you install the Crash add-on.

Note

The .war files are located under the $PLATFORM_TOMCAT_HOME/webapps folder. In case of the Native Installer, you will find these files unzipped in $NATIVE_INSTALLER_DIR/apache-tomcat/webapps.

In the JBoss package:

exo.portal.web.portal.war: /WEB-INF/jboss-web.xml, /WEB-INF/web.xml, /META-INF/context.xml.
exo.portal.web.rest.war: /WEB-INF/jboss-web.xml, /WEB-INF/web.xml.
calendar-extension-webapp.war: /WEB-INF/jboss-web.xml.
forum-extension-webapp.war: /WEB-INF/jboss-web.xml.
wiki-extension-webapp.war: /WEB-INF/jboss-web.xml.
ecms-core-webapp.war: /WEB-INF/jboss-web.xml.
ecms-packaging-wcm-webapp.war: /WEB-INF/jboss-web.xml.
crash.war: /WEB-INF/crash/crash.properties in case you install the Crash add-on.

Note

The .war files are located under the $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear folder.

See also