{docbook}
<abstract>
<para>
This chapter presents the topics related to security configuration in eXo Platform:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Security.Change_JAAS_real">Changes on the JAAS realm</link></emphasis>
</para>
<para>
Changes on the JAAS realm in the Tomcat bundle, and common changes in <emphasis role="bold">configuration.properties</emphasis>, <emphasis role="bold">portal.war</emphasis>, and <emphasis role="bold">rest.war</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Security.Gadget_proxy_configuration">Gadget proxy configuration</link></emphasis>
</para>
<para>
Instructions on how to configure the ProxyFilterServie, and information of how the proxy service works.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Security.HTTPS_conf">HTTPS configuration</link> </emphasis>
</para>
<para>
Steps to configure the HTTPS configuration to run in the HTTPS mode.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Security.Key_Rememberme_token">Update the password encryption key of the RememberMe token</link></emphasis>
</para>
<para>
Information about the file location and steps to update the key of the <emphasis role="bold">RememberMe</emphasis> token.
</para>
</listitem>
</itemizedlist>
</abstract>
{docbook}

h1. Changes on the JAAS realm {anchor:id=ADM.Security.Change_JAAS_real}

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|../../reference/html/JCR.AccessControl.html].

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

Since the security configuration is highly dependent of the app server, each application sever is represented separately.

{docbook}
<para xml:id="ADM.Security.Tomcat">
<citetitle>
<emphasis role="bold">
Tomcat
</emphasis>
</citetitle>
</para>
{docbook}

In the Tomcat bundle, the JAAS configuration is controled by the _$PLATFORM\_TOMCAT\_HOME/conf/jaas.conf_:

{code}
gatein-domain {
  org.gatein.wci.security.WCILoginModule optional;
  org.exoplatform.services.security.jaas.SharedStateLoginModule required;
  org.exoplatform.services.security.j2ee.TomcatLoginModule required; 
};
{code}

Replace gatein-domain with your own domain name.

{note}
The PortalLoginModule module was designed to support the 'Remember me' feature. The password wrapped in PasswordCallback is the cookie token key.
The PortalLoginModule module uses the token key to retrieve Credential object from CookieTokenService, then injects the correct username/password into the shared state (accessible from subsequent login modules). For the moment, to keep the authentication work properly, the PortalLoginModule module is mandatory. On the other hand, to ensure that correct password is visible to other login modules, it should be the first one in the JAAS configuration file. 
The custom login module could retrieve the real password through the shared state instead of PasswordCallback.
{note}

{tip}
To learn more about the syntax, or realms in Tomcat, refer to the [JAAS tutorial|http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html] or [Tomcat Realm How-To|http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html] respectively.
{tip}

For JBoss, you need to edit the default JAAS security domain in the _portal.war!WEB-INF/jboss-web.xml_ file.

{code:xml}
<jboss-web>
  <security-domain>java:/jaas/gatein-domain</security-domain>
</jboss-web>
{code}

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

