Delivery Tier Authentication Configuration

Introduction

Goal

Learn about the delivery tier's default authentication configuration.

Background

Hippo's delivery tier (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's Form Login Pages
• Customize the Delivery Tier Authentication Provider.

JAAS Login Configuration

Default Configuration

Hippo's delivery tier 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:

1. Configure the LoginModule implementation class in a JAAS login configuration file:
   site/src/main/resources/org/example/login.conf

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

2. Configure the location of the JAAS login configuration file in hst-config.properties:
   site/src/main/webapp/WEB-INF/hst-config.properties

   java.security.auth.login.config = classpath:/org/example/login.conf

The authentication realm and valve are configured in the application context configuration.

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.

site/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>

Servlet Configuration

The form-based authentication is enabled and processed by the LoginServlet configured in site/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 Hippo 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/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 site/src/main/resources/META-INF/hst/security/skin/screen.css.

HTTPS vs HTTP Login

By default, all delivery tier 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 [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 tier 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!