Two-Factor Authentication with Duo Security

Bloomreach Experience Manager offers integration with Duo Security to add a second layer of security for accessing the CMS, verifying the identity of the user using a second factor (like a phone or other mobile device). This document describes the steps required to install this integration module.

Watch video

You can see a demo of logging in with Two-Factor Authentication in the video about Log in Options on this video page.

Sign up with Duo Security

Before anything you need to sign up for a Duo Security account. At the time of this writing Duo Security is free for up to ten users so you can try it out and test it before committing yourself. In the Duo Security admin panel create a new Web SDK integration and enroll your users. Note that usernames in Duo Security must match the usernames in Bloomreach Experience Manager.

Add the Duo Security integration module dependency

Add the following dependency to the cms/pom.xml file:

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

Configure the Duo Security integration Servlet Filter

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

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

And in the same file the following filter mapping:

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

Configure the Duo Security Resource Servlet

To serve the duo security javascript file from the server you need to add the following 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>

And the following servlet mapping:

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

Configure the Duo Security integration Servlet Filter

The Duo Security integration servlet filter is configured with a separate properties file, for example with the name 2fa.properties. The properties file should contain the folllowing properties:

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

The context path is typically /cms when running locally and / when running behind a proxy, with no context path in the CMS URL.

The integration key (duo-ikey), the secret key (duo-skey) and the API host are listed on the integration details page in the Duo Security admin panel. The duo-akey is a key of at least 40 characters long that you keep secret from Duo Security and that you must generate yourself. You can for example generate a random string in Python with:

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

The duo-enabled parameter allows to disable duo security two-factor authentication by setting it to false. Default is  true.

The servlet filter can find the properties file when specified by the system property 2fa.config. The latter should contain the absolute path to the properties file.