{code: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> 
{code}

{tip}
To learn more about the JBoss security configuration, refer to [JBoss Web Docs|http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform/5/html-single/Getting_Started_Guide/index.html#Basic_Configuration_Issues-Security_Service].
{tip}

{docbook}
<para xml:id="ADM.Security.Common_Changes">
<citetitle>
<emphasis role="bold">Common changes</emphasis>
</citetitle>
</para>
{docbook}

Finally, you need to do some common changes on both app servers as follows:

*configuration.properties* {anchor:id="ADM.Security.Configuration.properties"}

First, change the JAAS realm to match your own security constraints and then identify the entry named _exo.security.domain_ inside the _configuration.properties_ file.

{code}
# Realm name
exo.security.domain=gatein-domain
{code}

{note}
Internally, eXo Platform uses this setting to set a new variable named "portal.container.realm" that is then used in the Kernel configuration files, such as _platform-extension/WEB-INF/conf/platform/repository-configuration.xml_.
{note}

*portal.war* {anchor:id="ADM.Security.Portal.war"}

Inside _portal.war_, you should declare the Realm name in the _web.xml_ file:

{code:xml}
<login-config>
  <auth-method>FORM</auth-method> 
  <realm-name>gatein-domain</realm-name> 
  <form-login-config>
    ...
  </form-login-config>
</login-config>
{code}

*rest.war* {anchor:id="ADM.Security.rest.war"}

You also need to modify _rest.war_ to provide secured REST services properly.

{code:xml}
<login-config>
  <auth-method>BASIC</auth-method> 
  <realm-name>gatein-domain</realm-name> 		
</login-config>
{code}

{note}
This change is very important, allowing you to secure the file downloads via WEBDAV.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Gadget proxy configuration|#ADM.Security.Gadget_proxy_configuration]
* [HTTPS configuration|#ADM.Security.HTTPS_conf]
* [Update the password encryption key of the RememberMe token|#ADM.Security.Key_Rememberme_token]

h1. Gadget proxy configuration {anchor:id=ADM.Security.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 via configuring the _ProxyFilterService_. {anchor:id=ADM.Security.Gadget_proxy_configuration.Overview}

{docbook}
<para xml:id="ADM.Security.Gadget_proxy_configuration.Configuration">
<citetitle>
<emphasis role="bold">
Configure the ProxyFilterServie
</emphasis>
</citetitle>
</para>
{docbook}

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

To modify the filtering of domain names, modify the _portal.war/WEB-INF/conf/common/common-configuration.xml_ file.

The default configuration is set as below:

{code:xml}
<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>
      <!-- Accept anything not black listed -->
      <value></value>
    </values-param>
    <values-param>
      <name>black-list</name>
      <value></value>
    </values-param>
  </init-params>
</component>
{code}


{docbook}
<para xml:id="ADM.Security.Gadget_proxy_configuration.How_does_it_work">
<citetitle>
<emphasis role="bold">
How does it work?
</emphasis>
</citetitle>
</para>
{docbook}

The proxy service will deny access to any domain that is in the blacklist. If the domain name does not match any of the blacklist, the proxy filter will verify if the domain name is on the white list.
If the domain name is not defined in either the white list or black list, access will be denied.
Multiple values can be added for each list and wildcards can also be used.

The following is an example of a valid configuration: {anchor:id=ADM.Configuration.Gadget_proxy_configuration.Example}

{code:xml}
<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>
{code}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Changes on the JAAS realm|#ADM.Security.Change_JAAS_real]
* [HTTPS configuration|#ADM.Security.HTTPS_conf]
* [Update the password encryption key of the RememberMe token|#ADM.Security.Key_Rememberme_token]

h1. HTTPS configuration {anchor:id=ADM.Security.HTTPS_conf}
By default, eXo Platform runs in the HTTP mode. However, for the security purposes, you can configure it to run in the HTTPS mode.
This section explains how to configure HTTPS mode.

*1.* Generate your key.

If you do not have an X.509 certificate, you can make a simple certificate using the _keytool_ command.

*i.* Change the variables in the following command to suit your circumstances, then run it a terminal:
{code}
keytool -genkey -alias serverkeys -keyalg RSA -keystore server.keystore -storepass 123456 -keypass 123456 -dname "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY"
{code}

Your key will be stored in _server.keystore_.

*ii.* Import your key into the Sun JDK keystore (this is required to help running gadget features) with the following command:
{code}
keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts
{code}

*2.* Set up the Jboss configuration to use your new key.

*i.* Comment the following lines in _PLATFORM\_JBOSS\_HOME/server/<PROFILE>/deploy/jbossweb.sar/server.xml_:
{code:xml}
 <Connector port="8080" protocol="HTTP/1.1" maxHttpHeaderSize="8192"

         maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

         enableLookups="false" redirectPort="8443" acceptCount="100"

         connectionTimeout="20000" disableUploadTimeout="true"

         compression="on" URIEncoding="UTF-8" emptySessionPath="true"

         compressionMinSize="2048" address="${jboss.bind.address}"

         noCompressionUserAgents=".*MSIE 6.*"

         compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript"/>
{code}
*ii.* Uncomment the following line:
{code:xml}
<Connector protocol="HTTP/1.1" SSLEnabled="true"

         port="8443" address="${jboss.bind.address}"

         scheme="https" secure="true" clientAuth="false"

         keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"

         keystorePass="rmissl" sslProtocol = "TLS" />
{code}
Then, change the values of _keystoreFile_ and _keystorePass_ to values of your key.

*3.* Restart your server.
You can now access the portal via {{https\://<ServerAddress>:8443/portal}}.

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Changes on the JAAS realm|#ADM.Security.Change_JAAS_real]
* [Gadget proxy configuration|#ADM.Security.Gadget_proxy_configuration]
* [Update the password encryption key of the RememberMe token|#ADM.Security.Key_Rememberme_token]

h1. Update the password encryption key of the RememberMe token {anchor:id=ADM.Security.Key_Rememberme_token}
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.

{docbook}
<citetitle>
<para>
<emphasis role="bold">File location</emphasis>
</para>
</citetitle>
{docbook}

|| File || Tomcat || Jboss ||
| _codeckey.txt_ | _$PLATFORM\_TOMCAT\_HOME/gatein/conf/codec_. | _$PLATFORM\_JBOSS\_HOME/server/<PROFILE>/conf/gatein/codec_. |

{docbook}
<citetitle>
<para>
<emphasis role="bold">Update the key</emphasis>
</para>
</citetitle>
{docbook}

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

*1.* Remove the _codeckey.txt_ file.

*2.* Restart the server.

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Changes on the JAAS realm|#ADM.Security.Change_JAAS_real]
* [Gadget proxy configuration|#ADM.Security.Gadget_proxy_configuration]
* [HTTPS configuration|#ADM.Security.HTTPS_conf]