Security best practices

This section describes recommended practices to improve the security of an OpenKM installation, especially in production environments. It covers protecting sensitive configuration values, securing network communications, and auditing activity within the application.

Password Encryption in openkm.properties

The openkm.properties file may contain several passwords in plain text. In a production environment, it is strongly recommended to store these values in encrypted form rather than in plain text. The most relevant properties are:

OpenKM provides a built-in utility to encrypt these values, available at Administration > Utilities > Password encryption. This utility must be used to generate the encrypted value that must be set in openkm.properties, rather than writing the password in plain text. For more details about how to use this utility, see Password encryption.

Secure Communications (TLS/SSL)

All communications with OpenKM should be encrypted using HTTPS. Running the application over plain HTTP in a production environment exposes login credentials, session cookies, and document content to interception on the network. It is strongly recommended to place OpenKM behind a reverse proxy configured with a valid TLS/SSL certificate, so that all traffic between clients and the server is encrypted.

For step-by-step instructions on how to configure this, see Configuring Apache HTTPS Reverse-Proxy.

Secure, HttpOnly and SameSite Cookie Attributes

Beyond encrypting the transport channel, the session cookie itself can be hardened with additional attributes set in the Set-Cookie HTTP response header. These attributes are enforced by the browser and reduce the impact of common attacks such as cookie theft via XSS, cookie interception over unencrypted connections, and cross-site request forgery (CSRF).

These attributes are not part of the OpenKM application and must be configured at the application server level, without modifying OpenKM itself.

HttpOnly and Secure are configured in tomcat/conf/web.xml (or in the application's own web.xml), inside the session-config element:

<session-config>
    <session-timeout>30</session-timeout>
    <cookie-config>
        <http-only>true</http-only>
        <secure>true</secure>
    </cookie-config>
</session-config>

SameSite is not part of this element and must be configured separately through the CookieProcessor, either in tomcat/conf/context.xml (applies to every web application deployed in that Tomcat instance) or in a context file scoped to a single application (applies only to that application):

<Context>
    <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
                      sameSiteCookies="strict" />
</Context>

Because each OpenKM installation typically runs on its own Tomcat instance, these settings can be adjusted per environment. For example, Secure should be left disabled on installations that are not yet served over HTTPS, and installations that embed OpenKM in an iframe from another domain should use SameSite=None together with Secure instead of Strict.

Auditing and Event Logging

OpenKM provides a complete audit trail of the actions performed within the application. Practically every action performed against the document management repository can be audited, and the level of detail recorded is configurable.

By default, OpenKM already audits the most relevant actions, which cover the most common auditing needs. The default audited actions are:

LOGIN
LOGIN_FAILED
LOGOUT
CREATE_.*
DELETE_.*
PURGE_.*
MOVE_.*
COPY_.*
SEND_MAIL_.*
DOWNLOAD_.*
ADMIN_CONFIG_.*
CHECKOUT_DOCUMENT
CHECKIN_DOCUMENT
GET_DOCUMENT_CONTENT.*
ADD_PROPERTY_GROUP
REMOVE_PROPERTY_GROUP
SET_PROPERTY_GROUP_PROPERTIES

This default level can be increased to audit additional actions if required. For more information about how the activity log works and how to configure the audited actions, see Activity log.

In addition to the application-level audit trail, administrators should also consider enabling auditing at the operating system level (for example, file system access, authentication, and system calls on the server hosting OpenKM). This kind of auditing is independent of OpenKM and must be configured and managed at the operating system level.

Restricting Access to Document Templates

OpenKM can generate documents from templates in HTML, PDF, and ODT formats, using the FreeMarker templating engine to insert dynamic content. Since these templates are processed and executed on the server-side, a template containing malicious FreeMarker tags could be used as an attack vector against the server.

For this reason, it is strongly recommended that only application administrators have write permissions over the templates folder and its subfolders, so that regular users cannot create or modify templates. It is also recommended to keep this folder permanently audited, so that any change made to a template can be tracked and reviewed.