Security

This chapter introduces you to the security configuration in eXo Platform:

JAAS Realm configuration

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
    

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:

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

Note

The .war files are located under the $PLATFORM_TOMCAT_HOME/webapps folder.

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.

Note

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

Gadget proxy configuration

In eXo Platform, you could allow gadgets to load remote resources. However, this could be a potential security risk, as it will make the Gadget deployed as an open web proxy. So, you can set up the anonymous proxy to accept or deny certain hosts by configuring the ProxyFilterService.

Configuring the ProxyFilterService

By default, the proxy denies any host except the domain on which the gadget server is installed.

To specify domains that you want to allow or deny, modify the file:

  • $PLATFORM_TOMCAT_HOME/webapps/portal.war/WEB-INF/conf/common/common-configuration.xml (in Tomcat).
  • $PLATFORM_JBOSS_HOME/standalone/deployments/platform.ear/exo.portal.web.portal.war/WEB-INF/conf/common/common-configuration.xml (in JBoss).

The default configuration is:

<component>
    <key>org.exoplatform.web.security.proxy.ProxyFilterService</key>
    <type>org.exoplatform.web.security.proxy.ProxyFilterService</type>
    <init-params>
        <values-param>
        <!-- The white list -->
            <name>white-list</name>
            <!-- We accept anything not black listed -->
            <value>*</value>
        </values-param>
        <values-param>
            <name>black-list</name>
            <value>*.evil.org</value>
        </values-param>
    </init-params>
</component>

How does it work?

  • Any domain name in black list is denied.
  • Any domain name NOT in white list is denied.
  • Only domain names in white list and NOT in black list are allowed.

Multiple values can be added (by adding more value tags) and wildcards can be used, as in the following example:

<component>
    <key>org.exoplatform.web.security.proxy.ProxyFilterService</key>
    <type>org.exoplatform.web.security.proxy.ProxyFilterService</type>
    <init-params>
        <values-param>
            <name>white-list</name>
            <value>*.example.com</value>
            <value>www.example.net</value>
        </values-param>

        <values-param>
            <name>black-list</name>
            <value>evil.example.com</value>
        </values-param>
    </init-params>
</component>

Enabling HTTPS

In order to enable HTTPS, you can either:

In both cases, you must have a valid SSL certificate. For testing purpose, you can generate a self-signed SSL certificate should be used.

Generating a self-signed certificate

Generating a self-signed certificate can be done with OpenSSL. Once again, a self-signed certificate must be used only for testing purpose, never in production. Use the following command to generate the certificate:

openssl req -x509 -nodes -newkey rsa:2048 -keyout cert-key.pem -out cert.pem -subj '/O=MYORG/OU=MYUNIT/C=MY/ST=MYSTATE/L=MYCITY/CN=proxy1.com' -days 730

You will use cert-key.pem to certificate the Apache/Nginx server proxy1.com, so the part “CN=proxy1.com” is important.

Note

When using a self-signed certificate, users will need to point their browser to https://proxy1.com and accept the security exception.

Importing an SSL certificate in the JVM’s trust store

For gadgets to work, the SSL certificate must be imported in the JVM trust store:

  1. Because Java keytool does not accept PEM file format, you will need to convert cert-key.pem into DER format.

openssl x509 -outform der -in cert-key.pem -out cert-key.der

  1. Import your certificate to the JVM trust store using the following command:

keytool -import -trustcacerts -file cert-key.der -keystore $JAVA_HOME/jre/lib/security/cacerts -alias proxy1.com

Note

The default password of the JVM’s trust store is “changeit”.

Using a reverse proxy for HTTPS in front of eXo Platform

Apache or Nginx can both be used as a reverse proxy in front of eXo Platform. The role of the reverse proxy server is to catch HTTPS requests coming from the http clients (e.g web browsers) and to relay them to eXo Platform either via AJP or via HTTP protocol. The following diagram depicts the case described in this section:

image0

Note

At this stage, we assume you already have an SSL certificate, either issued by an official certification authority or self-signed (for testing).

The examples below will let you setup a basic installation with ssl enabled. You should fine tune your installation before opening it on the web. Mozilla provide a great site to help you to find a configuration adapted to your needs.

