Delivery Tier Authentication Configuration

This documentation page is possibly outdated and is scheduled to be verified and updated.

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:

Alternatively, the HST Spring Security Support forge project provides an authentication provider against the repository and a Spring Security-aware Security Valve in order to let you leverage Spring Security instead of the default JAAS-based security module.

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.

Note that the Realm is configured in site/webapp/src/main/webapp/META-INF/context.xml, not in conf/context.xml!

Multiple Delivery Webapps

In projects containing multiple delivery webapps it's possible to define a different LoginModule implementation for each by adding additional apps in conf/login.conf and corresponding realms in site/webapp/src/main/webapp/META-INF/context.xml.

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:

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!

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?