Delivery Tier Authentication Configuration

Introduction

Goal

Learn about the delivery tier's default authentication configuration.

Background

Bloomreach Experience Manager's delivery framework (HST) supports authentication through JAAS out-of-the-box. A standard implementation project created using the Maven archetype is configured for form-based authentication over HTTPS using the default LoginModule implementation included in the HST. Unauthenticated users requesting a page for which authorization is required are automatically redirected to the login form.

This page describes the default authentication configuration and some options for customization.

Separate pages describe how to:

• Configure the Delivery Tier to Use Basic Authentication
• Customize the Delivery Tier Authentication Provider
• Customize the Delivery Tier's Form Login Pages

JAAS Login Configuration

Default Configuration

Bloomreach Experience Manager's delivery framework provides a default JAAS login configuration file which configures the default LoginModule implementation org.hippoecm.hst.security.impl.DefaultLoginModule.

Configure a Custom Login Module

To configure a different LoginModule implementation:

Place the LoginModule implementation class in the site webapp, e.g. site/src/main/java/org/example/MyLoginModule.java.

Configure the LoginModule implementation class in a JAAS login configuration file, e.g. conf/login.conf:

HSTSITE {
   org.example.MyLoginModule required
   debug="false"
   storePrivCreds="true";
};

Configure the location of the JAAS login configuration file in the cms webapp's hst-config.properties, i.e. cms/webapp/src/main/webapp/WEB-INF/hst-config.properties:

java.security.auth.login.config = file:/${catalina.base}/conf/login.conf

The authentication realm and valve are configured in the application context configuration in site/webapp/src/main/webapp/META-INF/context.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Context crossContext="true">

  <Realm className="org.apache.catalina.realm.JAASRealm"
         appName="HSTSITE"
         userClassNames="org.hippoecm.hst.security.TransientUser"
         roleClassNames="org.hippoecm.hst.security.TransientRole"
         useContextClassLoader="true"/>
  <Valve className="org.apache.catalina.authenticator.FormAuthenticator" characterEncoding="UTF-8"/>
</Context>

The name of the realm must be the same as configured in web.xml. By default, the realm is configured to use form-based authentication using the FormAuthenticator valve. Alternatively, you may Configure the Delivery Tier to Use Basic Authentication.

Finally, make sure that login.conf ends up in the Tomcat conf directory.

For local development using cargo:run, in the project root pom.xml, add the following to build/plugins/plugin/configuration/configuration/configfiles:

<configfile>
  <file>${project.basedir}/conf/login.conf</file>
  <todir>conf/</todir>
  <tofile>login.conf</tofile>
</configfile>

For deployment using a project distribition, add the following to src/main/assembly/conf-component.xml:

<file>
  <source>conf/login.conf</source>
  <outputDirectory>conf</outputDirectory>
  <destName>login.conf</destName>
</file>

Servlet Configuration

The form-based authentication is enabled and processed by the LoginServlet configured in site/webapp/src/main/webapp/WEB-INF/web.xml:

<servlet>
  <servlet-name>LoginServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.security.servlet.LoginServlet
  </servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>LoginServlet</servlet-name>
  <url-pattern>/login/*</url-pattern>
</servlet-mapping>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>Login</web-resource-name>
    <url-pattern>/login/resource</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>everybody</role-name>
  </auth-constraint>
</security-constraint>
<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>HSTSITE</realm-name>
  <form-login-config>
    <form-login-page>/login/login</form-login-page>
    <form-error-page>/login/error</form-error-page>
  </form-login-config>
</login-config>
<security-role>
  <description>Default role of the repository</description>
  <role-name>everybody</role-name>
</security-role>

The configurations above set a default protected web resource path ( /login/resource), which is internally used by the LoginServlet, and form-based authentication with the internal login page path and error page path. Also, only for authentication purpose, the default role, "everybody", is required for the default protected web resource path ( /login/resource).

Login Form Skin Resources

Default Configuration

The default login form needs access to some built-in skin resources such as CSS and images. These resources are served by the SecurityResourceServlet configured in site/webapp/src/main/webapp/WEB-INF/web.xml:

<servlet>
  <servlet-name>SecurityResourceServlet</servlet-name>
  <servlet-class>org.springframework.js.resource.ResourceServlet</servlet-class>
  <init-param>
    <param-name>jarPathPrefix</param-name>
    <param-value>/META-INF/hst/security</param-value>
  </init-param>
</servlet>

<servlet-mapping>
  <servlet-name>SecurityResourceServlet</servlet-name>
  <url-pattern>/login/hst/security/*</url-pattern>
</servlet-mapping>

Override Login Form CSS

For simple customization of the look and feel of the login form, its default CSS can be overridden by creating a file src/main/resources/META-INF/hst/security/skin/screen.css in either the site/components or site/webapp module.

HTTPS vs HTTP Login

By default, all delivery framework login requests are over HTTPS. In a standard Cargo-based development environment, you have two options to use HTTPS:

• Configure Cargo for SSL/TLS
• Configure Apache HTTP Server as Reverse Proxy (also see Apache HTTP Server's SSL/TLS and mod_ssl documentation).

Alternatively, you may configure login over HTTP instead (in local development environments only!), following the instructions below.

Using the Console, browse to the default login sitemap item at /hst:hst/hst:configurations/hst:default/hst:sitemap/login.

Change the value of the hst:scheme property from https to http.

/hst:hst/hst:configurations/hst:default/hst:sitemap:
  /login:
    jcr:primaryType: hst:sitemapitem
    hst:scheme: http

Test the Login Form

Point your browser to /login/form. In a standard project running in a local development environment that would be http://localhost:8080/site/login/form.

Enter a CMS username and password to sign in. You will be able to get authenticated.

If you enter an incorrect username or password, you will be redirected to the default error page, /login/error.

In your delivery framework components, you can check if the current user is authenticated by calling HttpServletRequest#getUserPrincipal(). If the method returns a non-null value, then the user is authenticated!