Configuring Apache

Before you start, note that for clarity, not all details of the Apache server configuration are described here. The configuration may vary depending on Apache version and your OS, so consult Apache documentation if you need.

Note

The supported version of Apache is 2.4 which should be used in a supported version of OS. You can learn more about supported environments here.

Required modules

You need mod_ssl, mod_proxy. They are all standard Apache2 modules, so no installation is required. You just need to enable them with the following command:

sudo a2enmod ssl proxy proxy_http headers

Configuring a virtual host for the SSL port

Add this to site configuration (you can override the default ssl site /etc/apache2/sites-enabled/default-ssl.conf or create your own site):

<VirtualHost *:80>
    ServerName proxy1.com
    Redirect / https://proxy1.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName proxy1.com
    ProxyPass / http://exo1.com:8080/
    ProxyPassReverse / http://exo1.com:8080/
    ProxyRequests Off
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}

    ProxyPass /cometd ws://exo1.com:8080/cometd max=200 acquire=5000 retry=5 disablereuse=on flushpackets=on

    SSLEngine On
    SSLCertificateFile /path/to/folder/from/certificate/cert.pem
    SSLCertificateKeyFile /path/to/folder/from/certificate/cert-key.pem
</VirtualHost>

Configuring Nginx

Instructions for installing Nginx can be found here. On Debian and Ubuntu you can install Nginx with the following command: apt-get install nginx.

Configure the server proxy1.com at port 443 like this (you can put the configuration in a file like /etc/nginx/sites-enabled/proxy1.com):

server {
    listen 80;
    server_name proxy1.com;

    # Redirect all HTTP requests to HTTPS with a 301 Moved Permanently response.
    return 301 https://$host$request_uri;
}

