Delivery Tier Authentication Configuration

Note: This documentation is scheduled for verification and may contain outdated information.

Overview

This page describes the default authentication configuration for the delivery tier in Bloomreach Content. It explains the standard setup, outlines customization options, and provides references to related topics.

Default Authentication in the Delivery Tier

Bloomreach Content's delivery framework (HST) provides built-in authentication using JAAS (Java Authentication and Authorization Service). Projects generated with the Maven archetype are pre-configured for form-based authentication over HTTPS. This uses the default LoginModule implementation included in HST.

When an unauthenticated user requests a page that requires authorization, the system redirects the user to the login form.

For alternative authentication approaches or further customization, see:

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

Info: The HST Spring Security Support forge project provides an authentication provider for the repository and a Spring Security-aware Security Valve. This allows you to use Spring Security instead of the default JAAS-based security module.

JAAS Login Configuration

Default JAAS Configuration

The delivery framework includes a default JAAS login configuration file. This file configures the default LoginModule implementation: org.hippoecm.hst.security.impl.DefaultLoginModule.

Using a Custom LoginModule

To use a different LoginModule implementation:

1. Place your custom LoginModule class in the site web application. For example: site/src/main/java/org/example/MyLoginModule.java.

2. Define the custom LoginModule in a JAAS login configuration file, such as conf/login.conf:

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

3. Specify the location of the JAAS login configuration file in the CMS web application's hst-config.properties (typically cms/webapp/src/main/webapp/WEB-INF/hst-config.properties):

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

4. Configure the authentication realm and valve in the application context file (site/webapp/src/main/webapp/META-INF/context.xml):

   <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>
   copy

   The realm name must match the value configured in web.xml. By default, the configuration uses form-based authentication with the FormAuthenticator valve. To use basic authentication, refer to Configure the Delivery Tier to Use Basic Authentication.

   Note: Configure the Realm in site/webapp/src/main/webapp/META-INF/context.xml, not in conf/context.xml.

   Hint: Multiple Delivery Webapps

   If your project includes multiple delivery web applications, you can define a separate LoginModule for each. Add additional app entries in conf/login.conf and configure corresponding realms in each webapp's META-INF/context.xml.

5. Ensure that login.conf is present in the Tomcat conf directory.

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

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

   • For deployment with a project distribution, add this entry to src/main/assembly/conf-component.xml:

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

Servlet Configuration

Form-based authentication is handled 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>
copy

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

<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>
copy

This configuration:

• Protects the /login/resource path, which is used internally by LoginServlet.
• Enables form-based authentication with specified login and error page paths.
• Requires the everybody role for the protected resource, used for authentication purposes only.

Login Form Skin Resources

Default Skin Resource Configuration

The default login form references built-in skin resources (such as CSS and images). These 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>
copy

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

Overriding Login Form CSS

To customize the appearance of the login form, override the default CSS:

• Create a file at src/main/resources/META-INF/hst/security/skin/screen.css in either the site/components or site/webapp module.
• The system will use your custom CSS instead of the default.

HTTPS vs HTTP Login

By default, all login requests in the delivery framework use HTTPS.

For a standard Cargo-based development environment, you can enable HTTPS by:

• Configuring Cargo for SSL/TLS
• Configuring Apache HTTP Server as a Reverse Proxy. See also Apache HTTP Server's SSL/TLS and mod_ssl documentation.

To use HTTP for login (for local development only):

1. Open the Console.

2. Navigate to /hst:hst/hst:configurations/hst:default/hst:sitemap/login.

3. 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
   copy

Testing the Login Form

To verify the login form:

1. Open your browser and navigate to /login/form. For a standard local project, use http://localhost:8080/site/login/form.
2. Enter a valid CMS username and password. The system should authenticate you.
3. If you enter invalid credentials, you will be redirected to /login/error.

To check authentication status in delivery framework components, call HttpServletRequest#getUserPrincipal(). If this method returns a non-null value, the user is authenticated.