Two-Factor Authentication with Duo Security

Info: This feature requires a standard or premium Bloomreach Content license. Contact Bloomreach for details.

Bloomreach Content supports integration with Duo Security to add two-factor authentication (2FA) for CMS access. This integration verifies user identity with a second factor, such as a mobile device. This guide describes how to install and configure the Duo Security integration module.

Video Demonstration

A demonstration of logging in with two-factor authentication is available in the Log in Options section on the video page.

Prerequisites

A Duo Security account (sign up here)
Access to the Duo Security admin panel
Administrative access to your Bloomreach Content project
Ability to edit project dependencies and configuration files

1. Register with Duo Security

Sign up for a Duo Security account. Duo Security offers a free tier for up to ten users, which is suitable for evaluation and testing.
In the Duo Security admin panel, create a new Web SDK integration.
Enroll your users in Duo Security. Usernames in Duo Security must match the usernames in Bloomreach Content.

Info: To ensure secure communication, you must add the required certificates to the Tomcat truststore. See Configure the Bloomreach app in the DUO Admin Panel.

2. Add the Duo Security Integration Module Dependency

Add the Duo Security integration dependency to your cms/pom.xml file:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-2fa-duosecurity</artifactId>
</dependency>

Info: The add-on uses a specific version of the duo-universal-sdk (for example, version 1.1.3 with brXM 16.7.0). To use a newer version (if fully backward compatible), add it as a separate dependency:

<dependency>
  <groupId>com.duosecurity</groupId>
  <artifactId>duo-universal-sdk</artifactId>
  <version>1.3.1</version>
</dependency>

3. Configure the Duo Security Integration Servlet Filter

Add the following filter definition to cms/src/main/webapp/WEB-INF/web.xml:

<filter>
  <filter-name>DuoSecurity</filter-name>
  <filter-class>com.onehippo.cms7.twofa.duosecurity.DuoSecurityTwoFAFilter</filter-class>
</filter>

Add the filter mapping in the same file:

<filter-mapping>
  <filter-name>DuoSecurity</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Place this filter mapping above the CMS filter mapping. The DuoSecurity filter must execute first.

4. Configure the Duo Security Resource Servlet

To serve the Duo Security JavaScript file, add this servlet definition:

<servlet>
  <servlet-name>DuoWebResourcesServlet</servlet-name>
  <servlet-class>org.onehippo.cms7.utilities.servlet.ResourceServlet</servlet-class>
  <init-param>
    <param-name>jarPathPrefix</param-name>
    <param-value>/duoweb</param-value>
  </init-param>
  <init-param>
    <param-name>allowedResourcePaths</param-name>
    <param-value>
      ^/.*\..*
    </param-value>
  </init-param>
  <init-param>
    <param-name>cacheTimeout</param-name>
    <param-value>0</param-value>
  </init-param>
</servlet>

Add the servlet mapping:

<servlet-mapping>
  <servlet-name>DuoWebResourcesServlet</servlet-name>
  <url-pattern>/duoweb/*</url-pattern>
</servlet-mapping>

5. Configure the Duo Security Integration Servlet Filter Properties

Create a properties file (for example, 2fa.properties) with the following content:

duo.enabled=true
duo.contextPath=/cms
duo.akey=...
duo.ikey=...
duo.skey=...
duo.host=api-....duosecurity.com
// optional, since 14.7.1
// no entry or using 'from-request' will retrieve the URL from request headers 
duo.cmsUrl=from-request | https://cms.example.com

duo.contextPath is typically /cms when running locally, or / when running behind a proxy.
duo.ikey, duo.skey, and duo.host are available on the integration details page in the Duo Security admin panel.
duo.akey is a secret key (at least 40 characters) that you generate and keep private. For example, generate a random string in Python:

import os, hashlib 
print hashlib.sha1(os.urandom(32)).hexdigest()

Set duo.enabled to false to disable Duo Security 2FA. The default is true.

Specify the properties file location using the 2fa.config system property. This property must contain the absolute path to the properties file.

Hint: To pass the system property to Tomcat via Cargo, use -Dcargo.jvm.args="-D2fa.config=/path/to/2fa.properties"

6. Configure the Bloomreach App in the Duo Admin Panel

Add the required certificates to the Tomcat truststore to enable secure communication with Duo Security.

Download the root certificates from the DigiCert website, specifically:
- DigiCert SHA2 High Assurance Server CA
- DigiCert SHA2 High Assurance EV Root CA
These certificates may already be present if your environment interacts with external APIs.
Obtain the Duo server-specific certificate after creating your account. Use OpenSSL to retrieve the certificate:

echo | openssl s_client -showcerts -connect api-xxxxx.duosecurity.com:443 | openssl x509 > duo_cert.pem

In the Duo dashboard, select 'Protect an Application' and choose the 'Web SDK' type.

Verification

Attempt to log in to the CMS. You should be prompted for two-factor authentication via Duo Security.
Confirm that only users enrolled in Duo Security and with matching usernames can complete the login process.

Troubleshooting

If authentication fails, verify that the 2fa.properties file contains correct values for all required keys.
Ensure the Tomcat truststore includes the necessary DigiCert and Duo certificates.
Check that the filter mapping for DuoSecurity is placed before the CMS filter mapping in web.xml.
Review Tomcat logs for errors related to Duo Security authentication.