server {
    listen 443;
    server_name proxy1.com;
    ssl on;
    ssl_certificate /path/to/file/mycert.pem;
    ssl_certificate_key /path/to/file/mykey.pem;

    location / {
        proxy_pass http://exo1.com:8080;
    }
    location /cometd/cometd {
        proxy_pass http://exo1.com:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

}

The configuration here is a simple one and it works. For a more advanced configuration, you may want to read this blog post.

Configuring the HTTP connector

In both eXo Platform Tomcat and JBoss distributions, there is a default HTTP (8080) connector.

In any case, you should configure that connector so that eXo Platform is aware of the proxy in front of it.

  • In Tomcat

Set the following property in $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties file:

exo.base.url=https://proxy1.com

The connector is configured in $PLATFORM_TOMCAT_HOME/conf/server.xml. Add proxy parameters like this:

<Connector address="0.0.0.0" port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
  enableLookups="false" redirectPort="8443"
  connectionTimeout="20000" disableUploadTimeout="true"
  URIEncoding="UTF-8"
  compression="off" compressionMinSize="2048"
  noCompressionUserAgents=".*MSIE 6.*" compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript"
  proxyName="proxy1.com" proxyPort="443" scheme="https" />
  • In JBoss
  1. Set the following property in $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties file:

    exo.base.url=https://proxy1.com
    
  2. In $PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xml, add the property proxy-address-forwarding=”true” in the configuration of http-listener:

    <http-listener name="default" redirect-socket="https"
                            socket-binding="http" max-post-size="209715200"
                            proxy-address-forwarding="true"/>
    

After restarting the proxy and eXo Platform, you can test https://proxy1.com. If you are testing with dummy server names, make sure you created the hosts “proxy1.com” and “exo1.com” in the file /etc/hosts.

Running eXo Platform itself under HTTPS

In the previous section you learnt to configure a reverse proxy in front of eXo Platform, and it is the proxy which encrypts the requests and responses. Alternatively you can configure eXo Platform to allow HTTPS access directly, so no proxy between browsers and eXo Platform. See the following diagram :

image1

Configuring eXo Platform’s Tomcat

  1. Set the following property in $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties file:

    exo.base.url=https://exo1.com:8443
    
  2. Edit the $PLATFORM_TOMCAT_HOME/conf/server.xml file by commenting the following lines:

    <Connector address="0.0.0.0" port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
    enableLookups="false" redirectPort="8443"
    connectionTimeout="20000" disableUploadTimeout="true"
    URIEncoding="UTF-8"
    compression="off" compressionMinSize="2048"
    noCompressionUserAgents=".*MSIE 6.*" compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript" />
    
  3. Uncomment the following lines and edit with your keystoreFile and keystorePass values:

    <Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"
    keystoreFile="/path/to/file/serverkey.jks"
    keystorePass="123456"/>
    

After starting eXo Platform, you can connect to https://exo1.com:8443/portal. If you are testing with dummy server names, make sure you created the host “exo1.com” in the file /etc/hosts.

Configuring eXo Platform’s JBoss

To configure JBoss to run under HTTPS, you just need to set the following property in $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/exo.properties file:

exo.base.url=https://exo1.com:8443

After starting JBoss, you can connect to eXo Platform at https://exo1.com:8443/portal. If you are testing with dummy server names, make sure you created the host “exo1.com” in the file /etc/hosts.

Password encryption key of RememberMe

eXo Platform supports the “Remember My Login” feature. This guideline explains how the feature works, and how to update the password encryption key in server side for security purpose.

How the feature works?

If users select “Remember My Login” when they log in, their login information will be saved in both client and server sides:

  • A token is saved in the server side. The user password is encrypted and saved along with the token.
  • The token ID is sent back to the browser and saved in the “rememberme” cookie.

When the users visit the website for next time from the same browser on the same machine, they do not need to type their username and password. The browser sends the cookies, and the server validates it using the token. By that way, the login step is automatically completed.

Symmetric encryption of passwords

The user password is encrypted and stored along with the token.

The password encryption is built against JCA (Java Cryptography Architecture) and by default uses the AES algorithm. If you do not make your own configuration, a keystore is generated with defaulted attributes (such as file name, keypass, keysize). Thus, the feature works without any effort to configure anything. However, eXo Platform allows you to configure and use your own keystore to conform to your security policy.

How to customize the password

As you can see, the customization involves properties in exo.properties, jca-symmetric-codec.properties and a keystore. The goal of customization is to use your own keystore instead of the default one.

  1. Generate your own keystore file using keytool:

    ::

    keytool -genseckey -alias “customAlias” -keypass “customKeyPass” -keyalg “customAlgo” -keystore “customStore” -storepass “customStorePass” -storetype “customStoreType”

The file name will be the parameter keystore (“customStore” in the example). The valid value of algorithms and other parameters can be found here.

Then, place the generated file under gatein/conf/codec (in Tomcat) or standalone/configuration/gatein/codec (in JBoss).

  1. Update the jca-symmetric-codec.properties file with the parameters used in your keytool command:

    gatein.codec.jca.symmetric.alias=customAlias
    gatein.codec.jca.symmetric.keypass=customKeyPass
    gatein.codec.jca.symmetric.keyalg=customAlgo
    gatein.codec.jca.symmetric.keystore=customStore
    gatein.codec.jca.symmetric.storepass=customStorePass
    gatein.codec.jca.symmetric.storetype=customStoreType
    

Again, in case of eXo Platform package, you need to create the jca-symmetric-codec.properties file by yourself. You also need to put these two properties in exo.properties.

Updating password encryption key

The password encryption uses a keystore file. By default, the file is:

  • $PLATFORM_TOMCAT_HOME/gatein/conf/codec/codeckey.txt (in Tomcat).
  • $PLATFORM_JBOSS_HOME/standalone/configuration/gatein/codec/codeckey.txt (in JBoss).

To update the password encryption key, just remove the file, then restart the server. The keystore file will be re-created at the startup time.

Note

Updating the password encryption key causes the invalidation of existing tokens, so the users must re-login.

XSS Protection

Even if the XSS protection is handled in the PRODUCT development, some protections can be added on the server side to protect against external threats. They are essentially based on HTTP headers added to the responses to ask the modern browsers to avoid such attacks.

Additional configuration options can be found on the Content-security-Policy header definition.

Add XSS protection headers on Apache

To manipulate the response headers, the Apache module mod_headers must be activated and the following lines added on your configuration :

<VirtualHost *:80>
        ...
        # XSS Protection
        Header always append X-Frame-Options SAMEORIGIN
        Header always append X-XSS-Protection 1
        Header always append Content-Security-Policy "frame-ancestors 'self'"
        ...
        </VirtualHost>

Add XSS protection headers on Nginx

Add the following line in the http or server part of your Nginx configuration :

...
# XSS Protection
add_header X-Frame-Options SAMEORIGIN;
add_header X-XSS-Protection 1;
add_header Content-Security-Policy "frame-ancestors 'self'"
...

Secured MongoDB

For a quick setup, the add-on by default uses a local and none-authorization connection. However, in production it is likely you will secure your MongoDB, so authorization is required. Below are steps to do this.

Note

Read MongoDB documentation for MongoDB security. This setup procedure is applied for MongoDB 3.2.

  1. Start MongoDB and connect to the shell to create a database named admin. Add a user with role userAdminAnyDatabase.

    $ mongo
    >use admin
    >db.createUser({user: "admin", pwd: "admin", roles: [{role: "userAdminAnyDatabase", db: "admin"}]})
    >exit
    
  2. Edit MongoDB configuration to turn on authentication, then restart the server.

    # mongodb.conf
    # Your MongoDB host.
    bind_ip = 192.168.1.81
    
    # The default MongoDB port
    port = 27017
    
    # Turn on authentication
    auth=true
    
  3. Create a user having readWrite role in the database chat (you can name the database as your desire).

    $ mongo -port 27017 -host 192.168.1.81 -u admin -p admin -authenticationDatabase admin
    >use chat
    >db.createUser({user: "exo", pwd: "exo", roles: [{role: "readWrite", db: "chat"}]})
    >exit
    
  4. Verify the authentication/authorization of the new user:

    $ mongo -port 27017 -host 192.168.1.81 -u exo -p exo -authenticationDatabase chat
    >use chat
    >db.placeholder.insert({description: "test"})
    >db.placeholder.find()
    
  5. Create a configuration file containing these below parameters.

    dbName=chat
    dbServerHost=192.168.1.81
    dbServerPort=27017
    dbAuthentication=true
    dbUser=exo
    dbPassword=exo
    

Note

The parameters above correspond with the values used during creating authorization for MongoDB.

Rest Api exposure

eXo Platform exposes a list of Rest API methods. They are used internally by the deployed components but can also be used by your users.

Depending on your use cases, it could be (highly) recommanded to block the public access to some of them.

  • /rest/loginhistory/loginhistory/AllUsers : to avoid information disclosure and for performance issue.
  • /rest/private/loginhistory/loginhistory/AllUsers/* : to avoid information disclosure and for performance issue.
  • /rest/jcr/repository/collaboration/Trash : to avoid information disclosure.
  • /rest/ : Avoid rest services discovery.
  • /portal/rest : Avoid rest services discovery.

The following configuraton examples will allow you to block the previously listed Rest URLs with Apache or Nginx.

Block sensitive Rest urls with Apache

...

      # Block login history for performance and security reasons
      RewriteRule             "/rest/loginhistory/loginhistory/AllUsers"            - [L,NC,R=403]
      RewriteRule             "/rest/private/loginhistory/loginhistory/AllUsers/*"  - [L,NC,R=403]

      # Block access to trash folder
      RewriteRule             "/rest/jcr/repository/collaboration/Trash"            - [L,NC,R=403]

      # Don't expose REST APIs listing
      RewriteRule             "^/rest/?$"         -                   [NC,F,L]
      RewriteRule             "^/portal/rest/?$"  -                   [NC,F,L]
          ...

Block sensitive Rest urls with Nginx

You can create redirection rules in several ways with nginx, this is one of the possibles :

...

      # Block login history for performance and security reasons
      location /rest/loginhistory/loginhistory/AllUsers { return 403; }
      location /rest/private/loginhistory/loginhistory/AllUsers { return 403; }

      # Block access to trash folder
      location /rest/jcr/repository/collaboration/Trash { return 403; }

      # Don't expose REST APIs listing
      location ~ ^/rest/?$ { return 403; }
      location ~ ^/portal/rest/?$ { return 403; }

        ...