# Security

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

JAAS Realm configuration Instructions on how to configure JAAS Realm.
Enabling HTTPS To enable security access, you can either run eXo Platform itself in HTTPS, or more commonly, use a reverse proxy like Apache.
Password encryption key of RememberMe Information about the file location and steps to update the "Remember My Login" password encryption key.
Anti Brute Force To configure the mechanim that protects against brute force attacks on password authentication.
XSS protection To activate XSS protection mechanisms.
SameSite Configuration To configure SameSite property for cookies
Securing the MongoDB Database How to secure eXo chat database.
Rest Api exposure List of REST API exposed by 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?
Declaring JAAS Realm in eXo Platform
List of applications using Realm

# What is JAAS Realm?

The JAAS configuration requires a login.config file (opens new window). 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.

    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

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

TIP

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

# Enabling HTTPS

In order to enable HTTPS, you can either:

Use a reverse proxy, such as Apache HTTPd or Nginx, to set up an HTTPS virtual host that runs in front of eXo Platform. This is the recommended way. Or:
Run eXo Platform itself over HTTPS

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

# Generating a self-signed certificate

Generating a self-signed certificate can be done with OpenSSL (opens new window). 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 mportant.

TIP

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

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

TIP

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 (opens new window) 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 (opens new window) if you need.

TIP

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 (opens new window).

# 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 (opens new window). 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. It can be tuned for advanced usages.

# Configuring the HTTP connector

In eXo Platform distribution, 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.

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

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

# Configuring eXo Platform's Tomcat

Set the following property in $PLATFORM_TOMCAT_HOME/gatein/conf/exo.properties file:
```
 exo.base.url=https://exo1.com:8443
```

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

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 (opens new window). 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 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 (opens new window) 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.

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 (opens new window). Then, place the generated file under gatein/conf/codec.

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

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.

WARNING

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

To prevent an attack based on brute force on login/password form, a built-in protection mechanism exists when multiple failed login attempts occur in a short time, the target user account is temporarily locked for a few minutes. When an account is locked, the user can immediately unlock it by resetting its password through a forgot password request. Two properties control the brute force attack protection mechanism. To configure it, you can add them in exo.properties. The following property determines the number of unsuccessful login attempts before the account is locked. The default value is attempts :

   exo.authentication.antibruteforce.maxAuthenticationAttempts=5

The following property determines how long (in minutes) an account is locked when the protection mechanism is triggered. The default value is 10 minutes :

   exo.authentication.antibruteforce.blockingTime=10

# 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 (opens new window).

# Add XSS protection headers on Apache

To manipulate the response headers, the Apache module mod_headers (opens new window) 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'"
    ...

# SameSite Configuration

SameSite is a property set on HTTP cookies. It can prevent some CSRF attacks. SameSite property can take one of theses values : None, Strict, and Lax

With value None, when a request is done on eXo Server, there is no verification on the referer. The cookies is used. For example, when a user receives a malicious email, containing a link forged to call a data-altering REST endpoint such as deleting a space, changing a permission, etc.. if the user has a valid session on eXo, clicking the link would alter data on their behalf. It is a CSRF attack.
With value Strict; when a request arrives on the eXo server, the referer is verified. If the referer has a different domain than the eXo server's domain, the request will not use the cookie. In the situation described above, the request would not be directly executed. The user would be redirected to the login page first. This behaviour is also applied for HTTP GET requests. So, when a user clicks on a link in a notification for example, he has to login again. With this value, all SSO systems (SAML, OAuth, OpenIdConnect ...), generally based on redirections between different hosts, will not work.
With value Lax; when a request arrives on the eXo server, the referer is also verified. If the referer has a different domain than the eXo server's domain, only GET requests will use the cookie. So this intermediate option allows to use links read only endpoints in email notifications, and still protect sensitive requests that may alter data.

By default, eXo uses Lax policy in order to have email notification links and SSO configurations work. It can be changed by configuration if a different value is needed. For that, rename file (if not already done) $PLATFORM_TOMCAT_HOME/bin/setenv-customize.sample.sh in $PLATFORM_TOMCAT_HOME/bin/setenv-customize.sh and then uncomment the line

    CATALINA_OPTS="$CATALINA_OPTS -Dexo.cookie.samesite=Lax"
    ...

Then modify the value to use None or Strict

For Windows environment, use the file $PLATFORM_TOMCAT_HOME/bin/setenv-customize.sample.bat

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

TIP

Read MongoDB documentation (opens new window) for MongoDB security. This setup procedure is applied for MongoDB 3.2 (opens new window).

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

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

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

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

Create a configuration file containing these below parameters.

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

TIP

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) recommended 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 configuration 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; }

← Add-ons Management JMX/REST Management →