Migration to Native JAAS Security

This article explains how to migrate to the security mechanism of version 2.1.

See details about new authentication: Security Service

1 JAAS configuration

Before 2.1, JAAS configuration for Tomcat (jaas.conf) would look like this :

exo-domain {
  org.exoplatform.services.organization.auth.ExoLoginJAASLoginModule required;
  org.exoplatform.services.organization.auth.ExoBroadcastJAASLoginModule required;
}

Starting with Core 2.1, we get rid of login broadcasting, instead we use native JAAS login module chaining mechanism. the result is a simplified configuration.

1.1 eXo native authentication

By default, any eXo bundle is configured with the eXo native authentication. It is a flexible mechanism that lets you authenticate against one of several sources such as eXo user DB, NTLM or PAM. With it, you can even plug your own authentication by implementing the org.exoplatform.services.security.Authenticator.

The JAAS configuration of eXo native authentication for each supported AS straightforward.

1.1.1 Tomcat

Simply configure jaas.conf as:

exo-domain {
  org.exoplatform.services.security.j2ee.TomcatLoginModule required;
}

1.1.2 JBoss

• org.exoplatform.services.security.j2ee.JbossLoginModule

1.1.3 JonAS

• org.exoplatform.services.security.j2ee.JonasLoginModule

1.1.4 Websphere

1.2 External Authentication

eXo native authentication is suitable to get up and running fast, or when you can implement an Authenticator. However, if you already have a JAAS LoginModule at your disposal, you may want to reuse it. For those cases, eXo provides the org.exoplatform.services.security.jaas.IdentitySetLoginModule. This alternative login module is made to be stacked after your own login module.

exo-domain {
  com.my.company.LoginModule1 required; 
  org.exoplatform.services.security.jaas.IdentitySetLoginModule required;
}

2 Old components configuration

1) Since version 2.1 the components org.exoplatform.services.organization.auth.AuthenticationService and org.exoplatform.services.security.SecurityService are removed. Remove entries like below from configuration.xml.

<component>
  <key>org.exoplatform.services.security.SecurityService</key>
  <type>org.exoplatform.services.security.impl.SecurityServiceImpl</type>
  <init-params>
    <value-param>
      <name>security.authentication</name>
      <value>standalone</value>
    </value-param>
  </init-params>
</component>

<component>
  <key>org.exoplatform.services.organization.auth.AuthenticationService</key>
  <type>org.exoplatform.services.organization.auth.impl.AuthenticationServiceImpl</type>
</component>

2) Authentication Listener is no more used for authentication. So exo.service.authentication.login events have to be removed from configuration.xml :

<external-component-plugins>
  <target-component>org.exoplatform.services.listener.ListenerService</target-component>
  <component-plugin>
    <name>exo.service.authentication.login</name>
    <set-method>addListener</set-method>
    <type>org.exoplatform.services.jcr.impl.core.access.JCRAuthenticationListener</type>
  </component-plugin>
</external-component-plugins>

3 New components configuration

Following components have to be configured instead:

1) Authenticator - necessary if you use eXo native authentication mechanism.

<component>
  <key>org.exoplatform.services.security.Authenticator</key>
  <type>org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl</type>
</component>

Default Authenticator is org.exoplatform.services.organization.auth.OrganizationAuthenticatorImpl. This Authenticator uses an implementation of eXo Organization Service. It might already be configured, see $EXO_PROJECTS/core/component/organization/api/src/main/java/conf/portal/configuration.xml

Also provided:

• org.exoplatform.services.security.pam.PAMAuthenticator (Pluggable Authentication Module)
• org.exoplatform.services.security.ntlm.NTLMAuthenticator (Windows authentication)

<component>
  <type>org.exoplatform.services.security.IdentityRegistry</type>
</component>

3) ConversationRegistry - mandatory component which keeps ConversationStates of authenticated users.

<component>
  <type>org.exoplatform.services.security.ConversationRegistry</type>
</component>

4) RoleExtractor - optional component used by the application server's Login Module to create a list of user roles from the list of user's group.

<component>
  <key>org.exoplatform.services.security.RolesExtractor</key>
  <type>org.exoplatform.services.security.impl.DefaultRolesExtractorImpl</type>
  <init-params>
    <value-param>
      <name>user.role.parent.group</name>
      <description>authentication service use this value to authenticate</description>
      <value>platform</value>
    </value-param>
  </init-params>
</component>

4 Configuration of web application

SetCurrentIdentityFilter is used to create the current user's conversation state, it stores current user's conversation state in a ThreadLocal variable. See Security Service for details.

Web.xml example:

<filter>
  <filter-name>SetCurrentIdentityFilter</filter-name>
  <filter-class>org.exoplatform.services.security.web.SetCurrentIdentityFilter</filter-class>
</filter>
.....
<filter-mapping>
  <filter-name>SetCurrentIdentityFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Important note: This filter should launch before org.exoplatform.frameworks.jcr.web.ThreadLocalSessionProviderInitializedFilter, basically, if the application does not require a special configuration, it is a good idea to configure the SetCurrentIdentityFilter as the first filter in the request chain.

The current conversation state can be retrieved at any time in the HTTP request lifecycle.

ConversationState state = ConversationState.getCurrent();

There are two kinds of logout session listeners:

• org.exoplatform.services.security.web.ConversationStateListener - common purpose logout listener and
• org.exoplatform.services.security.web.JAASConversationStateListener - JAAS specific logout listener (extends the first one).

<listener>
    <listener-class>org.exoplatform.services.security.web.JAASConversationStateListener</listener-class>
</listener>